Saltar al contenido principal
POST
El cuerpo de la solicitud, el esquema de la respuesta y los ejemplos de esta página se generan a partir de la definición de OpenAPI. Scan recorre el historial de una dirección, conserva las transacciones que coinciden con tus criterios de match y analiza solo esas. Úsalo en lugar de paginar Historial de transacciones analizadas y filtrar del lado del cliente. De forma predeterminada, cada elemento de data usa la misma estructura de TransactionResult que devuelve Analizar transacciones. Configura returnShape para obtener solo las firmas coincidentes o solo un conteo. La respuesta también incluye un resumen de scan que indica hasta dónde llegó el escaneo y por qué se detuvo.

​
Cómo funciona Scan

  1. Scan obtiene el historial de la dirección en páginas de hasta 1,000 transacciones, en sortOrder, dentro de los límites de slot, time y firma que establezcas.
  2. Conserva las transacciones que coinciden con todos los criterios establecidos en match.
  3. Se detiene cuando ocurre primero uno de estos casos: se encuentran limit coincidencias (solo con la estructura predeterminada transactions), se escanean budget.maxScannedTransactions, se llega al final del historial o del intervalo, o se alcanza el límite de tiempo de la solicitud.
Un escaneo que se detiene antes de tiempo sigue siendo un 200. Vuelve a llamar con el paginationToken devuelto mientras haya uno, incluso cuando data esté vacío.

​
Criterios de coincidencia

match es obligatorio. Configura programs, mints o ambos. Si configuras ambos, una transacción debe coincidir con los dos.

​
Coincidencia por programa

programs enumera hasta 20 programas, cada uno como máximo una vez. Una transacción coincide cuando contiene una instrucción de cualquiera de ellos, de nivel superior o interna (CPI), dentro del scope del programa. Para cada programa, puedes restringir la coincidencia:
  • instructions: nombres de instrucciones de cualquier versión de la IDL del programa, tal como aparecen en la IDL o en snake_case. Si un nombre no se encuentra en las IDL del programa, se devuelve 400.
  • discriminators: prefijos de datos de instrucciones, cada uno de 1 a 8 bytes codificados en hexadecimal con un prefijo 0x opcional. Úsalos para programas sin una IDL.
  • Configura una lista o ambas. Con ambas, una instrucción coincide cuando es una de las instrucciones nombradas o sus datos comienzan con uno de los discriminadores. Omite ambas para que coincida cualquier instrucción del programa.
  • Cada lista acepta como máximo 50 entradas por programa.
Para confirmar los nombres de instrucciones decodificadas de un programa, usa el método describeProgram de Parsed Streams.

​
Coincidencia por acuñación

mints enumera hasta 20 objetos con la forma { "mint": "...", "scope": "address" }, cada acuñación como máximo una vez. Una transacción coincide cuando uno de sus saldos de tokens anteriores o posteriores corresponde a una de las acuñaciones, dentro del scope de esa acuñación. Cuando escanees una billetera para una acuñación, configura tokenAccounts como balanceChanged. De forma predeterminada, el historial omite las transacciones que solo involucran las cuentas de tokens de la billetera y no la billetera en sí, lo que incluye muchas transferencias de tokens entrantes.

​
Coincidencia con SOL nativo

SOL nativo no tiene saldos de tokens, por lo que Scan busca coincidencias según los lamports. Usa la acuñación de SOL nativo So11111111111111111111111111111111111111111 (SOL envuelto es So11111111111111111111111111111111111111112):
  • Con el alcance address, una transacción coincide cuando cambiaron los lamports de la dirección escaneada.
  • Con el alcance transaction, coincide cuando cambiaron los lamports de cualquier cuenta.
La comisión cobrada al pagador de la comisión no cuenta. Cada cuenta se compara de manera individual, por lo que los lamports que salen de una cuenta y regresan en la misma transacción no cuentan. La coincidencia con SOL nativo detecta el SOL que un programa paga sin una instrucción de transferencia, como una venta en Pump.fun. También detecta movimientos secundarios, como propinas de Jito y alquileres pagados o reembolsados desde cuentas.

​
Alcance de la coincidencia

