> ## Documentation Index > Fetch the complete documentation index at: https://cobo.com/products/agentic-wallet/manual/llms.txt > Use this file to discover all available pages before exploring further. # List token balances > This operation retrieves cached token balances across all wallets accessible to the authenticated principal. Balances are synchronized from on-chain data and may be slightly delayed. You can filter by wallet, chain, address, or token. Use cursor-based pagination with `after`/`before`. Set `force_refresh=true` together with `address` to force a fresh sync from on-chain before returning. ## OpenAPI ````yaml get /api/v1/wallets/balances openapi: 3.1.0 info: title: Cobo Agentic Wallet Service description: Unified wallet engine for human and agent principals version: 1.3.0 servers: [] security: [] paths: /api/v1/wallets/balances: get: tags: - Balance summary: List token balances description: >- This operation retrieves cached token balances across all wallets accessible to the authenticated principal. Balances are synchronized from on-chain data and may be slightly delayed. You can filter by wallet, chain, address, or token. Use cursor-based pagination with `after`/`before`. Set `force_refresh=true` together with `address` to force a fresh sync from on-chain before returning. operationId: list_balances parameters: - name: wallet_uuid in: query required: false schema: description: >- Filter balances by wallet ID. The wallet ID can be retrieved by calling the List all wallets operation. title: Wallet Uuid type: string format: uuid nullable: true description: >- Filter balances by wallet ID. The wallet ID can be retrieved by calling the List all wallets operation. - name: chain_id in: query required: false schema: description: Filter balances by chain ID (for example, `SETH`, `BASE_ETH`). title: Chain Id type: string nullable: true description: Filter balances by chain ID (for example, `SETH`, `BASE_ETH`). - name: address in: query required: false schema: description: Filter balances by on-chain address. title: Address type: string nullable: true description: Filter balances by on-chain address. - name: token_id in: query required: false schema: description: Filter balances by token ID (for example, `SETH`, `SETH_USDC`). title: Token Id type: string nullable: true description: Filter balances by token ID (for example, `SETH`, `SETH_USDC`). - name: force_refresh in: query required: false schema: type: boolean description: >- When `true` and `address` is provided, force a fresh sync of balances from on-chain before returning results. default: false title: Force Refresh description: >- When `true` and `address` is provided, force a fresh sync of balances from on-chain before returning results. - name: limit in: query required: false schema: type: integer maximum: 200 minimum: 1 description: 'The maximum number of items to return. Range: [1, 200].' default: 50 title: Limit description: 'The maximum number of items to return. Range: [1, 200].' - name: after in: query required: false schema: description: >- A cursor for forward pagination. Pass the `after` value from a previous response to retrieve the next page. title: After type: string nullable: true description: >- A cursor for forward pagination. Pass the `after` value from a previous response to retrieve the next page. - name: before in: query required: false schema: description: >- A cursor for backward pagination. Pass the `before` value from a previous response to retrieve the preceding page. title: Before type: string nullable: true description: >- A cursor for backward pagination. Pass the `before` value from a previous response to retrieve the preceding page. - name: offset in: query required: false schema: description: Deprecated. Use `after`/`before` cursors instead. deprecated: true title: Offset type: integer maximum: 9223372036854776000 minimum: 0 nullable: true description: Deprecated. Use `after`/`before` cursors instead. deprecated: true - name: X-API-Key in: header required: false schema: title: X-Api-Key type: string nullable: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/StandardResponse_list_BalanceRead__' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/WrappedValidationError' components: schemas: StandardResponse_list_BalanceRead__: properties: success: type: boolean title: Success default: true result: items: $ref: '#/components/schemas/BalanceRead' type: array title: Result suggestion: type: string title: Suggestion default: '' message: type: string title: Message default: '' meta: $ref: '#/components/schemas/PaginationMeta' nullable: true type: object required: - result title: StandardResponse[list[BalanceRead]] WrappedValidationError: title: WrappedValidationError type: object required: - success - error properties: success: type: boolean const: false default: false title: Success error: type: object title: Error required: - detail properties: detail: type: array title: Detail items: $ref: '#/components/schemas/ValidationError' BalanceRead: properties: id: type: string format: uuid title: Id description: The balance record ID. wallet_uuid: type: string format: uuid title: Wallet Uuid description: The wallet ID this balance belongs to. cobo_wallet_id: type: string title: Cobo Wallet Id description: The Cobo WaaS wallet ID. user_id: type: string format: uuid title: User Id description: The ID of the principal that owns this wallet. address: type: string title: Address description: The on-chain address holding this balance. chain_id: title: Chain Id description: The Cobo chain ID (for example, `SETH`, `BASE_ETH`, `SOL`). type: string nullable: true chain_type: title: Chain Type description: >- The address standard shared across chains — chains with the same chain_type share one wallet address. E.g. ETH, BASE, ARB, OP, BSC, MATIC, AVAXC, and SETH are all chain_type: ETH, so they all use the same 0x... address. type: string nullable: true compatible_chains: items: type: string type: array title: Compatible Chains description: >- Supported chain IDs that share the same address under this chain_type. token_id: type: string title: Token Id description: The Cobo token ID (for example, `SETH`, `SETH_USDC`). amount: type: string title: Amount description: The spendable balance as a decimal string. total: title: Total description: The total balance including pending amounts, as a decimal string. type: string nullable: true pending: title: Pending description: >- The pending balance (unconfirmed inbound transfers), as a decimal string. type: string nullable: true locked: title: Locked description: >- The locked balance (for example, staked or escrowed amounts), as a decimal string. type: string nullable: true balance_updated_at: title: Balance Updated At description: >- The timestamp when the balance was last synced from on-chain, in ISO 8601 format. type: string format: date-time nullable: true updated_at: type: string format: date-time title: Updated At description: >- The timestamp when this balance record was last updated, in ISO 8601 format. type: object required: - id - wallet_uuid - cobo_wallet_id - user_id - address - token_id - amount - updated_at title: BalanceRead PaginationMeta: properties: total: title: Total type: integer nullable: true offset: title: Offset type: integer nullable: true limit: title: Limit type: integer nullable: true has_more: title: Has More type: boolean nullable: true after: title: After type: string nullable: true before: title: Before type: string nullable: true type: object title: PaginationMeta description: |- Pagination metadata for list responses. Supports both legacy offset-based and cursor-based pagination. Cursor fields (``has_more``, ``after``, ``before``) are populated for cursor-paginated endpoints. Legacy fields (``offset``, ``limit``) are populated when the caller uses the deprecated ``offset`` parameter. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ````