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

> Shares held by this key’s trading account on each venue, with average price, mark price and unrealized profit and loss. Each holding names its `market_id`, `title` and `outcome`, or null when no market is listed for it. Filter by venue, market or text in the market title. Kalshi and Polymarket US accounts belong to the user rather than one trading account, so every trading account of the user lists the same holdings there. A venue that could not be read is listed in `unavailable`.



## OpenAPI

````yaml api-reference/openapi.json GET /positions
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:
  /positions:
    get:
      tags:
        - Account
      summary: List positions
      description: >-
        Shares held by this key’s trading account on each venue, with average
        price, mark price and unrealized profit and loss. Each holding names its
        `market_id`, `title` and `outcome`, or null when no market is listed for
        it. Filter by venue, market or text in the market title. Kalshi and
        Polymarket US accounts belong to the user rather than one trading
        account, so every trading account of the user lists the same holdings
        there. A venue that could not be read is listed in `unavailable`.
      operationId: getPositions
      parameters:
        - schema:
            type: string
            enum:
              - kalshi
              - polymarket
              - polymarket_us
              - hyperliquid
            description: >-
              Only holdings on this venue. Other venues are not read, so only
              this one can be `unavailable`.
          required: false
          description: >-
            Only holdings on this venue. Other venues are not read, so only this
            one can be `unavailable`.
          name: venue
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 512
            description: >-
              Only holdings on this market. A market id from GET /markets, or a
              venue symbol that names one market: a Polymarket token id, a
              Hyperliquid book coin (`#…`, written `%23…` in a path), or a leg
              `ticker` (`pm:…`, `hl:…`, `pmus:…` or a Kalshi market ticker) that
              lists only this outcome. A symbol that names more than one market,
              such as a Polymarket condition id, is refused with 400; use the
              token id or the market id instead.
          required: false
          description: >-
            Only holdings on this market. A market id from GET /markets, or a
            venue symbol that names one market: a Polymarket token id, a
            Hyperliquid book coin (`#…`, written `%23…` in a path), or a leg
            `ticker` (`pm:…`, `hl:…`, `pmus:…` or a Kalshi market ticker) that
            lists only this outcome. A symbol that names more than one market,
            such as a Polymarket condition id, is refused with 400; use the
            token id or the market id instead.
          name: market_id
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 100
            description: >-
              Text, in any letter case, found in the title or outcome of the
              market the holding trades. A holding with no listed market never
              matches.
          required: false
          description: >-
            Text, in any letter case, found in the title or outcome of the
            market the holding trades. A holding with no listed market never
            matches.
          name: search
          in: query
      responses:
        '200':
          description: Open positions of the key’s trading account
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      success:
                        type: boolean
                        enum:
                          - true
                      data:
                        type: object
                        properties:
                          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'
                                quantity:
                                  type: string
                                  pattern: ^\d+(?:\.\d+)?$
                                average_price:
                                  type: string
                                  nullable: true
                                  pattern: ^\d+(?:\.\d+)?$
                                  description: >-
                                    Cost basis per share, fees included, so it
                                    can exceed 1; null when the venue reports no
                                    cost.
                                cost_basis_usd:
                                  type: string
                                  nullable: true
                                  pattern: ^\d+(?:\.\d+)?$
                                  description: >-
                                    What the held shares cost, fees included, as
                                    the Lean portfolio records it; for a holding
                                    Lean has no record of, the venue’s own entry
                                    value. Null when neither is known.
                                mark_price:
                                  type: string
                                  nullable: true
                                  description: >-
                                    Price per share the holding is valued at:
                                    its settlement payout once its market
                                    resolves, else the average a sell of the
                                    whole quantity would fill at in the current
                                    book, else the book’s size-weighted midpoint
                                    when the spread is tight, else the last
                                    price the venue or Lean reported. Null when
                                    none is known, and the holding is then
                                    valued at cost.
                                unrealized_pnl_usd:
                                  type: string
                                  nullable: true
                                  pattern: ^-?\d+(?:\.\d+)?$
                                  description: >-
                                    Value at the mark price, or at cost without
                                    one, less the cost basis; null when the cost
                                    is unknown.
                                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
                              required:
                                - venue
                                - ticker
                                - side
                                - quantity
                                - average_price
                                - cost_basis_usd
                                - mark_price
                                - unrealized_pnl_usd
                                - market_id
                                - title
                                - outcome
                          unavailable:
                            type: array
                            items:
                              type: string
                              enum:
                                - kalshi
                                - polymarket
                                - polymarket_us
                                - hyperliquid
                          livemode:
                            type: boolean
                        required:
                          - positions
                          - 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:
                Positions:
                  summary: Open positions
                  value:
                    success: true
                    data:
                      positions:
                        - market_id: >-
                            mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                          venue: hyperliquid
                          ticker: <venue ticker>
                          side: 'yes'
                          quantity: '5'
                          average_price: '0.47'
                          mark_price: '0.52'
                          unrealized_pnl_usd: '0.25'
                          title: >-
                            Denver Broncos at Los Angeles Chargers: DEN -3.5,
                            Denver Broncos -3.5
                          outcome: DEN
                        - market_id: >-
                            mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                          venue: hyperliquid
                          ticker: <venue ticker>
                          side: 'yes'
                          quantity: '5'
                          average_price: '0.47'
                          mark_price: '0.52'
                          unrealized_pnl_usd: '0.25'
                          title: >-
                            Denver Broncos at Los Angeles Chargers: DEN -3.5,
                            Denver Broncos -3.5
                          outcome: DEN
                      unavailable: []
                      livemode: true
                    meta:
                      timestampMs: 1791741600000
                      requestId: a3f8c2e7-0d4b-4691-8b6a-5e1c9f07d2b8
                Test key:
                  summary: Simulated shares, marked at the venue's best bid
                  value:
                    success: true
                    data:
                      positions:
                        - market_id: >-
                            mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                          venue: hyperliquid
                          ticker: <venue ticker>
                          side: 'yes'
                          quantity: '5'
                          average_price: '0.5'
                          mark_price: '0.52'
                          unrealized_pnl_usd: '0.1'
                          title: >-
                            Denver Broncos at Los Angeles Chargers: DEN -3.5,
                            Denver Broncos -3.5
                          outcome: DEN
                        - market_id: >-
                            mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                          venue: hyperliquid
                          ticker: <venue ticker>
                          side: 'yes'
                          quantity: '5'
                          average_price: '0.5'
                          mark_price: '0.52'
                          unrealized_pnl_usd: '0.1'
                          title: >-
                            Denver Broncos at Los Angeles Chargers: DEN -3.5,
                            Denver Broncos -3.5
                          outcome: DEN
                      unavailable: []
                      livemode: false
                    meta:
                      timestampMs: 1791741600000
                      requestId: a3f8c2e7-0d4b-4691-8b6a-5e1c9f07d2b8
                Venue unavailable:
                  summary: One venue could not be read; do not treat it as empty
                  value:
                    success: true
                    data:
                      positions: []
                      unavailable:
                        - hyperliquid
                        - hyperliquid
                      livemode: true
                    meta:
                      timestampMs: 1791741600000
                      requestId: a3f8c2e7-0d4b-4691-8b6a-5e1c9f07d2b8
        '400':
          description: API error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: VALIDATION_ERROR
                  message: Invalid request
                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'
              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: a3f8c2e7-0d4b-4691-8b6a-5e1c9f07d2b8
                Missing key:
                  summary: No Authorization header
                  value:
                    success: false
                    error:
                      code: UNAUTHORIZED
                      message: Missing API key
                    meta:
                      timestampMs: 1791741600000
                      requestId: a3f8c2e7-0d4b-4691-8b6a-5e1c9f07d2b8
        '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: a3f8c2e7-0d4b-4691-8b6a-5e1c9f07d2b8
        '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: a3f8c2e7-0d4b-4691-8b6a-5e1c9f07d2b8
        '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: a3f8c2e7-0d4b-4691-8b6a-5e1c9f07d2b8
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.