Cada programa y cada acuñación admite un scope: Usa el alcance transaction cuando la dirección escaneada esté en la transacción, pero no en la instrucción o el saldo con el que buscas coincidencias. Por ejemplo, cuando la dirección solo paga la comisión, ejecuta una transacción multifirma o no aparece en una CPI de evento de Anchor. Para escanear la acuñación de un token en busca de transacciones que también contengan USDC, la entrada de USDC necesita el alcance transaction. La propiedad de la cuenta de tokens proviene del owner registrado en cada saldo de tokens. Las transacciones antiguas que no lo registran solo coinciden con el alcance address en el propio address.

​
Estructuras de retorno

returnShape establece qué contiene la respuesta para las coincidencias: signatures e count ignoran limit e rawTransaction. Devuelven todas las coincidencias del intervalo que escanea una solicitud, por lo que solo se detienen por windowEnd, budget o deadline. Para contar un historial completo, sigue llamando con paginationToken y suma scan.matchedTransactions. Cada elemento de data con returnShape: "signatures" tiene este aspecto:
Las tres estructuras tienen el mismo costo, ya que los créditos dependen de las páginas del historial escaneadas, no de lo que se devuelve.

​
Solicitudes de ejemplo

​
Compras y ventas de Pump.fun

Escanea el historial del programa Pump.fun en busca de instrucciones buy e sell:
Pump.fun también tiene variantes como buy_exact_sol_in, buy_v2 e sell_v2. Enumera todos los nombres de instrucciones con los que quieras buscar coincidencias.

​
Compras y ventas de un token

Para obtener las operaciones de Pump.fun de un token, escanea la dirección de acuñación del token en lugar del programa. El historial de la acuñación solo contiene la actividad de ese token, y cada instrucción de compra o venta enumera la acuñación como una cuenta, por lo que coincide con el alcance predeterminado address:
Para conservar solo las transacciones del token que también involucren una cuenta de tokens USDC, agrega USDC con el alcance transaction. Con el alcance predeterminado address, un saldo de USDC tendría que pertenecer a la dirección de acuñación, por lo que no habría coincidencias:

​
Operaciones de una billetera en dos programas

Enumera varios programas para que coincida una llamada a cualquiera de ellos. Esta solicitud devuelve solo como firmas las operaciones de Pump.fun y PumpSwap de una billetera:

​
Actividad de USDC de una billetera en un intervalo de tiempo

Escanea el historial de una billetera en busca de transacciones que involucraron USDC durante 2025. tokenAccounts: "balanceChanged" incluye transferencias que solo involucraron la cuenta de tokens USDC de la billetera:
Para obtener solo el número de transacciones coincidentes, agrega "returnShape": "count".

​
Movimientos de SOL de una billetera

Escanea una billetera en busca de transacciones que cambiaron su saldo de SOL, sin contar la comisión que pagó, durante 2025. Esto incluye el SOL que un programa pagó sin una instrucción de transferencia:

​
Paginación y motivos de detención

scan.stoppedOn indica por qué finalizó la solicitud: scan.scannedThrough proporciona el slot y la hora del bloque de la última transacción escaneada, para que puedas informar el progreso en historiales extensos. Un escaneo de una instrucción poco frecuente puede agotar su presupuesto sin encontrar una coincidencia. En ese caso, la respuesta tiene un arreglo data vacío y aun así devuelve un paginationToken, por lo que debes seguir escaneando:
Este bucle continúa el escaneo hasta agotar el historial:
scan-pumpfun-trades.js
Escanea la dirección más específica posible. Cada transacción del historial de la dirección cuenta para el presupuesto, por lo que, mientras menos transacciones no relacionadas tenga una dirección, más coincidencias encontrará cada solicitud.

​
Créditos

Cada escaneo cuesta 10 créditos más 1 crédito por cada página del historial escaneada. Una página contiene hasta 1,000 transacciones, por lo que un escaneo con el presupuesto predeterminado de 10,000 transacciones cuesta como máximo 20 créditos. Una página interrumpida por el límite de tiempo no se escanea ni se cobra. Cada respuesta informa su costo en scan.creditsCharged. Consulta Créditos para conocer los precios de los planes.

​
Errores

Los errores de nivel de solicitud devuelven un cuerpo JSON con un mensaje error, como {"error": "limit must be between 1 and 100"}. Un cuerpo con un campo desconocido, como includeRawTransaction (usa rawTransaction), o con mints como cadenas simples en lugar de objetos { "mint": "..." }, devuelve {"error": "invalid request payload"}.

