Pular para o conteúdo principal
POST
O corpo da solicitação, o esquema da resposta e os exemplos desta página são gerados a partir da definição OpenAPI. A operação Scan percorre o histórico de um endereço, mantém as transações que correspondem aos seus critérios de match e analisa apenas essas transações. Use-a em vez de percorrer as páginas do Histórico de transações analisadas e filtrar no cliente. Por padrão, cada item em data usa o mesmo formato TransactionResult retornado por Analisar transações. Defina returnShape para obter apenas as assinaturas correspondentes ou apenas uma contagem. A resposta também inclui um resumo scan que informa até onde a varredura chegou e por que ela parou.

​
Como a operação Scan funciona

  1. A operação Scan busca o histórico do endereço em páginas de até 1.000 transações, em sortOrder, dentro dos limites de slot, time e assinatura que você definiu.
  2. Ela mantém as transações que correspondem a todos os critérios definidos em match.
  3. Ela para quando ocorre primeiro uma destas condições: limit correspondências encontradas (apenas para o formato padrão transactions), budget.maxScannedTransactions transações examinadas, fim do histórico ou da janela, ou limite de tempo da solicitação.
Uma varredura que para antecipadamente ainda é uma 200. Faça outra chamada com o paginationToken retornado enquanto ele estiver presente, mesmo quando data estiver vazio.

​
Critérios de correspondência

match é obrigatório. Defina programs, mints ou ambos. Quando você define ambos, uma transação deve corresponder aos dois.

​
Correspondência por programa

programs lista até 20 programas, cada um no máximo uma vez. Uma transação corresponde quando contém uma instrução de qualquer um deles, de nível superior ou interna (CPI), dentro do scope do programa. Para cada programa, você pode restringir a correspondência:
  • instructions: nomes de instruções de qualquer versão da IDL do programa, conforme escritos na IDL ou em snake_case. Um nome não encontrado nas IDLs do programa retorna 400.
  • discriminators: prefixos dos dados da instrução, cada um com 1 a 8 bytes codificados em hexadecimal e um prefixo 0x opcional. Use-os para programas sem uma IDL.
  • Defina uma das listas ou ambas. Com ambas, uma instrução corresponde quando é uma das instruções nomeadas ou quando seus dados começam com um dos discriminadores. Omita ambas para corresponder a qualquer instrução do programa.
  • Cada lista aceita no máximo 50 entradas por programa.
Para confirmar os nomes das instruções decodificadas de um programa, use o método describeProgram do Parsed Streams.

​
Correspondência por emissão

mints lista até 20 objetos no formato { "mint": "...", "scope": "address" }, cada emissão no máximo uma vez. Uma transação corresponde quando um de seus saldos de tokens anterior ou posterior pertence a uma das emissões, dentro do scope dessa emissão. Ao examinar uma carteira para uma emissão, defina tokenAccounts como balanceChanged. Por padrão, o histórico omite transações que envolvem apenas as contas de token da carteira, mas não a própria carteira, o que inclui muitas transferências de tokens recebidas.

​
Correspondência com SOL nativo

O SOL nativo não tem saldos de tokens. Portanto, a operação Scan faz a correspondência com base em lamports. Use a emissão do SOL nativo So11111111111111111111111111111111111111111 (o SOL encapsulado é So11111111111111111111111111111111111111112):
  • Com o escopo address, uma transação corresponde quando os lamports do endereço examinado mudam.
  • Com o escopo transaction, ela corresponde quando os lamports de qualquer conta mudam.
A taxa cobrada do pagador da taxa não conta. Cada conta é comparada individualmente. Portanto, lamports que saem de uma conta e retornam na mesma transação não contam. A correspondência de SOL nativo detecta SOL que um programa paga sem uma instrução de transferência, como em uma venda na Pump.fun. Ela também detecta movimentações incidentais, como gorjetas da Jito e aluguel pago por contas ou reembolsado delas.

​
Escopo da correspondência

