Wallet Detail

GET/gateway/v1/wallet/detail

Returns a wallet's cross-chain portfolio with selectable sub-resources (balance, tokens, labels, NFTs). Always includes per-chain USD breakdown across 15+ EVM chains.

Available fields (via `fields`): `balance`, `tokens`, `labels`, `nft`.

Lookup: by `address`. Partial failures return available fields with per-field error info. Returns 422 if `fields` is invalid.

Query Parameters

addressstringrequired

Wallet address (0x hex for EVM, base58 for Solana)

Example: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

chainenum<string>

Chain filter for `tokens`, `nft`, and `approvals`. When omitted, inferred from address format: 0x addresses query all EVM chains, base58 addresses query Solana.

Available options:ethereumpolygonbscavalanchearbitrumoptimismfantombasesolana

Example: ethereum

fieldsstring

Comma-separated sub-resources to include. Valid: `balance`, `tokens`, `labels`, `nft`, `approvals`. The `active_chains` field is always returned. `approvals` is opt-in (not in default) as it triggers additional upstream calls.

Example: balance,labels,approvals

Wallet Detail

const options = {method: 'GET'};

fetch('https://api.asksurf.ai/gateway/v1/wallet/detail?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&chain=ethereum&fields=balance,labels,approvals', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "$schema": "https://example.com/schemas/DataObjectResponseWalletDetailBody.json",
  "data": {
    "active_chains": [
      {
        "chain": "<string>",
        "chain_id": 123,
        "usd_value": 123
      }
    ],
    "approvals": [
      {
        "balance": 123,
        "chain": "<string>",
        "name": "<string>",
        "spenders": [
          {
            "allowance": 123,
            "spender_address": "<string>",
            "spender_name": "<string>"
          }
        ],
        "symbol": "<string>",
        "token_address": "<string>"
      }
    ],
    "errors": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ],
    "evm_balance": {
      "address": "<string>",
      "chain_balances": [
        {
          "chain": "<string>",
          "chain_id": 123,
          "usd_value": 123
        }
      ],
      "total_usd": 123
    },
    "evm_tokens": [
      {
        "balance": "<string>",
        "chain": "<string>",
        "is_verified": true,
        "logo_url": "<string>",
        "name": "<string>",
        "price": 123,
        "symbol": "<string>",
        "token_address": "<string>",
        "usd_value": 123
      }
    ],
    "labels": {
      "address": "<string>",
      "entity_name": "<string>",
      "entity_type": "<string>",
      "labels": [
        {
          "confidence": 123,
          "label": "<string>"
        }
      ]
    },
    "nft": [
      {
        "chain": "<string>",
        "collection_name": "<string>",
        "contract_address": "<string>",
        "image_url": "<string>",
        "name": "<string>",
        "token_id": "<string>",
        "usd_price": 123
      }
    ],
    "sol_balance": {
      "address": "<string>",
      "sol_balance": "<string>"
    },
    "sol_tokens": [
      {
        "balance": "<string>",
        "decimals": 123,
        "is_verified": true,
        "logo_url": "<string>",
        "name": "<string>",
        "symbol": "<string>",
        "token_address": "<string>"
      }
    ]
  },
  "meta": {
    "cached": true,
    "credits_used": 123,
    "empty_reason": "<string>"
  }
}