---
title: "Token balances held by a wallet address on one chain."
method: POST
path: "/v2/ops/crypto.wallet.assets"
tags: ["crypto"]
---

# Token balances held by a wallet address on one chain.

`POST /v2/ops/crypto.wallet.assets`

## Request

- Base URL: `https://api.agentkey.app`
- URL: `https://api.agentkey.app/v2/ops/crypto.wallet.assets`
- Auth: HTTP bearer

Lists the token positions of a wallet on one EVM chain with balance and, where the provider attaches them, USD price and value. Page with cursor. The chain's native coin may be excluded by the provider (see unsupported_fields and the method notes).

Fixed price: 0.2 credits per successful call, whichever provider serves it.

## Request body

- object
  - `address` string, required: Wallet address (0x-prefixed hex). ENS names are not resolved.
  - `chain` 'ethereum' | 'polygon' | 'bsc' | 'arbitrum' | 'optimism' | 'base' | 'avalanche': Chain to read positions on.
  - `cursor` string: Opaque pagination cursor from the previous response's next_cursor. Send the same query parameters with it.
  - `fields` string[]: Projection: keep only these dotted paths of data, e.g. ["items.id", "items.text"].
  - `include_raw` boolean: Attach the raw upstream payload as `raw` (not a stable contract; truncated above 256 KB).
  - `limit` integer: Maximum number of positions to return.
  - `provider` string: Shorthand for routing.only = [provider].
  - `routing` Routing: Provider routing override. order: try these providers first; only: restrict to these (equivalent to pinning); allow_fallbacks: false tries only the first eligible provider.
    - `allow_fallbacks` boolean: false = try only the first eligible provider.
    - `only` string[]: Restrict to these providers.
    - `order` string[]: Providers to try first, in order.
    - `strategy` 'auto': How eligible providers are ordered. auto = the method's curated order. fastest / stable / popular are specified but not implemented yet (400 until then). The price is fixed whatever the strategy; mutually exclusive with order.

## Response `200`

Success envelope

- WalletAssetPageEnvelope: Success envelope whose data is a WalletAssetPage.
  - `attempts` Attempt[], required
    - `error_type` string: validation | not_found | rate_limit | timeout | upstream_unauthorized | upstream_unavailable | provider_error
    - `provider` string, required: Provider slug.
    - `refunded` boolean: true when the reservation for this attempt was refunded.
    - `status` integer, required: HTTP status AgentKey mapped this attempt to (200 on success).
    - `took_ms` integer, required
    - `tool` string, required: Registry tool name (Provider/operation) that was called.
    - `upstream_status` integer: The provider's real HTTP status; absent when nothing was received.
  - `credits_charged` number, required: Credits charged for this call (the method's fixed price).
  - `data` object, required: One page of wallet positions.
    - `items` WalletAsset[], required
      - `balance` number, nullable, required: Decimal-adjusted balance (1.5 = one and a half tokens).
      - `balance_raw` string, nullable, required: Balance in the smallest unit exactly as the chain reports it (decimal or hex string), for callers that need full precision.
      - `chain` string, required: Chain slug the position lives on.
      - `price_usd` number, nullable, required: Current token price in USD when the provider attaches one.
      - `token` object, required
        - `address` string, nullable, required: Token contract address; null for the chain's native coin.
        - `decimals` integer, nullable, required: Token decimals when reported.
        - `logo_url` string, nullable, required: Logo image URL.
        - `name` string, nullable, required: Token name.
        - `symbol` string, nullable, required: Ticker symbol.
      - `value_usd` number, nullable, required: Position value in USD when the provider computes it.
    - `next_cursor` string, nullable, required: Opaque cursor for the next page; null when exhausted or the provider cannot page.
  - `op` string, required: Method name.
  - `op_version` integer, required: Method version that served the call.
  - `provider` string, required: Provider that actually served the call.
  - `raw` unknown
  - `raw_truncated` boolean
  - `request_id` string, required: Correlation id; quote it in support requests.
  - `took_ms` integer, required
  - `unsupported_fields` string[], required: Output paths this provider structurally does not supply; such fields are null for a different reason than 'missing on this record'.

## Other responses

- `400`: Validation error (unknown field, bad cursor, bad routing)
- `402`: Insufficient credits
- `404`: Not found (method, or upstream object)
- `429`: Rate limited upstream
- `502`: All providers failed
- `504`: Timed out

---

[API](https://skmtc.dev/agentkey/apis/agentkey-scenario-methods.md) - [All operations](https://skmtc.dev/agentkey/apis/agentkey-scenario-methods/llms.txt) - [OpenAPI document](https://skmtc.dev/agentkey/apis/agentkey-scenario-methods/revisions/a7cf5b682fdd?raw)