Cada programa e cada emissão recebe um scope: Use o escopo transaction quando o endereço examinado estiver na transação, mas não na instrução ou no saldo que você está comparando. Por exemplo, o endereço apenas paga a taxa, executa uma transação multisig ou está ausente de uma CPI de evento do Anchor. Para examinar a emissão de um token em busca de transações que também tenham USDC, é necessário usar o escopo transaction na entrada de USDC. A propriedade da conta de token vem de owner registrado em cada saldo de tokens. Transações antigas que não o registram correspondem ao escopo address apenas no próprio address.

​
Formatos de retorno

returnShape define o que a resposta contém para as correspondências: signatures e count ignoram limit e rawTransaction. Eles retornam todas as correspondências no intervalo examinado por uma solicitação. Portanto, param apenas em windowEnd, budget ou deadline. Para contar um histórico inteiro, continue fazendo chamadas com paginationToken e some os valores de scan.matchedTransactions. Cada item em data com returnShape: "signatures" tem esta aparência:
Os três formatos têm o mesmo custo, pois os créditos dependem das páginas do histórico examinadas, não do que é retornado.

​
Exemplos de solicitações

​
Compras e vendas na Pump.fun

Examine o histórico do programa Pump.fun em busca das instruções buy e sell:
A Pump.fun também tem variantes como buy_exact_sol_in, buy_v2 e sell_v2. Liste todos os nomes de instruções aos quais você deseja corresponder.

​
Compras e vendas de um token

Para obter as negociações de um token na Pump.fun, examine o endereço de emissão do token em vez do programa. O histórico da emissão contém apenas a atividade desse token, e cada instrução de compra ou venda lista a emissão como uma conta. Portanto, ela corresponde ao escopo padrão address:
Para manter apenas as transações do token que também envolvem uma conta de token USDC, adicione USDC com o escopo transaction. Com o escopo padrão address, um saldo de USDC teria que pertencer ao endereço de emissão. Portanto, nada corresponderia:

​
Negociações de uma carteira em dois programas

Liste vários programas para corresponder a uma chamada a qualquer um deles. Esta solicitação retorna as negociações de uma carteira na Pump.fun e na PumpSwap apenas como assinaturas:

​
Atividade de USDC de uma carteira em um intervalo de tempo

Examine o histórico de uma carteira em busca de transações que envolveram USDC durante 2025. tokenAccounts: "balanceChanged" inclui transferências que envolveram apenas a conta de token USDC da carteira:
Para obter apenas o número de transações correspondentes, adicione "returnShape": "count".

​
Movimentações de SOL de uma carteira

Examine uma carteira em busca de transações que alteraram seu saldo de SOL, além da taxa paga, durante 2025. Isso inclui SOL que um programa pagou sem uma instrução de transferência:

​
Paginação e motivos de interrupção

scan.stoppedOn informa por que a solicitação terminou: scan.scannedThrough fornece o slot e o horário do bloco da última transação examinada, permitindo que você informe o progresso em históricos longos. Uma varredura por uma instrução rara pode esgotar seu orçamento sem encontrar uma correspondência. Nesse caso, a resposta tem um array data vazio e ainda retorna um paginationToken. Portanto, continue examinando:
Este loop continua examinando até esgotar o histórico:
scan-pumpfun-trades.js
Examine o endereço mais específico possível. Cada transação no histórico do endereço conta para o orçamento. Portanto, quanto menos transações não relacionadas um endereço tiver, mais correspondências cada solicitação encontrará.

​
Créditos

Cada varredura custa 10 créditos mais 1 crédito por página do histórico examinada. Uma página contém até 1.000 transações. Portanto, uma varredura com o orçamento padrão de 10.000 transações custa no máximo 20 créditos. Uma página interrompida pelo prazo não é examinada nem cobrada. Cada resposta informa sua cobrança em scan.creditsCharged. Consulte Créditos para ver os preços dos planos.

​
Erros

Erros no nível da solicitação retornam um corpo JSON com uma mensagem error, como {"error": "limit must be between 1 and 100"}. Um corpo com um campo desconhecido, como includeRawTransaction (use rawTransaction), ou com mints como strings simples em vez de objetos { "mint": "..." }, retorna {"error": "invalid request payload"}.

