레퍼런스

GET /v1/wallets/{address}/history

해당 지갑의 모든 매수/매도 거래를 반환합니다.

요청

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

응답

기본 호출은 내역을 NDJSON으로 스트리밍합니다. 한 줄에 하나의 JSON 객체가 담기며, 거래 배치는 가져오는 즉시 { "trades": [...] } 형태로 도착합니다. 따라서 대형 지갑도 열려 있는 하나의 연결 위에서 추가 호출 없이 점진적으로 채워집니다. 마지막 줄 { "complete": true, "tradeCount": ..., "wallet": ..., "firstTrade": ... }가 스트림의 끝을 알립니다.

{"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":[ ...가져오는 대로 이어지는 거래... ],"cursor":"pW3nZ2...Kd9"}
{"complete":true,"tradeCount":354,"wallet":"BtDyZ4EF...AAu9","firstTrade":"2026-07-12T07:39:02+00:00"}

각 거래에는 amountSol(해당 거래의 SOL 가치)과 amount(이동한 토큰 수량), 그리고 tokenMint가 포함됩니다. 토큰 심볼은 중복될 수 있으므로 mint 주소가 토큰별 안정적인 키 역할을 합니다. 이 값들을 함께 쓰면 취득원가와 실현손익을 계산할 수 있습니다. 특정 거래에서 값을 확정할 수 없는 경우 두 숫자 필드는 null이 될 수 있습니다.

응답은 줄 단위로 읽으세요. 각 줄의 trades를 누적하다가 complete가 담긴 줄에서 멈추면 됩니다. 대부분의 지갑은 이 한 번의 호출로 전부 스트리밍됩니다. 약 55초 안에 끝내기 어려운 대형 지갑은 complete: false와 cursor로 종료되며, 나머지는 백그라운드에서 계속 로드됩니다.

중단과 재개: 언제든 연결을 닫아 스트림을 멈출 수 있습니다(예: AbortController 또는 Ctrl-C). 모든 배치 줄에 cursor가 담기므로, 마지막으로 받은 cursor를 ?cursor=에 넣어 새 요청을 시작하면(limit 없이) 정확히 그 지점부터 스트림이 재개됩니다.

페이지네이션

스트림 대신 개별 JSON 페이지를 원하시나요? limit을 전달하면 각 호출이 NDJSON이 아닌 일반 JSON 페이지를 반환합니다. trades는 limit 행으로 제한되고(상한 없음) 다음 페이지용 cursor가 함께 옵니다. 받은 cursor를 그대로 다시 보내 다음 페이지를 요청하세요. 내용을 해석하거나 변경하려 하지 마세요. 응답에서 cursor가 사라질 때까지 따라가면 되며, 이는 complete가 true일 때만 발생합니다.

이 모드를 선택하는 것은 limit입니다. cursor만 있고 limit이 없는 요청은 NDJSON 스트림을 재개하므로, 페이지네이션으로 순회할 때는 모든 페이지에 limit을 포함하세요.

limit은 과금 범위를 제한합니다. 실시간 조회량을 제한하므로 ?limit=100은 100건만 가져와 사용량에 100건을 반영하며, 지갑의 전체 내역을 미리 인덱싱하지 않습니다.

complete가 false인 동안에는 totalPages가 생략됩니다. limit이 조회를 조기에 멈추기 때문에 순회가 끝나기 전에는 지갑의 실제 크기를 알 수 없고, 순회 도중의 tradeCount는 지갑 총계가 아니라 "지금까지 가져온 거래 수"를 뜻합니다. 잘못된 페이지 수를 알리는 대신 해당 필드를 생략합니다. cursor가 사라질 때까지 따라가세요. complete가 true가 되면 tradeCount와 totalPages 모두 전체 내역을 나타냅니다.

모든 거래는 사용량에 한 번만 반영됩니다. cursor로 지갑을 넘겨보다가 이미 받은 거래를 다시 읽어도 중복 과금되지 않습니다.

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"

체인

이 엔드포인트는 Solana, 모든 주요 EVM 체인, Tron을 지원합니다. ?chain=<slug>를 추가해 선택하며 기본값은 sol이므로 기존 Solana 호출은 그대로 동작합니다. 지갑 주소는 해당 체인의 주소 체계에 맞춰 검증됩니다. Solana는 base58, EVM 체인은 0x…, Tron은 T…입니다. Solana가 아닌 체인에서는 amountSol이 SOL이 아니라 네이티브 토큰 수량(ETH/BNB/TRX 등)을 담습니다.

지원