> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentkey.app/llms.txt
> Use this file to discover all available pages before exploring further.

# crypto.wallet.assets

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



## OpenAPI

````yaml api-reference/openapi/v2.yaml POST /v2/ops/crypto.wallet.assets
openapi: 3.1.0
info:
  description: >-
    Fixed, versioned, provider-independent methods over AgentKey's upstream
    catalog. Each method has a stable name, input schema and output schema; the
    server picks the upstream provider, fails over, normalizes fields and
    refunds failed attempts. Every response names the provider that served it,
    the credits charged and every attempt made.
  title: AgentKey Scenario Methods
  version: '2'
servers:
  - url: https://api.agentkey.app
security: []
paths:
  /v2/ops/crypto.wallet.assets:
    post:
      tags:
        - crypto
      summary: Token balances held by a wallet address on one chain.
      description: >-
        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.
      operationId: crypto_wallet_assets
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                address:
                  description: >-
                    Wallet address (0x-prefixed hex). ENS names are not
                    resolved.
                  type: string
                chain:
                  default: ethereum
                  description: Chain to read positions on.
                  enum:
                    - ethereum
                    - polygon
                    - bsc
                    - arbitrum
                    - optimism
                    - base
                    - avalanche
                  type: string
                cursor:
                  description: >-
                    Opaque pagination cursor from the previous response's
                    next_cursor. Send the same query parameters with it.
                  type: string
                fields:
                  $ref: '#/components/schemas/FieldsProjection'
                include_raw:
                  $ref: '#/components/schemas/IncludeRaw'
                limit:
                  default: 20
                  description: Maximum number of positions to return.
                  maximum: 100
                  minimum: 1
                  type: integer
                provider:
                  $ref: '#/components/schemas/ProviderShorthand'
                routing:
                  $ref: '#/components/schemas/Routing'
              required:
                - address
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletAssetPageEnvelope'
          description: Success envelope
        '400':
          $ref: '#/components/responses/ValidationError'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamFailed'
        '504':
          $ref: '#/components/responses/Timeout'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    FieldsProjection:
      description: >-
        Projection: keep only these dotted paths of data, e.g. ["items.id",
        "items.text"].
      items:
        type: string
      type: array
    IncludeRaw:
      default: false
      description: >-
        Attach the raw upstream payload as `raw` (not a stable contract;
        truncated above 256 KB).
      type: boolean
    ProviderShorthand:
      description: Shorthand for routing.only = [provider].
      type: string
    Routing:
      additionalProperties: false
      description: >-
        Provider routing override. order: try these providers first; only:
        restrict to these (equivalent to pinning); allow_fallbacks: false tries
        only the first eligible provider.
      properties:
        allow_fallbacks:
          default: true
          description: false = try only the first eligible provider.
          type: boolean
        only:
          description: Restrict to these providers.
          items:
            type: string
          type: array
        order:
          description: Providers to try first, in order.
          items:
            type: string
          type: array
        strategy:
          default: auto
          description: >-
            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.
          enum:
            - auto
          type: string
      type: object
    WalletAssetPageEnvelope:
      allOf:
        - $ref: '#/components/schemas/Envelope'
        - properties:
            data:
              $ref: '#/components/schemas/WalletAssetPage'
          type: object
      description: Success envelope whose data is a WalletAssetPage.
    Envelope:
      description: Success envelope. `data` is the method's output object.
      properties:
        attempts:
          items:
            $ref: '#/components/schemas/Attempt'
          type: array
        credits_charged:
          description: Credits charged for this call (the method's fixed price).
          type: number
        data:
          description: Method output (typed per method).
        op:
          description: Method name.
          type: string
        op_version:
          description: Method version that served the call.
          type: integer
        provider:
          description: Provider that actually served the call.
          type: string
        raw:
          description: Upstream payload, only with include_raw=true. Not a stable contract.
        raw_truncated:
          type: boolean
        request_id:
          description: Correlation id; quote it in support requests.
          type: string
        took_ms:
          type: integer
        unsupported_fields:
          description: >-
            Output paths this provider structurally does not supply; such fields
            are null for a different reason than 'missing on this record'.
          items:
            type: string
          type: array
      required:
        - op
        - op_version
        - provider
        - request_id
        - credits_charged
        - took_ms
        - attempts
        - unsupported_fields
        - data
      type: object
    WalletAssetPage:
      additionalProperties: false
      description: One page of wallet positions.
      properties:
        items:
          items:
            $ref: '#/components/schemas/WalletAsset'
          type: array
        next_cursor:
          description: >-
            Opaque cursor for the next page; null when exhausted or the provider
            cannot page.
          type:
            - string
            - 'null'
      required:
        - items
        - next_cursor
      type: object
    ErrorEnvelope:
      properties:
        attempts:
          items:
            $ref: '#/components/schemas/Attempt'
          type: array
        code:
          type: integer
        error:
          description: Human-readable message.
          type: string
        error_type:
          description: >-
            validation | not_found | rate_limit | timeout | insufficient_credits
            | upstream_unauthorized | upstream_unavailable | provider_error
          type: string
        op:
          description: Method name.
          type: string
        request_id:
          description: Correlation id.
          type: string
      required:
        - error
        - code
        - error_type
      type: object
    Attempt:
      description: >-
        One upstream try. Present on success and failure so a failover is never
        invisible.
      properties:
        error_type:
          description: >-
            validation | not_found | rate_limit | timeout |
            upstream_unauthorized | upstream_unavailable | provider_error
          type: string
        provider:
          description: Provider slug.
          type: string
        refunded:
          description: true when the reservation for this attempt was refunded.
          type: boolean
        status:
          description: HTTP status AgentKey mapped this attempt to (200 on success).
          type: integer
        took_ms:
          type: integer
        tool:
          description: Registry tool name (Provider/operation) that was called.
          type: string
        upstream_status:
          description: The provider's real HTTP status; absent when nothing was received.
          type: integer
      required:
        - provider
        - tool
        - status
        - took_ms
      type: object
    WalletAsset:
      additionalProperties: false
      description: One token position of a wallet.
      properties:
        balance:
          description: Decimal-adjusted balance (1.5 = one and a half tokens).
          type:
            - number
            - 'null'
        balance_raw:
          description: >-
            Balance in the smallest unit exactly as the chain reports it
            (decimal or hex string), for callers that need full precision.
          type:
            - string
            - 'null'
        chain:
          description: Chain slug the position lives on.
          type: string
        price_usd:
          description: Current token price in USD when the provider attaches one.
          type:
            - number
            - 'null'
        token:
          properties:
            address:
              description: Token contract address; null for the chain's native coin.
              type:
                - string
                - 'null'
            decimals:
              description: Token decimals when reported.
              type:
                - integer
                - 'null'
            logo_url:
              description: Logo image URL.
              type:
                - string
                - 'null'
            name:
              description: Token name.
              type:
                - string
                - 'null'
            symbol:
              description: Ticker symbol.
              type:
                - string
                - 'null'
          required:
            - address
            - symbol
            - name
            - decimals
            - logo_url
          type: object
        value_usd:
          description: Position value in USD when the provider computes it.
          type:
            - number
            - 'null'
      required:
        - chain
        - token
        - balance
        - balance_raw
        - price_usd
        - value_usd
      type: object
  responses:
    ValidationError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: Validation error (unknown field, bad cursor, bad routing)
    InsufficientCredits:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: Insufficient credits
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: Not found (method, or upstream object)
    RateLimited:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: Rate limited upstream
    UpstreamFailed:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: All providers failed
    Timeout:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: Timed out
  securitySchemes:
    ApiKeyAuth:
      description: AgentKey API key (ak_…).
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.