​
Parâmetros da solicitação

​
string
obrigatório
Endereço cujo histórico será examinado.
​
object
obrigatório
O que uma transação deve corresponder. Defina programs, mints ou ambos. Quando ambos são definidos, uma transação deve corresponder aos dois.
​
array
Programas aos quais corresponder, no máximo 20, cada um no máximo uma vez. Uma transação corresponde quando contém uma instrução de qualquer um deles, de nível superior ou interna (CPI), dentro do scope do programa.
​
string
obrigatório
Endereço do programa.
​
array
Nomes de instruções de qualquer versão da IDL do programa, conforme escritos na IDL ou em snake_case. No máximo 50. Pode ser combinado com discriminators.
​
array
Prefixos dos dados da instrução, cada um com 1 a 8 bytes codificados em hexadecimal e um prefixo 0x opcional. No máximo 50. Pode ser combinado com instructions.
​
string
padrão:"address"
Quais instruções do programa contam. address conta apenas instruções com uma conta que seja address, uma conta de token pertencente a address ou uma conta de token cuja emissão seja address, ou todas as instruções quando address é o programa. transaction conta qualquer instrução do programa na transação.
  • address
  • transaction
​
array
Emissões às quais corresponder, no máximo 20, cada uma no máximo uma vez. Uma transação corresponde quando um de seus saldos de tokens anterior ou posterior pertence a uma dessas emissões, dentro do scope da emissão.
​
string
obrigatório
Endereço de emissão do token. A emissão do SOL nativo So11111111111111111111111111111111111111111 corresponde com base em alterações de lamports em vez de saldos de tokens, sem contar a taxa.
​
string
padrão:"address"
Quais saldos de tokens da emissão contam. address conta apenas saldos cuja conta de token seja address ou pertença a ela, ou cuja emissão seja address. Para SOL nativo, apenas alterações nos lamports de address contam. transaction conta qualquer saldo da emissão na transação. Para SOL nativo, uma alteração nos lamports de qualquer conta conta.
  • address
  • transaction
​
string
padrão:"transactions"
O que a resposta contém para as correspondências: transactions (correspondências analisadas em data, até limit), signatures (signature, slot, transactionIndex e blockTime por correspondência em data) ou count (sem data; scan.matchedTransactions é o número de correspondências). signatures e count ignoram limit e rawTransaction.
  • transactions
  • signatures
  • count
​
number
padrão:"100"
Número máximo de correspondências a retornar com o formato transactions, de 1 a 100.
​
object
Limites da quantidade de histórico que uma solicitação examina.
​
number
padrão:"10000"
Número máximo de transações a examinar nesta solicitação, de 1 a 10.000.
​
string
Examine transações anteriores a esta assinatura.
​
string
Examine transações posteriores a esta assinatura.
​
string
Cursor retornado por uma varredura anterior. O formato é slot:transactionIndex.
​
string
padrão:"desc"
Ordem na qual o histórico é examinado e as correspondências são retornadas.
  • asc
  • desc
​
string
padrão:"confirmed"
Nível de compromisso usado para buscar o histórico. processed não é compatível.
  • confirmed
  • finalized
​
string
padrão:"succeeded"
Resultado de execução a incluir. A filtragem ocorre antes da correspondência. Portanto, as transações excluídas não contam para o orçamento.
  • succeeded
  • failed
  • any
​
string
padrão:"none"
Define se devem ser incluídas transações que referenciam apenas uma conta de token pertencente a address, mas não o próprio address: none as omite, balanceChanged inclui aquelas que alteram o saldo da conta de token e all inclui todas. Use balanceChanged ao examinar uma carteira por emissão.
  • none
  • balanceChanged
  • all
​
number
Slot mínimo no qual a solicitação pode ser avaliada.
​
string
padrão:"none"
Codificação da transação original da Solana retornada como rawTransaction em cada resultado bem-sucedido, no formato getTransaction. Aplica-se apenas ao formato transactions.
  • none
  • json
  • jsonParsed
  • base64
