> ## 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.

# Get risk

> Exposure of this key’s trading account, per venue and in total: the cost basis and mark value of its positions, its cash, and the unfilled notional of its open orders. Also its largest positions and how its cost basis splits across markets and categories. Built from the same reads as positions, balances and orders; a venue that cannot be read is listed in `unavailable` and its values are null, never zero. A test key’s positions are marked as the Lean portfolio marks live ones: Polymarket at the last trade, Hyperliquid at the venue’s mid; a position with no mark makes the mark values it counts toward null.



## OpenAPI

````yaml api-reference/openapi.json GET /risk
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:
  /risk:
    get:
      tags:
        - Account
      summary: Get risk
      description: >-
        Exposure of this key’s trading account, per venue and in total: the cost
        basis and mark value of its positions, its cash, and the unfilled
        notional of its open orders. Also its largest positions and how its cost
        basis splits across markets and categories. Built from the same reads as
        positions, balances and orders; a venue that cannot be read is listed in
        `unavailable` and its values are null, never zero. A test key’s
        positions are marked as the Lean portfolio marks live ones: Polymarket
        at the last trade, Hyperliquid at the venue’s mid; a position with no
        mark makes the mark values it counts toward null.
      operationId: getRisk
      responses:
        '200':
          description: Exposure of the key’s trading account
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      success:
                        type: boolean
                        enum:
                          - true
                      data:
                        type: object
                        properties:
                          cost_basis_usd:
                            type: string
                            nullable: true
                            pattern: ^\d+(?:\.\d+)?$
                          mark_value_usd:
                            type: string
                            nullable: true
                            pattern: ^\d+(?:\.\d+)?$
                          cash_usd:
                            type: string
                            nullable: true
                            pattern: ^\d+(?:\.\d+)?$
                          open_orders:
                            type: object
                            properties:
                              count:
                                type: integer
                                minimum: 0
                              buy_notional_usd:
                                type: string
                                pattern: ^\d+(?:\.\d+)?$
                                description: >-
                                  What the unfilled part of open buys costs at
                                  their limit prices.
                              sell_notional_usd:
                                type: string
                                pattern: ^\d+(?:\.\d+)?$
                                description: >-
                                  What the unfilled part of open sells pays at
                                  their limit prices.
                            required:
                              - count
                              - buy_notional_usd
                              - sell_notional_usd
                            description: >-
                              Every open order, including routed orders whose
                              venue order is not placed yet, which no venue
                              lists.
                          venues:
                            type: array
                            items:
                              type: object
                              properties:
                                venue:
                                  type: string
                                  enum:
                                    - kalshi
                                    - polymarket
                                    - polymarket_us
                                    - hyperliquid
                                position_count:
                                  type: integer
                                  minimum: 0
                                  description: >-
                                    Positions on this venue, not counting
                                    remainders too small to trade that the venue
                                    cannot redeem yet. Their cost and value
                                    still count.
                                cost_basis_usd:
                                  type: string
                                  nullable: true
                                  pattern: ^\d+(?:\.\d+)?$
                                  description: >-
                                    Sum of `cost_basis_usd` over this venue’s
                                    positions; null when its positions could not
                                    be read or one has no known cost.
                                mark_value_usd:
                                  type: string
                                  nullable: true
                                  pattern: ^\d+(?:\.\d+)?$
                                  description: >-
                                    What this venue’s positions are worth: each
                                    at quantity times its mark price, or at cost
                                    without one. Null when its positions could
                                    not be read or one has no known cost.
                                cash_usd:
                                  type: string
                                  nullable: true
                                  pattern: ^\d+(?:\.\d+)?$
                                  description: >-
                                    Cash balance on this venue; null when it
                                    could not be read.
                                available_usd:
                                  type: string
                                  nullable: true
                                  pattern: ^\d+(?:\.\d+)?$
                                  description: >-
                                    Cash free to trade on this venue; null when
                                    it could not be read.
                                open_orders:
                                  type: object
                                  properties:
                                    count:
                                      type: integer
                                      minimum: 0
                                    buy_notional_usd:
                                      type: string
                                      pattern: ^\d+(?:\.\d+)?$
                                      description: >-
                                        What the unfilled part of open buys
                                        costs at their limit prices.
                                    sell_notional_usd:
                                      type: string
                                      pattern: ^\d+(?:\.\d+)?$
                                      description: >-
                                        What the unfilled part of open sells
                                        pays at their limit prices.
                                  required:
                                    - count
                                    - buy_notional_usd
                                    - sell_notional_usd
                              required:
                                - venue
                                - position_count
                                - cost_basis_usd
                                - mark_value_usd
                                - cash_usd
                                - available_usd
                                - open_orders
                          largest_positions:
                            type: array
                            items:
                              type: object
                              properties:
                                venue:
                                  type: string
                                  enum:
                                    - kalshi
                                    - polymarket
                                    - polymarket_us
                                    - hyperliquid
                                ticker:
                                  type: string
                                  minLength: 1
                                side:
                                  type: string
                                  enum:
                                    - 'yes'
                                    - 'no'
                                market_id:
                                  type: string
                                  nullable: true
                                  minLength: 1
                                  description: >-
                                    The market id from GET /markets, however the
                                    request named the market.
                                title:
                                  type: string
                                  nullable: true
                                  minLength: 1
                                outcome:
                                  type: string
                                  nullable: true
                                  minLength: 1
                                quantity:
                                  type: string
                                  pattern: ^\d+(?:\.\d+)?$
                                cost_basis_usd:
                                  type: string
                                  nullable: true
                                  pattern: ^\d+(?:\.\d+)?$
                                mark_value_usd:
                                  type: string
                                  nullable: true
                                  pattern: ^\d+(?:\.\d+)?$
                                share:
                                  type: string
                                  nullable: true
                                  pattern: ^-?\d+(?:\.\d+)?$
                                  description: >-
                                    Fraction of the cost basis of every position
                                    whose cost is known, from 0 to 1.
                              required:
                                - venue
                                - ticker
                                - side
                                - market_id
                                - title
                                - outcome
                                - quantity
                                - cost_basis_usd
                                - mark_value_usd
                                - share
                            description: >-
                              At most 10 positions, largest cost basis first;
                              positions with no known cost come last.
                          by_market:
                            type: array
                            items:
                              type: object
                              properties:
                                market_id:
                                  type: string
                                  nullable: true
                                  minLength: 1
                                  description: >-
                                    Null groups the holdings the API lists no
                                    market for.
                                title:
                                  type: string
                                  nullable: true
                                  minLength: 1
                                cost_basis_usd:
                                  type: string
                                  pattern: ^\d+(?:\.\d+)?$
                                share:
                                  type: string
                                  pattern: ^-?\d+(?:\.\d+)?$
                                  description: >-
                                    Fraction of the cost basis of every position
                                    whose cost is known, from 0 to 1.
                              required:
                                - market_id
                                - title
                                - cost_basis_usd
                                - share
                            description: Largest cost basis first.
                          by_category:
                            type: array
                            items:
                              type: object
                              properties:
                                category:
                                  type: string
                                  nullable: true
                                  enum:
                                    - sports
                                  description: >-
                                    The market category. Null groups the
                                    holdings the API lists no market for.
                                sport:
                                  type: string
                                  nullable: true
                                  minLength: 1
                                cost_basis_usd:
                                  type: string
                                  pattern: ^\d+(?:\.\d+)?$
                                share:
                                  type: string
                                  pattern: ^-?\d+(?:\.\d+)?$
                                  description: >-
                                    Fraction of the cost basis of every position
                                    whose cost is known, from 0 to 1.
                              required:
                                - category
                                - sport
                                - cost_basis_usd
                                - share
                            description: >-
                              By market category and sport, largest cost basis
                              first.
                          unavailable:
                            type: array
                            items:
                              type: string
                              enum:
                                - kalshi
                                - polymarket
                                - polymarket_us
                                - hyperliquid
                            description: >-
                              Venues whose positions or balance could not be
                              read.
                          as_of:
                            type: string
                            format: date-time
                          livemode:
                            type: boolean
                        required:
                          - cost_basis_usd
                          - mark_value_usd
                          - cash_usd
                          - open_orders
                          - venues
                          - largest_positions
                          - by_market
                          - by_category
                          - unavailable
                          - as_of
                          - 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'
              example:
                success: true
                data:
                  cost_basis_usd: '8.1'
                  mark_value_usd: '9.3'
                  cash_usd: '250'
                  open_orders:
                    count: 1
                    buy_notional_usd: '2'
                    sell_notional_usd: '0'
                  venues:
                    - venue: polymarket
                      position_count: 1
                      cost_basis_usd: '3.6'
                      mark_value_usd: '4'
                      cash_usd: '150'
                      available_usd: '148'
                      open_orders:
                        count: 1
                        buy_notional_usd: '2'
                        sell_notional_usd: '0'
                    - venue: hyperliquid
                      position_count: 1
                      cost_basis_usd: '4.5'
                      mark_value_usd: '5.3'
                      cash_usd: '100'
                      available_usd: '100'
                      open_orders:
                        count: 0
                        buy_notional_usd: '0'
                        sell_notional_usd: '0'
                  largest_positions:
                    - venue: hyperliquid
                      ticker: hl:9999
                      side: 'yes'
                      market_id: >-
                        mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                      title: >-
                        Denver Broncos at Los Angeles Chargers: DEN -3.5, Denver
                        Broncos -3.5
                      outcome: DEN
                      quantity: '15'
                      cost_basis_usd: '4.5'
                      mark_value_usd: '5.3'
                      share: '0.5556'
                    - venue: polymarket
                      ticker: >-
                        pm:0x2222222222222222222222222222222222222222222222222222222222222222
                      side: 'yes'
                      market_id: >-
                        mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                      title: >-
                        Denver Broncos at Los Angeles Chargers: DEN -3.5, Denver
                        Broncos -3.5
                      outcome: DEN
                      quantity: '8'
                      cost_basis_usd: '3.6'
                      mark_value_usd: '4'
                      share: '0.4444'
                  by_market:
                    - market_id: >-
                        mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                      title: >-
                        Denver Broncos at Los Angeles Chargers: DEN -3.5, Denver
                        Broncos -3.5
                      cost_basis_usd: '8.1'
                      share: '1'
                  by_category:
                    - category: sports
                      sport: football
                      cost_basis_usd: '8.1'
                      share: '1'
                  unavailable: []
                  as_of: '2026-11-10T17:00:00.000Z'
                  livemode: true
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '401':
          description: Missing, invalid, expired or revoked API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: UNAUTHORIZED
                  message: Invalid, expired or revoked API key
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '403':
          description: The key lacks the scope this route needs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: FORBIDDEN
                  message: This API key lacks the scope this route needs
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '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'
              example:
                success: false
                error:
                  code: RATE_LIMITED
                  message: Too many requests for this API key
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '500':
          description: API error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: INTERNAL_ERROR
                  message: An internal error occurred.
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
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.