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

# Get user balances

> Get user balances.

 Get the current user's token balances with pagination support. Returns
 available, locked, and total balance for each token.



## OpenAPI

````yaml /proto-openapi/api/openapi.yaml get /api/v1/accounts/balances
openapi: 3.0.3
info:
  title: Monaco Protocol API
  description: REST API for the Monaco Protocol hybrid CLOB exchange.
  version: 1.0.0
servers:
  - url: https://staging.apimonaco.xyz
    description: Staging server (Testnet)
security: []
tags:
  - name: AccountsService
  - name: ApplicationsService
  - name: AuthService
  - name: BuildercodeRewardsService
  - name: CopyTradingService
  - name: DelegatedAgentsService
  - name: FaucetService
  - name: FeesService
  - name: HealthService
  - name: ManagedMarketsService
    description: |-
      Wallet-authenticated maker assignments. The signed session must match both
       configured maker user and application. Owner IDs are process fences, never auth.
       Only wallet sessions are supported; delegated-agent sessions receive 403.
  - name: MarginAccountsService
    description: |-
      Current public isolated-margin semantics:
       - a user has one parent margin account per application scope
       - opening orders create or reuse isolated position buckets under that parent
       - parent account creation is handled internally by margin workflows
  - name: MarketService
  - name: OrderbookService
  - name: OrdersService
  - name: PositionsService
    description: |-
      Current public isolated-margin semantics:
       - positions link to a parent margin account and, when applicable, a bucket id
       - opening orders create or reuse isolated position buckets under the parent
       - users can open another isolated position by reusing the parent account with a different market bucket
  - name: PulseService
  - name: SweeperService
  - name: TraderCodeService
  - name: TradesService
  - name: WhitelistService
  - name: WithdrawalsService
paths:
  /api/v1/accounts/balances:
    get:
      tags:
        - AccountsService
        - Accounts
      summary: Get user balances
      description: |-
        Get user balances.

         Get the current user's token balances with pagination support. Returns
         available, locked, and total balance for each token.
      operationId: get_user_balances
      parameters:
        - name: pageSize
          in: query
          schema:
            type: integer
            format: uint32
            minimum: 1
            maximum: 1000
            default: 20
          description: Items per page (max 1000)
        - name: pageToken
          in: query
          description: |-
            Pagination cursor with two states:
              - Omitted or empty string (""): start a cursor walk with no prior
                position, from the lowest token address.
              - Non-empty: an opaque cursor from a previous response's
                `nextPageToken`; results resume immediately after that position.

             This listing has no database page to walk: it reads every balance row,
             overlays the matching engine's authoritative amounts (which can add rows
             the projection has not written yet and drop rows the engine has zeroed),
             and pages that in-memory set. The walk therefore seeks by KEY on
             `(token, asset_id)` — immutable, present on every row including a
             live-only one — rather than by index, so a balance that appears or
             vanishes mid-walk no longer shifts the rows behind it across the resume
             point and duplicate or skipped rows. `total` and `totalPages` are exact:
             the set is bounded by the asset universe, so there is nothing to cap.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBalancesResponse'
        '400':
          description: Invalid request
        '401':
          description: Authentication required
        '429':
          description: >-
            Read rate limit exceeded — every authenticated read draws one
            request from the account's read budget; retry after the interval in
            details.retryAfter
        '500':
          description: Internal server error
      security:
        - monacoSignature: []
        - monacoHttpSignature: []
components:
  schemas:
    GetBalancesResponse:
      type: object
      properties:
        balances:
          type: array
          items:
            $ref: '#/components/schemas/AccountBalance'
          nullable: true
        total:
          example: 5
          type: integer
          description: Total number of balances
          format: uint32
          nullable: true
        pageSize:
          example: 20
          type: integer
          description: Items per page
          format: uint32
          nullable: true
        totalPages:
          example: 1
          type: integer
          description: Total number of pages
          format: uint32
          nullable: true
        nextPageToken:
          type: string
          description: >-
            Cursor for the next page, minted from the last row of an
            over-fetched
             page. The whole set is already in memory, so over-fetching is free and an
             empty token is the definitive end of the walk.
          nullable: true
    AccountBalance:
      type: object
      properties:
        token:
          example: '0x6a86da986797d59a839d136db490292cd560c131'
          type: string
          description: Token contract address
          nullable: true
        symbol:
          example: USDC
          type: string
          description: Token symbol
          nullable: true
        decimals:
          example: 6
          type: integer
          description: Token decimal places
          format: int32
          nullable: true
        availableBalance:
          example: '1000.50'
          type: string
          description: Available (unlocked) balance in token units
          nullable: true
        lockedBalance:
          example: '50.25'
          type: string
          description: Balance locked in open orders
          nullable: true
        totalBalance:
          example: '1050.75'
          type: string
          description: Total balance (available + locked)
          nullable: true
        availableBalanceRaw:
          example: '1000500000'
          type: string
          description: Raw available balance in smallest token unit
          nullable: true
        lockedBalanceRaw:
          example: '50250000'
          type: string
          description: Raw locked balance in smallest token unit
          nullable: true
        assetId:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Asset UUID
          format: uuid
          nullable: true
        totalBalanceRaw:
          example: '1050750000'
          type: string
          description: Raw total balance (available + locked) in smallest token unit
          nullable: true
        wrappedNative:
          example: true
          type: boolean
          description: >-
            True when this asset is the chain's wrapped-native token (e.g.
            WSEI): vault deposits can be made in native coin via depositNative
            (the vault wraps on entry) and withdrawals pay out native
          nullable: true
        version:
          example: 918342
          type: integer
          description: >-
            Opaque, non-negative producer-owned version for this spot
            user_balances row. Compare only within the same (user, application,
            token); higher is newer. 0 is the unranked legacy sentinel and never
            participates in ordering: it means the row predates this field or
            came from a producer that does not stamp it, so treat it exactly as
            an absent version and fall back to a full field comparison rather
            than ranking it as oldest. This does not order margin collateral.
          format: int64
          minimum: 0
          nullable: true
  securitySchemes:
    monacoSignature:
      type: apiKey
      description: >-
        Ed25519 session-key request signing. Every authenticated request carries
        three headers: `X-Monaco-PublicKey` (64-char lowercase-hex session
        public key), `X-Monaco-Timestamp` (Unix milliseconds, within 30s of
        server time), and `X-Monaco-Signature` (hex ed25519 signature). The
        signature is over `METHOD\npath?query\ntimestamp_ms\nSHA256_hex(body)`,
        where the body hash is the SHA-256 of the empty byte string when there
        is no body. Obtain the session keypair from `POST
        /api/v1/auth/challenge` followed by `POST /api/v1/auth/verify`.
      name: X-Monaco-Signature
      in: header
    monacoHttpSignature:
      type: apiKey
      description: >-
        RFC 9421 Ed25519 session-key request signatures. Send Signature-Input,
        Signature, and Content-Digest together; never combine them with
        X-Monaco-* credentials. The monaco signature covers @method, @path,
        @query, and content-digest in that order, with created (Unix seconds
        within 30s of server time), keyid (registered lowercase-hex session
        public key), and alg=ed25519 parameters. Content-Digest uses RFC 9530
        sha-256 over the exact body bytes, including the empty body. Query
        coverage retains ordering and percent encoding. Timestamp freshness does
        not reject repeated identical requests; use endpoint idempotency where
        supported. Existing legacy signing remains supported during server-first
        migration; SDK RFC 9421 signing is opt-in. See
        https://docs.0xmonaco.com/reference/http-message-signatures for the
        complete profile and trust model.
      name: Signature
      in: header

````

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