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

# Refresh balance & allowance

> Cache-invalidation variant of `/balance-allowance`. Forces a
fresh chain read; otherwise identical wire shape.




## OpenAPI

````yaml /api-reference/openapi.yaml get /balance-allowance/update
openapi: 3.0.3
info:
  title: XO Orderbook API
  description: |
    Public REST surface of the XO CLOB API.

    XO mainnet chain id is `3223`. The EIP-712 order domain is
    `XO Market CLOB` with `verifyingContract` set to the
    [CTF Exchange](/) address. See
    [Smart accounts](../guides/smart-accounts) for the smart-account
    identity model and ERC-1271 order signing.

    Wire conventions:
      * Prices are trimmed decimal strings (e.g. `"0.5"`, `"0.555"`).
      * Sizes are decimal-string integers in human shares.
      * Timestamps in trade and book responses are stringified Unix
        seconds / milliseconds (the SDK uses `TimestampSeconds<String>`
        / `TimestampMilliSeconds<String>`).
      * Token IDs are decimal U256 strings; condition IDs are
        `0x`-prefixed 32-byte hex.
  version: 1.0.0
  contact:
    name: XO Market
    url: https://beta.xo.market
servers:
  - url: https://orderbooks.xo.market
    description: Mainnet (XO chain id 3223)
security: []
tags:
  - name: Authentication
    description: >-
      Create and manage API keys. The L1 ClobAuth EIP-712 flow mints HMAC
      credentials that authenticate every other private request.
  - name: Market Data
    description: >-
      Public reads for books, prices, midpoints, spreads, last trades, and price
      history. Also includes server time and per-token configuration.
  - name: Markets
    description: >-
      Discovery for tradable markets, including pagination and SDK-compatible
      simplified shapes.
  - name: Trade
    description: Place, cancel, and inspect orders and trades for the authenticated maker.
  - name: Account
    description: Maker balance, allowance, positions, and claimable settled positions.
paths:
  /balance-allowance/update:
    get:
      tags:
        - Account
      summary: Refresh balance & allowance
      description: |
        Cache-invalidation variant of `/balance-allowance`. Forces a
        fresh chain read; otherwise identical wire shape.
      parameters:
        - in: query
          name: address
          required: true
          schema:
            type: string
        - in: query
          name: asset_type
          required: false
          schema:
            type: string
            enum:
              - COLLATERAL
              - CONDITIONAL
        - in: query
          name: token_id
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceAllowanceResponse'
              example:
                balance: '12345678'
                allowance: '10000000'
                smart_account: CAFE000000000000000000000000000000000A11
        '401':
          $ref: '#/components/responses/Error401'
      security:
        - L2HMAC: []
      x-codeSamples:
        - lang: Rust
          label: xo-orderbook-client-rs
          source: >
            // Requires an authenticated client. Forces a fresh chain read.

            use
            xo_orderbook_client::orderbook::types::request::UpdateBalanceAllowanceRequest;


            let resp = client
                .update_balance_allowance(UpdateBalanceAllowanceRequest::default())
                .await?;
components:
  schemas:
    BalanceAllowanceResponse:
      type: object
      required:
        - balance
        - allowance
      properties:
        balance:
          type: string
          description: |
            USDC cash balance in micro-units, decimal string. (XO does
            not currently honour `asset_type=CONDITIONAL` — see endpoint
            description.)
        allowance:
          type: string
          description: |
            Available cash after open-order reservations, decimal-string
            micro-USDC. `balance - allowance` is the amount earmarked
            against resting BUY orders.
        smart_account:
          type: string
          nullable: true
          description: |
            User's smart-account address as **hex without `0x` prefix**
            (e.g. `"CAFE000000000000000000000000000000000A11"`).
            `null` for plain EOA users with no smart account. XO-only
            field — not part of the canonical CLOB wire contract.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
  responses:
    Error401:
      description: |
        Authentication failure. L1 ClobAuth (wallet) or L2 HMAC (API key)
        headers were missing, malformed, expired, or did not match the
        requested resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            l1_required:
              summary: L1 ClobAuth headers missing
              value:
                error: L1 ClobAuth headers required
            l2_required:
              summary: HMAC credentials missing
              value:
                error: HMAC L2 credentials required
            address_mismatch:
              summary: L1-recovered address does not match request
              value:
                error: L1 auth address does not match request address
  securitySchemes:
    L2HMAC:
      type: apiKey
      in: header
      name: XO_API_KEY
      description: >-
        L2 HMAC request signature. See
        [Authentication](/api-reference/authentication).

````