Referência

GET /v1/wallets/{address}/history

Devolve todos os trades de compra e venda da carteira.

Requisição

curl -N "https://veltrabot.com/v1/wallets/{address}/history" \
  -H "Authorization: Bearer YOUR_API_KEY"

Resposta

Uma chamada padrão transmite o histórico em NDJSON, um objeto JSON por linha. Os lotes de trades chegam como { "trades": [...] } assim que são obtidos, de modo que uma carteira grande vai sendo preenchida gradualmente sobre a mesma conexão aberta, sem chamadas extras. Uma linha final { "complete": true, "tradeCount": ..., "wallet": ..., "firstTrade": ... } encerra o stream.

{"trades":[{"signature":"43C6...aY1Ve2X","side":"sell","token":"Benny","tokenMint":"9xY2...pump","amountSol":0.0448,"amount":152340.12,"dex":"Pump.fun","blockTime":"2026-07-19T07:37:17+00:00"}, ...],"cursor":"8kQ2mZ...f0X"}
{"trades":[ ...mais trades conforme são obtidos... ],"cursor":"pW3nZ2...Kd9"}
{"complete":true,"tradeCount":354,"wallet":"BtDyZ4EF...AAu9","firstTrade":"2026-07-12T07:39:02+00:00"}

Cada trade traz amountSol (o valor do trade em SOL) e amount (a quantidade de token movimentada), além de tokenMint, o endereço de mint do token, uma chave estável por token já que símbolos podem colidir. Juntos, permitem calcular custo de aquisição e PnL realizado. Qualquer um dos campos numéricos pode ser null quando não for possível determiná-lo para um trade.

Leia a resposta linha a linha: acumule o campo trades de cada linha e pare ao chegar na linha que carrega complete. A maioria das carteiras é transmitida por completo nessa única chamada. Uma carteira grande demais para terminar em cerca de 55 segundos encerra com complete: false e um cursor, e o restante continua carregando em segundo plano.

Parar e retomar: feche a conexão a qualquer momento para interromper o stream (por exemplo, com um AbortController ou Ctrl-C). Cada linha de lote carrega um cursor, então para retomar de onde parou basta iniciar uma nova requisição com ?cursor= definido como o último cursor recebido (sem limit), e o stream continua exatamente daquele ponto.

Paginação

Prefere páginas discretas em JSON único em vez do stream? Passe limit e cada chamada devolve uma página JSON comum (não NDJSON): trades limitado a limit linhas (sem máximo) mais um cursor para a página seguinte. Reenvie o cursor exatamente como o recebeu para obter a próxima página, sem tentar lê-lo ou alterá-lo. Siga-o até que uma resposta omita cursor, o que só acontece quando complete é true.

É o limit que seleciona esse modo. Uma requisição com cursor mas sem limit retoma o stream NDJSON, então inclua limit em cada página de um percurso paginado.

limit delimita o que é cobrado. Ele limita a busca ao vivo: ?limit=100 obtém 100 trades e conta 100 no seu uso, em vez de indexar antecipadamente todo o histórico da carteira.

totalPages é omitido enquanto complete for false. Como o limit interrompe a busca mais cedo, o tamanho real de uma carteira só é conhecido quando o percurso termina, e tradeCount no meio do caminho significa "trades obtidos até agora", não o total da carteira. Em vez de informar uma contagem de páginas incorreta, deixamos o campo de fora: siga o cursor até ele desaparecer. Assim que complete for true, tanto tradeCount quanto totalPages descrevem o histórico completo.

Cada trade conta uma única vez no seu uso. Quando a paginação com um cursor relê trades que você já obteve, esses trades não são cobrados novamente.

curl "https://veltrabot.com/v1/wallets/{address}/history?limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://veltrabot.com/v1/wallets/{address}/history?limit=100&cursor=8kQ2mZ3rV9...tLf0X" \
  -H "Authorization: Bearer YOUR_API_KEY"

Chains

O endpoint cobre Solana, todas as principais chains EVM e a Tron. Acrescente ?chain=<slug> para escolher uma. O padrão é sol, então chamadas existentes de Solana continuam iguais. O endereço da carteira é validado contra a família de endereços da chain: base58 para Solana, 0x… para chains EVM e T… para Tron. Em chains que não são Solana, amountSol carrega a quantidade do token nativo (ETH/BNB/TRX e outros) em vez de SOL.

Suporte