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

# Redeem positions

> Pays out every holding GET /positions marks redeemable, or only those on market_id, as cash on the venue. A Polymarket holding of a resolved market stays a token until it is redeemed; Kalshi, Polymarket US and Hyperliquid pay resolved holdings out on their own and never need this. The response lists each holding redeemed with its payout, and is empty when nothing was redeemable. A live redeem needs trading enabled for the account in the Lean app and is submitted once, in one transaction for every holding: it is settled once the venue confirms it, submitted while it is on its way, or failed with failure_reason when the venue refused it. A test redeem moves nothing, settles at once, removes the holdings from the simulated positions and adds their payout to the simulated cash until test mode is reset.



## OpenAPI

````yaml api-reference/openapi.json POST /positions/redeem
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/redeem:
    post:
      tags:
        - Positions
      summary: Redeem resolved positions
      description: >-
        Pays out every holding GET /positions marks redeemable, or only those on
        market_id, as cash on the venue. A Polymarket holding of a resolved
        market stays a token until it is redeemed; Kalshi, Polymarket US and
        Hyperliquid pay resolved holdings out on their own and never need this.
        The response lists each holding redeemed with its payout, and is empty
        when nothing was redeemable. A live redeem needs trading enabled for the
        account in the Lean app and is submitted once, in one transaction for
        every holding: it is settled once the venue confirms it, submitted while
        it is on its way, or failed with failure_reason when the venue refused
        it. A test redeem moves nothing, settles at once, removes the holdings
        from the simulated positions and adds their payout to the simulated cash
        until test mode is reset.
      operationId: redeemPositions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                market_id:
                  type: string
                  minLength: 1
                  maxLength: 512
                  description: >-
                    Only redeem holdings on this market. A Polymarket token id
                    or condition id redeems that one listing; a Lean market id
                    redeems every Polymarket listing of the market. Without it,
                    every redeemable holding of the account is redeemed.
              additionalProperties: false
            example:
              market_id: >-
                mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
      responses:
        '200':
          description: The holdings redeemed
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      success:
                        type: boolean
                        enum:
                          - true
                      data:
                        type: object
                        properties:
                          redeemed:
                            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+)?$
                                  description: The shares redeemed.
                                payout_usd:
                                  type: string
                                  pattern: ^\d+(?:\.\d+)?$
                                  description: >-
                                    What the shares pay: 1 per share on the
                                    winning side, 0 on the losing side, 0.5 when
                                    the market is void. 0 when status is failed.
                                status:
                                  type: string
                                  enum:
                                    - settled
                                    - submitted
                                    - failed
                                  description: >-
                                    settled once the venue has paid out,
                                    submitted while the payout is on its way and
                                    may still fail, failed when the venue
                                    refused it and nothing was paid.
                              required:
                                - venue
                                - ticker
                                - side
                                - market_id
                                - title
                                - outcome
                                - quantity
                                - payout_usd
                                - status
                            description: >-
                              Every holding redeemed, with its payout. Empty
                              when nothing was redeemable.
                          transaction_id:
                            type: string
                            nullable: true
                            minLength: 1
                            description: >-
                              The venue’s id for the transaction that pays out.
                              Null in test mode, for a Hyperliquid merge, and
                              when the venue never accepted it.
                          failure_reason:
                            type: string
                            nullable: true
                            description: >-
                              Why a failed payout paid nothing. Null unless
                              status is failed.
                          livemode:
                            type: boolean
                        required:
                          - redeemed
                          - transaction_id
                          - failure_reason
                          - 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:
                  redeemed:
                    - 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: '40'
                      payout_usd: '40'
                      status: settled
                  transaction_id: 0198f0d2-7c4e-7a51-9b3d-2e6f8a1c4d70
                  failure_reason: null
                  livemode: true
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '400':
          description: >-
            The request is invalid, or market_id names a listing on a venue
            other than Polymarket
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: VALIDATION_ERROR
                  message: >-
                    The request is invalid, or market_id names a listing on a
                    venue other than Polymarket
                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 trade scope, or details.reason is
            ACCOUNT_NOT_DELEGATED
          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
        '404':
          description: market_id names no market
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: NOT_FOUND
                  message: market_id names no market
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '409':
          description: The Polymarket wallet is not set up
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: CONFLICT
                  message: The Polymarket wallet is not set up
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '422':
          description: >-
            details.reason is VENUE_NOT_ALLOWED: the account may not trade
            Polymarket
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: VALIDATION_ERROR
                  message: Refused by a limit; nothing was changed
                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
        '503':
          description: >-
            Trading is paused for this key or its trading account, or the venue
            is unavailable and nothing was submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: FEATURE_DISABLED
                  message: A required service is temporarily unavailable.
                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.