Transaction History

GET/gateway/v1/wallet/history

Returns all on-chain transactions for a wallet, classified by type (send, receive, swap, approve) with native token value. For ERC-20 token transfers with token identity and USD value, use `wallet-transfers` instead.

Lookup: by `address`. Filter by `chain` — supports `ethereum`, `polygon`, `bsc`, `arbitrum`, `optimism`, `avalanche`, `fantom`, `base`.

Query Parameters

addressstringrequired

Wallet address — must be a raw 0x-prefixed hex address, not an ENS name

Example: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

chainenum<string>

Chain filter. Can be `ethereum`, `polygon`, `bsc`, `avalanche`, `arbitrum`, `optimism`, `fantom`, or `base`.

Available options:ethereumpolygonbscavalanchearbitrumoptimismfantombase

Example: ethereum

limitinteger

Results per page

Example: 20

offsetinteger

Pagination offset. This feed is cursor-paginated upstream and only the most recent ~1000 transactions are reachable; a larger offset returns an empty page with meta.empty_reason rather than an error. For deep history prefer the `before` cursor — its upstream cost is bounded by `limit` and independent of depth, whereas a large offset is emulated by walking the whole feed.

Example: 0

beforeinteger

Cursor for efficient deep pagination: return transactions strictly older than this Unix-seconds timestamp (exclusive). Pass the `timestamp` of the last item from the previous page; if items may share a second, pass that timestamp + 1 and de-duplicate on `tx_hash`. Unlike `offset` (which walks the feed), the number of upstream fetches is bounded by `limit` (DeBank returns up to 20 per page) and independent of how far back you page. Mutually exclusive with `offset`.

Example: 1704067200

sort_byenum<string>

Field to sort results by. The cursor-paginated upstream feed only supports `timestamp` correctly; unsupported values are rejected by the handler for correctness.

Available options:timestampvalue

Example: timestamp

orderenum<string>

Sort order. The cursor-paginated upstream feed only supports `desc` correctly; unsupported values are rejected by the handler for correctness.

Available options:ascdesc

Example: desc

includestring

Comma-separated enrichments to attach to each item. Currently valid: `labels` — adds `from_label` and `to_label` fields with entity information for each counterparty address.

Example: labels

Transaction History

const options = {method: 'GET'};

fetch('https://api.asksurf.ai/gateway/v1/wallet/history?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&chain=ethereum&limit=20&offset=0&before=1704067200&sort_by=timestamp&order=desc&include=labels', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "$schema": "https://example.com/schemas/DataResponseWalletHistoryItem.json",
  "data": [
    {
      "from_address": "<string>",
      "from_label": {
        "address": "<string>",
        "entity_name": "<string>",
        "entity_type": "<string>",
        "labels": [
          {
            "confidence": 123,
            "label": "<string>"
          }
        ]
      },
      "timestamp": 123,
      "to_address": "<string>",
      "to_label": {
        "address": "<string>",
        "entity_name": "<string>",
        "entity_type": "<string>",
        "labels": [
          {
            "confidence": 123,
            "label": "<string>"
          }
        ]
      },
      "tx_hash": "<string>",
      "tx_type": "<string>",
      "value": "<string>"
    }
  ],
  "meta": {
    "cached": true,
    "credits_used": 123,
    "empty_reason": "<string>",
    "has_more": true,
    "limit": 123,
    "offset": 123,
    "total": 123,
    "watermark": 123
  }
}