Wallet balances on Base

Returns JSON with the ETH and ERC20 token balances of a wallet on Base, read on-chain in one block: 21 major tokens plus any you list.

Use when you need the ERC20 token balance or wallet balance of an address on Base for onchain data checks.

Do not use when you need Ethereum mainnet or other chains, NFTs, transaction history or USD values.

Price: 0.004 USDC per call (x402, eip155:8453). Typical response time: 1200 ms (p95).

Call it over HTTP (x402)

POST https://x402-gateway.blackwoodstate8.workers.dev/v1/wallet-balances. A request without payment gets 402 Payment Required with the PAYMENT-REQUIRED header; any x402 client signs an EIP-3009 authorization and retries with PAYMENT-SIGNATURE (or X-PAYMENT). Invalid input is answered with 400 and not charged.

curl -i -X POST https://x402-gateway.blackwoodstate8.workers.dev/v1/wallet-balances -H 'content-type: application/json' -d '{"address":"0x5A6c77758820182484EA8DE614FC65423E80749a"}'
Pay to0xbB2F227a85e9F7405614326CeD123230D708DD90
Asset0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (USDC)
Amount4000 atomic units (0.004 USDC)
Authorization window60 s

Call it over MCP

Streamable HTTP at https://x402-gateway.blackwoodstate8.workers.dev/mcp, tool wallet-balances_v1. Payment goes in _meta["x402/payment"]; without it the tool returns the payment requirements.

Input

FieldTypeMeaning
addressstringWallet address on Base (0x followed by 40 hex characters)
tokens (optional)arrayExtra ERC20 token addresses on Base to check, beyond the 21 major ones (up to 20)
includeZero (optional)booleanAlso list tokens with zero balance (false when omitted)

Example:

{
  "address": "0x5A6c77758820182484EA8DE614FC65423E80749a"
}

Output

Real example:

{
  "address": "0x5A6c77758820182484EA8DE614FC65423E80749a",
  "network": "eip155:8453",
  "blockNumber": 52713897,
  "native": {
    "symbol": "ETH",
    "balance": "0",
    "raw": "0"
  },
  "tokens": [
    {
      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "symbol": "USDC",
      "decimals": 6,
      "balance": "0.01",
      "raw": "10000"
    }
  ],
  "notTokens": [],
  "checkedTokens": 21
}
JSON Schema
{
  "type": "object",
  "properties": {
    "address": {
      "type": "string"
    },
    "network": {
      "type": "string",
      "const": "eip155:8453"
    },
    "blockNumber": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "native": {
      "type": "object",
      "properties": {
        "symbol": {
          "type": "string",
          "const": "ETH"
        },
        "balance": {
          "type": "string"
        },
        "raw": {
          "type": "string"
        }
      },
      "required": [
        "symbol",
        "balance",
        "raw"
      ],
      "additionalProperties": false
    },
    "tokens": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string"
          },
          "symbol": {
            "type": [
              "string",
              "null"
            ]
          },
          "decimals": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "balance": {
            "type": "string"
          },
          "raw": {
            "type": "string"
          }
        },
        "required": [
          "token",
          "symbol",
          "decimals",
          "balance",
          "raw"
        ],
        "additionalProperties": false
      }
    },
    "notTokens": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "checkedTokens": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "address",
    "network",
    "blockNumber",
    "native",
    "tokens",
    "notTokens",
    "checkedTokens"
  ],
  "additionalProperties": false
}

More

Free schema and example: GET https://x402-gateway.blackwoodstate8.workers.dev/v1/wallet-balances. OpenAPI 3.1 · llms.txt · All services