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

# Close positions

> Sells each position of this key's trading account in this key's mode, optionally only on one venue or market, through the same checks and limits as POST /v1/orders. Each sell sells only what is held less what open sells already offer, on the venue that holds it, so a close never sells more than the account holds. Each placed sell is read back before the response, so one the venue matched at once reads filled with its filled quantity and average price. Cancel open orders first to close everything. A close answers 200 even when a sell fails: read outcome, which is failed or partial while positions are left unsold, and each failed leg's error.



## OpenAPI

````yaml api-reference/openapi.json POST /positions/close
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/close:
    post:
      tags:
        - Account
      summary: Close positions
      description: >-
        Sells each position of this key's trading account in this key's mode,
        optionally only on one venue or market, through the same checks and
        limits as POST /v1/orders. Each sell sells only what is held less what
        open sells already offer, on the venue that holds it, so a close never
        sells more than the account holds. Each placed sell is read back before
        the response, so one the venue matched at once reads filled with its
        filled quantity and average price. Cancel open orders first to close
        everything. A close answers 200 even when a sell fails: read outcome,
        which is failed or partial while positions are left unsold, and each
        failed leg's error.
      operationId: closePositions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                client_order_id:
                  type: string
                  maxLength: 40
                  pattern: ^[A-Za-z0-9_-]{1,40}$
                  description: >-
                    Unique per API key, up to 40 characters. Each sell gets
                    `<client_order_id>-close-<hash>-<hash>`, returned only in
                    this response; replaying the id returns the sells already
                    placed and places only those that are missing.
                venue:
                  type: string
                  enum:
                    - kalshi
                    - polymarket
                    - polymarket_us
                    - hyperliquid
                  description: Only this venue. Defaults to every venue.
                market_id:
                  type: string
                  minLength: 1
                  maxLength: 512
                  description: >-
                    Only 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.
                max_slippage_bps:
                  type: integer
                  minimum: 0
                  maximum: 10000
                  description: >-
                    Furthest each sell may trade below the best bid as read when
                    it is placed, in basis points.
                limit_price:
                  type: string
                  description: >-
                    Lowest price per share each sell accepts. Without it the
                    close is a market close: ioc, each venue sell placed 1 cent
                    below the worst price its quantity reaches in that venue's
                    book and never below max_slippage_bps.
                time_in_force:
                  type: string
                  enum:
                    - gtc
                    - ioc
                  description: >-
                    With limit_price: gtc rests the unfilled part, ioc cancels
                    it. Defaults to gtc with limit_price and ioc without.
              required:
                - client_order_id
                - max_slippage_bps
              additionalProperties: false
            example:
              client_order_id: flatten-0001
              max_slippage_bps: 200
      responses:
        '200':
          description: One leg per position in scope
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      success:
                        type: boolean
                        enum:
                          - true
                      data:
                        type: object
                        properties:
                          outcome:
                            type: string
                            enum:
                              - placed
                              - partial
                              - failed
                              - nothing_to_close
                            description: >-
                              What the close did overall. placed: every position
                              that needed a sell has one. partial: some do, but
                              a sell failed or a venue could not be read.
                              failed: nothing that needed a sell got one.
                              nothing_to_close: no position in scope needed a
                              sell. A placed sell may still be filling or end
                              unfilled; read each leg.
                          legs:
                            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
                                client_order_id:
                                  type: string
                                  minLength: 1
                                quantity:
                                  type: string
                                  pattern: ^\d+(?:\.\d+)?$
                                status:
                                  type: string
                                  enum:
                                    - placed
                                    - replayed
                                    - failed
                                    - skipped
                                order:
                                  type: object
                                  nullable: true
                                  properties:
                                    id:
                                      type: string
                                      format: uuid
                                    client_order_id:
                                      type: string
                                      minLength: 1
                                    market_id:
                                      type: string
                                      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
                                    venue:
                                      type: string
                                      nullable: true
                                      enum:
                                        - kalshi
                                        - polymarket
                                        - polymarket_us
                                        - hyperliquid
                                    ticker:
                                      type: string
                                      nullable: true
                                      minLength: 1
                                    side:
                                      type: string
                                      nullable: true
                                      enum:
                                        - 'yes'
                                        - 'no'
                                    action:
                                      type: string
                                      enum:
                                        - buy
                                        - sell
                                    type:
                                      type: string
                                      enum:
                                        - limit
                                        - market
                                    time_in_force:
                                      type: string
                                      enum:
                                        - gtc
                                        - ioc
                                        - fok
                                        - gtd
                                    expires_at:
                                      type: string
                                      nullable: true
                                      format: date-time
                                    quantity:
                                      type: string
                                      pattern: ^\d+(?:\.\d+)?$
                                    filled_quantity:
                                      type: string
                                      pattern: ^\d+(?:\.\d+)?$
                                    remaining_quantity:
                                      type: string
                                      pattern: ^\d+(?:\.\d+)?$
                                      description: >-
                                        Shares still working on the venues: the
                                        unfilled size of each live venue order.
                                        Zero once the order is final, since a
                                        canceled, expired or rejected remainder
                                        no longer works.
                                    limit_price:
                                      type: string
                                    avg_fill_price:
                                      type: string
                                      nullable: true
                                      description: >-
                                        Average price per share filled,
                                        size-weighted across the venue orders
                                        that filled, excluding fees. Null until
                                        every filled venue order has a price.
                                    notional_usd:
                                      type: string
                                      pattern: ^\d+(?:\.\d+)?$
                                    filled_notional_usd:
                                      type: string
                                      nullable: true
                                      pattern: ^\d+(?:\.\d+)?$
                                    status:
                                      type: string
                                      enum:
                                        - pending
                                        - open
                                        - partially_filled
                                        - filled
                                        - canceled
                                        - rejected
                                        - expired
                                        - unconfirmed
                                        - needs_attention
                                        - cancel_requested
                                    venue_status:
                                      type: string
                                      nullable: true
                                    venue_order_id:
                                      type: string
                                      nullable: true
                                    status_reason:
                                      type: object
                                      nullable: true
                                      properties:
                                        code:
                                          type: string
                                          minLength: 1
                                        message:
                                          type: string
                                          minLength: 1
                                      required:
                                        - code
                                        - message
                                    legs:
                                      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+)?$
                                          filled_quantity:
                                            type: string
                                            pattern: ^\d+(?:\.\d+)?$
                                          limit_price:
                                            type: string
                                          avg_fill_price:
                                            type: string
                                            nullable: true
                                          status:
                                            type: string
                                            enum:
                                              - pending
                                              - open
                                              - partially_filled
                                              - filled
                                              - canceled
                                              - rejected
                                              - expired
                                              - unconfirmed
                                              - needs_attention
                                              - cancel_requested
                                          venue_status:
                                            type: string
                                            nullable: true
                                          venue_order_id:
                                            type: string
                                            nullable: true
                                          cancel_requested_at:
                                            type: string
                                            nullable: true
                                            format: date-time
                                          status_reason:
                                            type: object
                                            nullable: true
                                            properties:
                                              code:
                                                type: string
                                                minLength: 1
                                              message:
                                                type: string
                                                minLength: 1
                                            required:
                                              - code
                                              - message
                                        required:
                                          - venue
                                          - ticker
                                          - side
                                          - quantity
                                          - filled_quantity
                                          - limit_price
                                          - avg_fill_price
                                          - status
                                          - venue_status
                                          - venue_order_id
                                          - cancel_requested_at
                                          - status_reason
                                    post_only:
                                      type: boolean
                                    replaces_order_id:
                                      type: string
                                      nullable: true
                                      format: uuid
                                    replaced_by_order_id:
                                      type: string
                                      nullable: true
                                      format: uuid
                                    created_at:
                                      type: string
                                      format: date-time
                                    updated_at:
                                      type: string
                                      format: date-time
                                    livemode:
                                      type: boolean
                                  required:
                                    - id
                                    - client_order_id
                                    - market_id
                                    - title
                                    - outcome
                                    - venue
                                    - ticker
                                    - side
                                    - action
                                    - type
                                    - time_in_force
                                    - expires_at
                                    - quantity
                                    - filled_quantity
                                    - remaining_quantity
                                    - limit_price
                                    - avg_fill_price
                                    - notional_usd
                                    - filled_notional_usd
                                    - status
                                    - venue_status
                                    - venue_order_id
                                    - status_reason
                                    - legs
                                    - post_only
                                    - replaces_order_id
                                    - replaced_by_order_id
                                    - created_at
                                    - updated_at
                                    - livemode
                                error:
                                  type: object
                                  nullable: true
                                  properties:
                                    code:
                                      type: string
                                      minLength: 1
                                    message:
                                      type: string
                                      minLength: 1
                                    details:
                                      nullable: true
                                  required:
                                    - code
                                    - message
                              required:
                                - venue
                                - ticker
                                - side
                                - market_id
                                - client_order_id
                                - quantity
                                - status
                                - order
                                - error
                          unavailable_venues:
                            type: array
                            items:
                              type: string
                              enum:
                                - kalshi
                                - polymarket
                                - polymarket_us
                                - hyperliquid
                          livemode:
                            type: boolean
                        required:
                          - outcome
                          - legs
                          - unavailable_venues
                          - 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:
                  outcome: placed
                  legs:
                    - venue: hyperliquid
                      ticker: hl:9999
                      side: 'yes'
                      market_id: >-
                        mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                      client_order_id: flatten-0001-close-9c1e4a7b-3f20d8e6
                      quantity: '10'
                      status: placed
                      order:
                        id: 5d9b2f71-0c3e-4a86-b7d4-1e6f8a2c9b05
                        client_order_id: flatten-0001-close-9c1e4a7b-3f20d8e6
                        market_id: >-
                          mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                        title: >-
                          Denver Broncos at Los Angeles Chargers: DEN -3.5,
                          Denver Broncos -3.5
                        outcome: DEN
                        venue: null
                        ticker: null
                        side: null
                        action: sell
                        type: limit
                        time_in_force: ioc
                        expires_at: null
                        quantity: '10'
                        filled_quantity: '10'
                        remaining_quantity: '0'
                        limit_price: '0.53'
                        avg_fill_price: '0.54'
                        notional_usd: '5.4'
                        filled_notional_usd: '5.4'
                        status: filled
                        venue_status: null
                        venue_order_id: null
                        status_reason: null
                        legs: []
                        post_only: false
                        replaces_order_id: null
                        replaced_by_order_id: null
                        created_at: '2026-10-29T18:00:00.000Z'
                        updated_at: '2026-10-29T18:00:00.000Z'
                        livemode: false
                      error: null
                  unavailable_venues: []
                  livemode: false
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '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'
              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
        '409':
          description: >-
            client_order_id was already used for a close with different
            parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: CONFLICT
                  message: >-
                    client_order_id was already used for a close with different
                    parameters
                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: Order placement is paused for this key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: FEATURE_DISABLED
                  message: Order placement is paused for this key
                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.