​
Parámetros de la solicitud

​
string
requerido
Dirección cuyo historial se escanea.
​
object
requerido
Condiciones que debe cumplir una transacción. Configura programs, mints o ambos. Si configuras ambos, una transacción debe coincidir con los dos.
​
array
Programas con los que buscar coincidencias, como máximo 20 y cada uno como máximo una vez. Una transacción coincide cuando contiene una instrucción de cualquiera de ellos, de nivel superior o interna (CPI), dentro del scope del programa.
​
string
requerido
Dirección del programa.
​
array
Nombres de instrucciones de cualquier versión de la IDL del programa, tal como aparecen en la IDL o en snake_case. Como máximo 50. Se puede combinar con discriminators.
​
array
Prefijos de datos de instrucciones, cada uno de 1 a 8 bytes codificados en hexadecimal con un prefijo 0x opcional. Como máximo 50. Se puede combinar con instructions.
​
string
predeterminado:"address"
Qué instrucciones del programa cuentan. address solo cuenta las instrucciones con una cuenta que sea address, una cuenta de tokens que posea address o una cuenta de tokens cuya acuñación sea address, o todas las instrucciones cuando address sea el programa. transaction cuenta cualquier instrucción del programa en la transacción.
  • address
  • transaction
​
array
Acuñaciones con las que buscar coincidencias, como máximo 20 y cada una como máximo una vez. Una transacción coincide cuando uno de sus saldos de tokens anteriores o posteriores corresponde a una de estas acuñaciones, dentro del scope de la acuñación.
​
string
requerido
Dirección de acuñación del token. La acuñación de SOL nativo So11111111111111111111111111111111111111111 busca coincidencias según los cambios en lamports, en lugar de los saldos de tokens, sin contar la comisión.
​
string
predeterminado:"address"
Qué saldos de tokens de la acuñación cuentan. address solo cuenta los saldos cuya cuenta de tokens sea address o le pertenezca, o cuya acuñación sea address. Para SOL nativo, solo cuentan los cambios en los lamports de address. transaction cuenta cualquier saldo de la acuñación en la transacción. Para SOL nativo, cuenta un cambio en los lamports de cualquier cuenta.
  • address
  • transaction
​
string
predeterminado:"transactions"
Lo que contiene la respuesta para las coincidencias: transactions (coincidencias analizadas en data, hasta limit), signatures (signature, slot, transactionIndex e blockTime por coincidencia en data), o count (sin data; scan.matchedTransactions es el número de coincidencias). signatures e count ignoran limit e rawTransaction.
  • transactions
  • signatures
  • count
​
number
predeterminado:"100"
Número máximo de coincidencias que se devolverán con la estructura transactions, de 1 a 100.
​
object
Límites sobre la cantidad de historial que escanea una solicitud.
​
number
predeterminado:"10000"
Número máximo de transacciones que se escanearán en esta solicitud, de 1 a 10,000.
​
string
Escanea las transacciones anteriores a esta firma.
​
string
Escanea las transacciones posteriores a esta firma.
​
string
Cursor devuelto por un escaneo anterior. Su estructura es slot:transactionIndex.
​
string
predeterminado:"desc"
Orden en que se escanea el historial y se devuelven las coincidencias.
  • asc
  • desc
​
string
predeterminado:"confirmed"
Nivel de compromiso utilizado para obtener el historial. processed no es compatible.
  • confirmed
  • finalized
​
string
predeterminado:"succeeded"
Resultado de ejecución que se incluirá. El filtrado ocurre antes de buscar coincidencias, por lo que las transacciones excluidas no cuentan para el presupuesto.
  • succeeded
  • failed
  • any
​
string
predeterminado:"none"
Indica si se deben incluir las transacciones que solo hacen referencia a una cuenta de tokens que pertenece a address, no al propio address: none las omite, balanceChanged incluye las que cambian el saldo de la cuenta de tokens e all las incluye todas. Usa balanceChanged cuando escanees una billetera por acuñación.
  • none
  • balanceChanged
  • all
