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

# Preview several orders

> Previews up to 25 order bodies in one call, each exactly as POST /v1/orders/preview previews it, and runs them at once, so a batch takes about as long as its slowest preview. Each body is previewed on its own: the batch does not add the notional of one body to another's limit checks. One body that cannot be previewed does not stop the rest; its result carries the status and error the single preview answers with. Results are in the order the bodies were sent. Nothing is placed or reserved, and the call counts once against the key's rate limit.



## OpenAPI

````yaml api-reference/openapi.json POST /orders/preview-batch
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:
  /orders/preview-batch:
    post:
      tags:
        - Orders
      summary: Preview several orders
      description: >-
        Previews up to 25 order bodies in one call, each exactly as POST
        /v1/orders/preview previews it, and runs them at once, so a batch takes
        about as long as its slowest preview. Each body is previewed on its own:
        the batch does not add the notional of one body to another's limit
        checks. One body that cannot be previewed does not stop the rest; its
        result carries the status and error the single preview answers with.
        Results are in the order the bodies were sent. Nothing is placed or
        reserved, and the call counts once against the key's rate limit.
      operationId: previewOrdersBatch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                orders:
                  type: array
                  items:
                    type: object
                    properties:
                      client_order_id:
                        type: string
                        pattern: ^[A-Za-z0-9_-]{1,64}$
                        description: >-
                          Unique per API key. Replaying an id returns the
                          original order.
                      market_id:
                        type: string
                        minLength: 1
                        maxLength: 512
                        description: >-
                          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. An order named by a venue
                          symbol trades only that listing, so it is refused when
                          `venues` leaves out the symbol's venue. A buy routed
                          automatically still buys that listing, paid from the
                          other venue. The order is stored under the market id.
                      action:
                        type: string
                        enum:
                          - buy
                          - sell
                      quantity:
                        type: string
                        pattern: ^\d+(?:\.\d+)?$
                        description: >-
                          Shares, in 0.01 steps. Send exactly one of quantity or
                          notional. A sell of the whole position, as held or
                          written to two decimals, sells what each venue's
                          increment allows and keeps the rest.
                      notional:
                        type: string
                        pattern: ^\d+(?:\.\d{1,2})?$
                        description: >-
                          Dollars to spend on an ioc or fok buy, in place of
                          quantity, at most two decimals. The buy walks the
                          books from the best price and never spends more than
                          this before fees; Lean works out the shares. Sells and
                          resting orders are sized with quantity.
                      limit_price:
                        type: string
                        description: >-
                          Worst price per share you accept, in dollars. Required
                          with quantity on a limit order. With notional or on a
                          market order it defaults to 0.99 for a buy and 0.01
                          for a sell; a market order is then placed 1 cent past
                          the worst price its quantity reaches in the book,
                          tightened by max_slippage_bps when set.
                      type:
                        type: string
                        enum:
                          - limit
                          - market
                        default: limit
                        description: >-
                          limit trades at limit_price or better. market trades
                          at once at the best prices: it needs time_in_force ioc
                          or fok, and each venue order is placed 1 cent past the
                          worst price its quantity reaches in the book of that
                          venue. limit_price and max_slippage_bps are optional
                          extra caps on the worst price it accepts.
                      time_in_force:
                        type: string
                        enum:
                          - gtc
                          - ioc
                          - fok
                          - gtd
                        default: gtc
                        description: >-
                          gtc rests until filled or canceled. ioc fills what it
                          can at once and cancels the rest. fok fills the whole
                          order at once or cancels all of it, and is placed
                          whole on one venue: Polymarket, else Kalshi, else
                          Polymarket US, since Hyperliquid has no fill or kill.
                          gtd rests like gtc until expires_at, and is placed on
                          Kalshi, Polymarket and Polymarket US, since
                          Hyperliquid has no order expiry. Polymarket takes an
                          ioc or fok buy only by dollar amount: one sized with
                          notional can fill there, while one sized with quantity
                          goes only to the other venues, and when Polymarket is
                          the only one it is refused with 400 VALIDATION_ERROR,
                          so send it with notional or as gtc. notional needs ioc
                          or fok.
                      expires_at:
                        type: string
                        format: date-time
                        description: >-
                          When a gtd order expires, as an ISO 8601 time.
                          Required with gtd and refused with any other
                          time_in_force. At least 3 minutes and at most 30 days
                          ahead. Whatever has not filled by then is canceled,
                          and the order reads expired.
                      max_slippage_bps:
                        type: integer
                        minimum: 0
                        maximum: 10000
                        description: >-
                          Optional extra cap: the furthest each venue order may
                          trade from that venue's own best price, in basis
                          points; overrides the account's max_slippage_bps. Each
                          venue is measured against its own book, not the best
                          price across venues, so venues quoting different
                          prices can each fill. Never looser than limit_price.
                          Without one, a limit order trades to its limit and a
                          market order to 1 cent past the worst price its
                          quantity reaches in the book, as the Lean trading
                          terminal places it.
                      all_or_none:
                        type: boolean
                        default: false
                        description: >-
                          Refuse the order unless the books, as read, fill the
                          whole quantity within the slippage bound. Needs
                          time_in_force ioc or fok. Best effort: venue orders
                          are placed separately and books can move between the
                          read and the fill, so a partial fill is still
                          possible.
                      post_only:
                        type: boolean
                        default: false
                        description: >-
                          Only rest on the book, never take. Needs time_in_force
                          gtc, cannot take best_price, and is placed on Kalshi,
                          Polymarket US and Hyperliquid, since Polymarket cannot
                          rest post-only. An order that would trade at once
                          against the books, as read, is refused with reason
                          POST_ONLY_WOULD_CROSS, and the venue rejects one that
                          would trade by the time it arrives.
                      venues:
                        type: array
                        items:
                          type: string
                          enum:
                            - kalshi
                            - polymarket
                            - polymarket_us
                            - hyperliquid
                        minItems: 1
                        description: >-
                          Only these venues may fill or fund the order, within
                          the account's allowed venues. A single venue sends the
                          order only there, and the order is refused if that
                          venue can't fill it. Omit to use every allowed venue.
                      best_price:
                        type: boolean
                        default: false
                        description: >-
                          Buy at the best price across venues: when a route
                          across venues that moves cash from another venue would
                          cost less in all than buying where the account's cash
                          is, the buy goes through that route. Needs the route
                          scope. A test key prices a route at the order's limit,
                          so there it wins only when the direct buy's fees cost
                          more. Sells already sell across every venue that holds
                          shares, so this does not change them.
                    required:
                      - client_order_id
                      - market_id
                      - action
                    additionalProperties: false
                  minItems: 1
                  maxItems: 25
                  description: >-
                    Between 1 and 25 bodies of POST /v1/orders, each previewed
                    as POST /v1/orders/preview previews it. A body that fails
                    validation refuses the whole batch with 400.
              required:
                - orders
            example:
              orders:
                - client_order_id: bot-0001
                  market_id: >-
                    mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                  action: buy
                  type: limit
                  quantity: '10'
                  limit_price: '0.55'
                  time_in_force: gtc
                  all_or_none: false
                  post_only: false
                  best_price: false
                - client_order_id: bot-0002
                  market_id: mkt_unknown
                  action: buy
                  type: limit
                  quantity: '10'
                  limit_price: '0.55'
                  time_in_force: gtc
                  all_or_none: false
                  post_only: false
                  best_price: false
      responses:
        '200':
          description: One result per body, in the order sent; places and reserves nothing
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      success:
                        type: boolean
                        enum:
                          - true
                      data:
                        type: object
                        properties:
                          results:
                            type: array
                            items:
                              type: object
                              properties:
                                status:
                                  type: integer
                                  description: >-
                                    The HTTP status POST /v1/orders/preview
                                    answers this body with: 200 with `preview`,
                                    otherwise the status of `error`.
                                preview:
                                  type: object
                                  nullable: true
                                  properties:
                                    market_id:
                                      type: string
                                      minLength: 1
                                      description: >-
                                        The market id from GET /markets, however
                                        the request named the market.
                                    action:
                                      type: string
                                      enum:
                                        - buy
                                        - sell
                                    quantity:
                                      type: string
                                      pattern: ^\d+(?:\.\d+)?$
                                    limit_price:
                                      type: string
                                    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
                                    execution:
                                      type: object
                                      nullable: true
                                      properties:
                                        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'
                                        notional_usd:
                                          type: string
                                          pattern: ^\d+(?:\.\d+)?$
                                        max_slippage_bps:
                                          type: integer
                                          nullable: true
                                          minimum: 0
                                          maximum: 10000
                                        executable_quantity:
                                          type: string
                                          pattern: ^\d+(?:\.\d+)?$
                                        expected_average_price:
                                          type: string
                                          nullable: true
                                        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+)?$
                                              limit_price:
                                                type: string
                                              notional_usd:
                                                type: string
                                                pattern: ^\d+(?:\.\d+)?$
                                              expected_fill_quantity:
                                                type: string
                                                pattern: ^\d+(?:\.\d+)?$
                                              expected_average_price:
                                                type: string
                                                nullable: true
                                              expected_fee_usd:
                                                type: string
                                                pattern: ^\d+(?:\.\d+)?$
                                              expected_resting_fee_usd:
                                                type: string
                                                pattern: ^\d+(?:\.\d+)?$
                                            required:
                                              - venue
                                              - ticker
                                              - side
                                              - quantity
                                              - limit_price
                                              - notional_usd
                                              - expected_fill_quantity
                                              - expected_average_price
                                              - expected_fee_usd
                                              - expected_resting_fee_usd
                                      required:
                                        - venue
                                        - ticker
                                        - side
                                        - notional_usd
                                        - max_slippage_bps
                                        - executable_quantity
                                        - expected_average_price
                                        - legs
                                    would_submit:
                                      type: boolean
                                    route_plan:
                                      type: object
                                      nullable: true
                                      properties:
                                        market_id:
                                          type: string
                                          minLength: 1
                                          description: >-
                                            The market id from GET /markets, however
                                            the request named the market.
                                        action:
                                          type: string
                                          enum:
                                            - buy
                                            - sell
                                        quantity:
                                          type: string
                                          pattern: ^\d+(?:\.\d+)?$
                                        executable_quantity:
                                          type: string
                                          pattern: ^\d+(?:\.\d+)?$
                                        average_price:
                                          type: string
                                          nullable: true
                                        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+)?$
                                              average_price:
                                                type: string
                                              limit_price:
                                                type: string
                                              fee_usd:
                                                type: string
                                                pattern: ^\d+(?:\.\d+)?$
                                              executable:
                                                type: boolean
                                            required:
                                              - venue
                                              - ticker
                                              - side
                                              - quantity
                                              - average_price
                                              - limit_price
                                              - fee_usd
                                              - executable
                                        expected_total_usd:
                                          type: string
                                          pattern: ^\d+(?:\.\d+)?$
                                        max_total_usd:
                                          type: string
                                          pattern: ^\d+(?:\.\d+)?$
                                        network_cost_usd:
                                          type: string
                                          pattern: ^\d+(?:\.\d+)?$
                                        limited_by:
                                          type: string
                                          nullable: true
                                        quoted_at:
                                          type: string
                                          format: date-time
                                        expires_at:
                                          type: string
                                          format: date-time
                                        livemode:
                                          type: boolean
                                      required:
                                        - market_id
                                        - action
                                        - quantity
                                        - executable_quantity
                                        - average_price
                                        - legs
                                        - expected_total_usd
                                        - max_total_usd
                                        - network_cost_usd
                                        - limited_by
                                        - quoted_at
                                        - expires_at
                                        - livemode
                                    route:
                                      type: object
                                      nullable: true
                                      properties:
                                        funding_venue:
                                          type: string
                                          enum:
                                            - polymarket
                                            - hyperliquid
                                        execution_venue:
                                          type: string
                                          enum:
                                            - polymarket
                                            - hyperliquid
                                        notional_usd:
                                          type: string
                                          pattern: ^\d+(?:\.\d+)?$
                                        costs:
                                          type: object
                                          properties:
                                            rebalance_fee_usd:
                                              type: string
                                              pattern: ^\d+(?:\.\d+)?$
                                            gas_usd:
                                              type: string
                                              pattern: ^\d+(?:\.\d+)?$
                                            activation_fee_usd:
                                              type: string
                                              pattern: ^\d+(?:\.\d+)?$
                                            network_cost_usd:
                                              type: string
                                              pattern: ^\d+(?:\.\d+)?$
                                          required:
                                            - rebalance_fee_usd
                                            - gas_usd
                                            - activation_fee_usd
                                            - network_cost_usd
                                      required:
                                        - funding_venue
                                        - execution_venue
                                        - notional_usd
                                        - costs
                                    warnings:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          code:
                                            type: string
                                            enum:
                                              - BELOW_VENUE_MINIMUM
                                              - ORDER_NOTIONAL_LIMIT
                                              - DAILY_NOTIONAL_LIMIT
                                              - NO_EXECUTABLE_VENUE
                                              - VENUE_NOT_ALLOWED
                                              - INSUFFICIENT_FUNDS
                                              - INSUFFICIENT_HOLDINGS
                                              - INSUFFICIENT_DEPTH
                                              - POST_ONLY_WOULD_CROSS
                                              - CLIENT_ORDER_ID_USED
                                              - TRADING_UNAVAILABLE
                                              - ROUTE_LIMITED
                                              - ROUTE_UNAVAILABLE
                                          message:
                                            type: string
                                            minLength: 1
                                        required:
                                          - code
                                          - message
                                    livemode:
                                      type: boolean
                                  required:
                                    - market_id
                                    - action
                                    - quantity
                                    - limit_price
                                    - type
                                    - time_in_force
                                    - expires_at
                                    - execution
                                    - would_submit
                                    - route_plan
                                    - route
                                    - warnings
                                    - livemode
                                  description: >-
                                    What POST /v1/orders/preview answers for
                                    this body; null when it answers with an
                                    error.
                                error:
                                  type: object
                                  nullable: true
                                  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
                                  description: >-
                                    The error POST /v1/orders/preview answers
                                    this body with, with the same code, message
                                    and details; null when it previews.
                              required:
                                - status
                                - preview
                                - error
                          livemode:
                            type: boolean
                        required:
                          - results
                          - 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:
                  results:
                    - status: 200
                      preview:
                        market_id: >-
                          mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                        action: buy
                        quantity: '10'
                        limit_price: '0.55'
                        type: limit
                        time_in_force: gtc
                        expires_at: null
                        execution:
                          venue: hyperliquid
                          ticker: hl:9999
                          side: 'yes'
                          notional_usd: '5.5'
                          max_slippage_bps: 100
                          executable_quantity: '10'
                          expected_average_price: '0.53'
                          legs:
                            - venue: hyperliquid
                              ticker: hl:9999
                              side: 'yes'
                              quantity: '10'
                              limit_price: '0.55'
                              notional_usd: '5.5'
                              expected_fill_quantity: '10'
                              expected_average_price: '0.53'
                              expected_fee_usd: '0'
                              expected_resting_fee_usd: '0'
                        would_submit: true
                        route_plan: null
                        route: null
                        warnings: []
                        livemode: false
                      error: null
                    - status: 404
                      preview: null
                      error:
                        code: NOT_FOUND
                        message: Market not found
                  livemode: false
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '400':
          description: >-
            The body is not a list of 1 to 25 valid order bodies; nothing was
            previewed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: VALIDATION_ERROR
                  message: The body is not a list of 1 to 25 valid order bodies
                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.