​
object
Limites de comparação de slots. Cada limite é opcional.
​
number
Corresponde a valores maiores que este valor.
​
number
Corresponde a valores maiores ou iguais a este valor.
​
number
Corresponde a valores menores que este valor.
​
number
Corresponde a valores menores ou iguais a este valor.
​
object
Limites de comparação do horário do bloco em segundos Unix. Cada limite é opcional.
​
number
Corresponde a valores maiores que este valor.
​
number
Corresponde a valores maiores ou iguais a este valor.
​
number
Corresponde a valores menores que este valor.
​
number
Corresponde a valores menores ou iguais a este valor.

Autorizações

​
api-key
string
query
obrigatório

Corpo

application/json

Corpo da solicitação para verificar o histórico de um endereço em busca de transações correspondentes.

​
address
string
obrigatório

Endereço cujo histórico é verificado.

​
match
object
obrigatório

O que uma transação deve corresponder. Defina programs, mints ou ambos. Quando ambos são definidos, uma transação deve corresponder aos dois.

​
returnShape
enum<string>
padrão:transactions

O que a resposta contém para as correspondências: transactions (correspondências analisadas em data, até limit), signatures (signature, slot, transactionIndex e blockTime por correspondência em data) ou count (sem data; scan.matchedTransactions é o número de correspondências). signatures e count ignoram limit e rawTransaction.

Opções disponíveis:
transactions,
signatures,
count
​
limit
integer
padrão:100

Número máximo de correspondências a retornar com o formato transactions, de 1 a 100.

Intervalo obrigatório: 1 <= x <= 100
​
budget
object

Limites da quantidade de histórico que uma solicitação verifica.

​
beforeSignature
string

Verifica transações anteriores a esta assinatura.

​
afterSignature
string

Verifica transações posteriores a esta assinatura.

​
paginationToken
string

Cursor retornado por uma verificação anterior. O formato é slot:transactionIndex.

​
sortOrder
enum<string>
padrão:desc

Ordem na qual o histórico é verificado e as correspondências são retornadas.

Opções disponíveis:
asc,
desc
​
commitment
enum<string>
padrão:confirmed

Nível de confirmação usado para buscar o histórico. processed não é compatível.

Opções disponíveis:
confirmed,
finalized
​
status
enum<string>
padrão:succeeded

Resultado da execução a ser incluído. A filtragem ocorre antes da correspondência, portanto, as transações excluídas não são contabilizadas no orçamento.

Opções disponíveis:
succeeded,
failed,
any
​
tokenAccounts
enum<string>
padrão:none

Indica se devem ser incluídas transações que referenciam apenas uma conta de token pertencente a address, e não o próprio address: none as exclui, balanceChanged inclui as que alteram o saldo da conta de token e all inclui todas. Use balanceChanged ao verificar uma carteira por emissão.

Opções disponíveis:
none,
balanceChanged,
all
​
minContextSlot
integer

Slot mínimo no qual a solicitação pode ser avaliada.

​
rawTransaction
enum<string>
padrão:none

Codificação da transação original da Solana retornada como rawTransaction em cada resultado bem-sucedido, no formato de getTransaction. Aplica-se apenas ao formato transactions.

Opções disponíveis:
none,
json,
jsonParsed,
base64
​
slot
object

Limites de comparação de slots. Cada limite é opcional.

​
time
object

Limites de comparação do horário do bloco em segundos Unix. Cada limite é opcional.

Resposta

As correspondências no returnShape solicitado e um resumo da verificação. Um resultado parcial ainda retorna 200; continue usando paginationToken enquanto ele for retornado.

As correspondências no returnShape solicitado e um resumo da verificação.

​
data
object

Per-signature parser result.

​
paginationToken
string

Cursor no qual a próxima verificação continua. Ausente quando a verificação chega ao fim do histórico ou da janela.

​
scan
object

Até onde a verificação avançou e por que parou.