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

# List balances

> Cash held by this key’s trading account on each venue, in the collateral the venue trades in. Kalshi and Polymarket US cash belongs to the user, so every trading account of the user reads the same balance there. A venue that could not be read is listed in `unavailable`.



## OpenAPI

````yaml api-reference/openapi.json GET /balances
openapi: 3.0.0
info:
  title: Lean API
  version: 0.1.0
  description: >-
    Programmatic access to Lean: canonical sports markets, quotes, orders,
    positions and balances.
servers:
  - url: '{baseUrl}/v1'
    description: Lean API
    variables:
      baseUrl:
        default: https://api.lean.xyz
        description: >-
          The Lean API base URL, without /v1. Same value as LEAN_API_URL in the
          guides.
security:
  - apiKey: []
paths:
  /balances:
    get:
      tags:
        - Account
      summary: Get balances
      description: >-
        Cash held by this key’s trading account on each venue, in the collateral
        the venue trades in. Kalshi and Polymarket US cash belongs to the user,
        so every trading account of the user reads the same balance there. A
        venue that could not be read is listed in `unavailable`.
      operationId: getBalances
      responses:
        '200':
          description: Cash balances of the key’s trading account per venue
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      success:
                        type: boolean
                        enum:
                          - true
                      data:
                        type: object
                        properties:
                          balances:
                            type: array
                            items:
                              type: object
                              properties:
                                venue:
                                  type: string
                                  enum:
                                    - kalshi
                                    - polymarket
                                    - polymarket_us
                                    - hyperliquid
                                currency:
                                  type: string
                                  minLength: 1
                                total_usd:
                                  type: string
                                  pattern: ^\d+(?:\.\d+)?$
                                available_usd:
                                  type: string
                                  pattern: ^\d+(?:\.\d+)?$
                              required:
                                - venue
                                - currency
                                - total_usd
                                - available_usd
                          unavailable:
                            type: array
                            items:
                              type: string
                              enum:
                                - kalshi
                                - polymarket
                                - polymarket_us
                                - hyperliquid
                          livemode:
                            type: boolean
                        required:
                          - balances
                          - unavailable
                          - livemode
                      meta:
                        type: object
                        properties:
                          timestampMs:
                            type: integer
                            minimum: 0
                          requestId:
                            type: string
                            minLength: 1
                          traceId:
                            type: string
                            minLength: 1
                          cachedAtMs:
                            type: integer
                            minimum: 0
                          source:
                            type: string
                            enum:
                              - cache
                              - database
                              - clickhouse
                              - upstream
                              - fallback
                              - internal
                        required:
                          - timestampMs
                          - requestId
                    required:
                      - success
                      - data
                      - meta
                  - $ref: '#/components/schemas/ApiError'
              examples:
                Balances:
                  summary: Cash per venue
                  value:
                    success: true
                    data:
                      balances:
                        - venue: hyperliquid
                          currency: USDC
                          total_usd: '250'
                          available_usd: '245.5'
                        - venue: polymarket
                          currency: USDC
                          total_usd: '100'
                          available_usd: '100'
                        - venue: hyperliquid
                          currency: USDC
                          total_usd: '250'
                          available_usd: '245.5'
                        - venue: polymarket
                          currency: USDC
                          total_usd: '100'
                          available_usd: '100'
                      unavailable: []
                      livemode: true
                    meta:
                      timestampMs: 1791741600000
                      requestId: f6d3a0b9-4e2c-4718-a5f9-0c8e1b7d3a54
                Test key:
                  summary: 'Simulated cash: each venue starts at 10,000'
                  value:
                    success: true
                    data:
                      balances:
                        - venue: polymarket
                          currency: pUSD
                          total_usd: '10000'
                          available_usd: '10000'
                        - venue: hyperliquid
                          currency: USDC
                          total_usd: '10000'
                          available_usd: '10000'
                        - venue: polymarket
                          currency: pUSD
                          total_usd: '10000'
                          available_usd: '10000'
                        - venue: hyperliquid
                          currency: USDC
                          total_usd: '10000'
                          available_usd: '10000'
                      unavailable: []
                      livemode: false
                    meta:
                      timestampMs: 1791741600000
                      requestId: f6d3a0b9-4e2c-4718-a5f9-0c8e1b7d3a54
                Venue unavailable:
                  summary: One venue could not be read; do not treat it as zero
                  value:
                    success: true
                    data:
                      balances:
                        - venue: hyperliquid
                          currency: USDC
                          total_usd: '250'
                          available_usd: '245.5'
                        - venue: hyperliquid
                          currency: USDC
                          total_usd: '250'
                          available_usd: '245.5'
                      unavailable:
                        - polymarket
                        - polymarket
                      livemode: true
                    meta:
                      timestampMs: 1791741600000
                      requestId: f6d3a0b9-4e2c-4718-a5f9-0c8e1b7d3a54
        '401':
          description: Missing, invalid, expired or revoked API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                Unknown key:
                  summary: Unknown, expired or revoked key
                  value:
                    success: false
                    error:
                      code: UNAUTHORIZED
                      message: Invalid, expired or revoked API key
                    meta:
                      timestampMs: 1791741600000
                      requestId: f6d3a0b9-4e2c-4718-a5f9-0c8e1b7d3a54
                Missing key:
                  summary: No Authorization header
                  value:
                    success: false
                    error:
                      code: UNAUTHORIZED
                      message: Missing API key
                    meta:
                      timestampMs: 1791741600000
                      requestId: f6d3a0b9-4e2c-4718-a5f9-0c8e1b7d3a54
        '403':
          description: The key lacks the scope this route needs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                Missing scope:
                  summary: The key lacks the read scope
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: This API key lacks the read scope
                    meta:
                      timestampMs: 1791741600000
                      requestId: f6d3a0b9-4e2c-4718-a5f9-0c8e1b7d3a54
        '429':
          description: API error
          headers:
            Retry-After:
              description: Seconds remaining in the upstream read cooldown, when available
              schema:
                type: integer
                minimum: 0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                Rate limited:
                  summary: Over 5 requests a second; wait for Retry-After
                  value:
                    success: false
                    error:
                      code: RATE_LIMITED
                      message: Too many requests for this API key
                    meta:
                      timestampMs: 1791741600000
                      requestId: f6d3a0b9-4e2c-4718-a5f9-0c8e1b7d3a54
        '500':
          description: API error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                Internal error:
                  summary: Unexpected server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An internal error occurred.
                    meta:
                      timestampMs: 1791741600000
                      requestId: f6d3a0b9-4e2c-4718-a5f9-0c8e1b7d3a54
components:
  schemas:
    ApiError:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - VALIDATION_ERROR
                - NOT_FOUND
                - UNAUTHORIZED
                - FORBIDDEN
                - CONFLICT
                - UPSTREAM_ERROR
                - RATE_LIMITED
                - INTERNAL_ERROR
                - FEATURE_DISABLED
                - CONDITIONAL_SELL_REJECTED
                - CONDITIONAL_SELL_ACTIVE
            message:
              type: string
              minLength: 1
            details:
              nullable: true
          required:
            - code
            - message
        meta:
          type: object
          properties:
            timestampMs:
              type: integer
              minimum: 0
            requestId:
              type: string
              minLength: 1
            traceId:
              type: string
              minLength: 1
            cachedAtMs:
              type: integer
              minimum: 0
            source:
              type: string
              enum:
                - cache
                - database
                - clickhouse
                - upstream
                - fallback
                - internal
          required:
            - timestampMs
            - requestId
      required:
        - success
        - error
        - meta
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        A Lean API key, sent as `Authorization: Bearer <key>`. A test key
        (`lean_sk_test_...`) simulates orders and fills with no money; a live
        key (`lean_sk_live_...`) trades for real within the key's limits. Every
        successful response says which mode answered in `data.livemode`.

````

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