​
number
Slot mínimo en el que se puede evaluar la solicitud.
​
string
predeterminado:"none"
Codificación de la transacción original de Solana devuelta como rawTransaction en cada resultado exitoso, con la estructura getTransaction. Solo se aplica a la estructura transactions.
  • none
  • json
  • jsonParsed
  • base64
​
object
Límites de comparación del slot. Cada límite es opcional.
​
number
Busca valores mayores que este valor.
​
number
Busca valores mayores o iguales que este valor.
​
number
Busca valores menores que este valor.
​
number
Busca valores menores o iguales que este valor.
​
object
Límites de comparación de la hora del bloque en segundos Unix. Cada límite es opcional.
​
number
Busca valores mayores que este valor.
​
number
Busca valores mayores o iguales que este valor.
​
number
Busca valores menores que este valor.
​
number
Busca valores menores o iguales que este valor.

Autorizaciones

​
api-key
string
query
requerido

Cuerpo

application/json

Cuerpo de la solicitud para escanear el historial de una dirección en busca de transacciones coincidentes.

​
address
string
requerido

Dirección cuyo historial se escanea.

​
match
object
requerido

Criterios que debe cumplir una transacción. Establece programs, mints o ambos. Cuando estableces ambos, una transacción debe coincidir con los dos.

​
returnShape
enum<string>
predeterminado:transactions

Contenido de la respuesta para las coincidencias: transactions (coincidencias analizadas en data, hasta limit), signatures (signature, slot, transactionIndex y blockTime para cada coincidencia en data) o count (sin data; scan.matchedTransactions es el número de coincidencias). signatures y count ignoran limit y rawTransaction.

Opciones disponibles:
transactions,
signatures,
count
​
limit
integer
predeterminado:100

Número máximo de coincidencias que se devolverán con la estructura transactions, de 1 a 100.

Rango requerido: 1 <= x <= 100
​
budget
object

Límites sobre la cantidad de historial que escanea una solicitud.

​
beforeSignature
string

Escanea las transacciones anteriores a esta firma.

​
afterSignature
string

Escanea las transacciones posteriores a esta firma.

​
paginationToken
string

Cursor devuelto por un escaneo anterior. Su estructura es slot:transactionIndex.

​
sortOrder
enum<string>
predeterminado:desc

Orden en el que se escanea el historial y se devuelven las coincidencias.

Opciones disponibles:
asc,
desc
​
commitment
enum<string>
predeterminado:confirmed

Nivel de confirmación usado para obtener el historial. processed no es compatible.

Opciones disponibles:
confirmed,
finalized
​
status
enum<string>
predeterminado:succeeded

Resultado de ejecución que se incluirá. El filtrado ocurre antes de buscar coincidencias, por lo que las transacciones excluidas no cuentan para el presupuesto.

Opciones disponibles:
succeeded,
failed,
any
​
tokenAccounts
enum<string>
predeterminado:none

Indica si se incluyen transacciones que solo hacen referencia a una cuenta de tokens propiedad de address, pero no a address en sí: none las excluye, balanceChanged incluye las que cambian el saldo de la cuenta de tokens y all las incluye todas. Usa balanceChanged cuando escanees una billetera por acuñación.

Opciones disponibles:
none,
balanceChanged,
all
​
minContextSlot
integer

Slot mínimo en el que se puede evaluar la solicitud.

​
rawTransaction
enum<string>
predeterminado:none

Codificación de la transacción original de Solana devuelta como rawTransaction en cada resultado correcto, con la estructura de getTransaction. Solo se aplica a la estructura transactions.

Opciones disponibles:
none,
json,
jsonParsed,
base64
​
slot
object

Límites de comparación del slot. Cada límite es opcional.

​
time
object

Límites de comparación de la hora del bloque en segundos Unix. Cada límite es opcional.

Respuesta

Las coincidencias en el returnShape solicitado y un resumen del escaneo. Un resultado parcial sigue siendo un 200; continúa con paginationToken mientras se devuelva uno.

Las coincidencias en el returnShape solicitado y un resumen del escaneo.

​
data
object

Resultado del analizador para cada firma.

​
paginationToken
string

Cursor donde continúa el siguiente escaneo. No está presente cuando el escaneo llega al final del historial o de la ventana.

​
scan
object

Hasta dónde llegó el escaneo y por qué se detuvo.