> ## 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 an order

> Runs the same checks as POST /v1/orders on the same body and returns what it would do: the venue legs, the expected average price, the route a buy would take and whether the order would be refused before reaching a venue. Nothing is placed or reserved.



## OpenAPI

````yaml api-reference/openapi.json POST /orders/preview
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:
    post:
      tags:
        - Orders
      summary: Preview an order
      description: >-
        Runs the same checks as POST /v1/orders on the same body and returns
        what it would do: the venue legs, the expected average price, the route
        a buy would take and whether the order would be refused before reaching
        a venue. Nothing is placed or reserved.
      operationId: previewOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              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
            example:
              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
      responses:
        '200':
          description: >-
            What POST /v1/orders would do with this body and the best route
            across venues; places and reserves nothing
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      success:
                        type: boolean
                        enum:
                          - true
                      data:
                        type: object
                        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
                      meta:
                        type: object
                        properties:
                          timestampMs:
                            type: integer
                            minimum: 0
                          requestId:
                            type: string
                            minLength: 1
                          traceId:
                            type: string
                            minLength: 1
                          cachedAtMs:
                            type: integer
                            minimum: 0
                          source:
                            type: string
                            enum:
                              - cache
                              - database
                              - clickhouse
                              - upstream
                              - fallback
                              - internal
                        required:
                          - timestampMs
                          - requestId
                    required:
                      - success
                      - data
                      - meta
                  - $ref: '#/components/schemas/ApiError'
              examples:
                Would submit:
                  summary: POST /v1/orders would place this
                  value:
                    success: true
                    data:
                      market_id: >-
                        mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                      action: buy
                      quantity: '5'
                      limit_price: '0.50'
                      type: limit
                      time_in_force: ioc
                      expires_at: null
                      execution:
                        venue: hyperliquid
                        ticker: <venue ticker>
                        side: 'yes'
                        notional_usd: '2.5'
                        max_slippage_bps: 700
                        executable_quantity: '5'
                        expected_average_price: '0.47'
                        legs:
                          - venue: hyperliquid
                            ticker: <venue ticker>
                            side: 'yes'
                            quantity: '5'
                            limit_price: '0.50'
                            notional_usd: '2.5'
                            expected_fill_quantity: '5'
                            expected_average_price: '0.47'
                            expected_fee_usd: '0'
                            expected_resting_fee_usd: '0'
                          - venue: hyperliquid
                            ticker: <venue ticker>
                            side: 'yes'
                            quantity: '5'
                            limit_price: '0.50'
                            notional_usd: '2.5'
                            expected_fill_quantity: '5'
                            expected_average_price: '0.47'
                            expected_fee_usd: '0'
                            expected_resting_fee_usd: '0'
                      would_submit: true
                      route_plan:
                        market_id: >-
                          mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                        action: buy
                        quantity: '5'
                        executable_quantity: '5'
                        average_price: '0.47'
                        legs:
                          - venue: hyperliquid
                            ticker: <venue ticker>
                            side: 'yes'
                            quantity: '5'
                            average_price: '0.47'
                            limit_price: '0.50'
                            fee_usd: '0'
                            executable: true
                          - venue: hyperliquid
                            ticker: <venue ticker>
                            side: 'yes'
                            quantity: '5'
                            average_price: '0.47'
                            limit_price: '0.50'
                            fee_usd: '0'
                            executable: true
                        expected_total_usd: '2.35'
                        max_total_usd: '2.5'
                        network_cost_usd: '0'
                        limited_by: null
                        quoted_at: '2026-10-11T18:00:00.000Z'
                        expires_at: '2026-10-11T18:00:15.000Z'
                        livemode: true
                      route: null
                      warnings: []
                      livemode: true
                    meta:
                      timestampMs: 1791741600000
                      requestId: 0e7a3c91-5f2b-4d84-9c16-a8b4e2d7f031
                Would be refused:
                  summary: Above the key limit; would_submit is false
                  value:
                    success: true
                    data:
                      market_id: >-
                        mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                      action: buy
                      quantity: '50'
                      limit_price: '0.50'
                      type: limit
                      time_in_force: ioc
                      expires_at: null
                      execution: null
                      would_submit: false
                      route_plan:
                        market_id: >-
                          mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                        action: buy
                        quantity: '50'
                        executable_quantity: '50'
                        average_price: '0.47'
                        legs:
                          - venue: hyperliquid
                            ticker: <venue ticker>
                            side: 'yes'
                            quantity: '50'
                            average_price: '0.47'
                            limit_price: '0.50'
                            fee_usd: '0'
                            executable: true
                          - venue: hyperliquid
                            ticker: <venue ticker>
                            side: 'yes'
                            quantity: '50'
                            average_price: '0.47'
                            limit_price: '0.50'
                            fee_usd: '0'
                            executable: true
                        expected_total_usd: '23.5'
                        max_total_usd: '25'
                        network_cost_usd: '0'
                        limited_by: null
                        quoted_at: '2026-10-11T18:00:00.000Z'
                        expires_at: '2026-10-11T18:00:15.000Z'
                        livemode: true
                      route: null
                      warnings:
                        - code: ORDER_NOTIONAL_LIMIT
                          message: Order notional exceeds this key's per-order limit
                        - code: ORDER_NOTIONAL_LIMIT
                          message: Order notional exceeds this key's per-order limit
                      livemode: true
                    meta:
                      timestampMs: 1791741600000
                      requestId: 0e7a3c91-5f2b-4d84-9c16-a8b4e2d7f031
                Insufficient funds:
                  summary: No venue that could place it has the cash
                  value:
                    success: true
                    data:
                      market_id: >-
                        mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                      action: buy
                      quantity: '5'
                      limit_price: '0.50'
                      type: limit
                      time_in_force: ioc
                      expires_at: null
                      execution: null
                      would_submit: false
                      route_plan:
                        market_id: >-
                          mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                        action: buy
                        quantity: '5'
                        executable_quantity: '5'
                        average_price: '0.47'
                        legs:
                          - venue: hyperliquid
                            ticker: <venue ticker>
                            side: 'yes'
                            quantity: '5'
                            average_price: '0.47'
                            limit_price: '0.50'
                            fee_usd: '0'
                            executable: true
                          - venue: hyperliquid
                            ticker: <venue ticker>
                            side: 'yes'
                            quantity: '5'
                            average_price: '0.47'
                            limit_price: '0.50'
                            fee_usd: '0'
                            executable: true
                        expected_total_usd: '2.35'
                        max_total_usd: '2.5'
                        network_cost_usd: '0'
                        limited_by: null
                        quoted_at: '2026-10-11T18:00:00.000Z'
                        expires_at: '2026-10-11T18:00:15.000Z'
                        livemode: true
                      route: null
                      warnings:
                        - code: INSUFFICIENT_FUNDS
                          message: >-
                            The trading account cannot pay for this order on the
                            venues that could place it
                        - code: INSUFFICIENT_FUNDS
                          message: >-
                            The trading account cannot pay for this order on the
                            venues that could place it
                      livemode: true
                    meta:
                      timestampMs: 1791741600000
                      requestId: 0e7a3c91-5f2b-4d84-9c16-a8b4e2d7f031
                Test key:
                  summary: A test key's plan is simulated over the public order books
                  value:
                    success: true
                    data:
                      market_id: >-
                        mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                      action: buy
                      quantity: '5'
                      limit_price: '0.50'
                      type: limit
                      time_in_force: ioc
                      expires_at: null
                      execution:
                        venue: hyperliquid
                        ticker: <venue ticker>
                        side: 'yes'
                        notional_usd: '2.5'
                        max_slippage_bps: 700
                        executable_quantity: '5'
                        expected_average_price: '0.47'
                        legs:
                          - venue: hyperliquid
                            ticker: <venue ticker>
                            side: 'yes'
                            quantity: '5'
                            limit_price: '0.50'
                            notional_usd: '2.5'
                            expected_fill_quantity: '5'
                            expected_average_price: '0.47'
                            expected_fee_usd: '0'
                            expected_resting_fee_usd: '0'
                          - venue: hyperliquid
                            ticker: <venue ticker>
                            side: 'yes'
                            quantity: '5'
                            limit_price: '0.50'
                            notional_usd: '2.5'
                            expected_fill_quantity: '5'
                            expected_average_price: '0.47'
                            expected_fee_usd: '0'
                            expected_resting_fee_usd: '0'
                      would_submit: true
                      route_plan:
                        market_id: >-
                          mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                        action: buy
                        quantity: '5'
                        executable_quantity: '5'
                        average_price: '0.47'
                        legs:
                          - venue: hyperliquid
                            ticker: <venue ticker>
                            side: 'yes'
                            quantity: '5'
                            average_price: '0.47'
                            limit_price: '0.50'
                            fee_usd: '0'
                            executable: true
                          - venue: hyperliquid
                            ticker: <venue ticker>
                            side: 'yes'
                            quantity: '5'
                            average_price: '0.47'
                            limit_price: '0.50'
                            fee_usd: '0'
                            executable: true
                        expected_total_usd: '2.35'
                        max_total_usd: '2.5'
                        network_cost_usd: '0'
                        limited_by: null
                        quoted_at: '2026-10-11T18:00:00.000Z'
                        expires_at: '2026-10-11T18:00:15.000Z'
                        livemode: false
                      route: null
                      warnings: []
                      livemode: false
                    meta:
                      timestampMs: 1791741600000
                      requestId: 0e7a3c91-5f2b-4d84-9c16-a8b4e2d7f031
                Live trading off:
                  summary: >-
                    A live key on an account where live trading is not enabled
                    yet
                  value:
                    success: true
                    data:
                      market_id: >-
                        mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                      action: buy
                      quantity: '5'
                      limit_price: '0.50'
                      type: limit
                      time_in_force: ioc
                      expires_at: null
                      execution:
                        venue: hyperliquid
                        ticker: <venue ticker>
                        side: 'yes'
                        notional_usd: '2.5'
                        max_slippage_bps: 700
                        executable_quantity: '5'
                        expected_average_price: '0.47'
                        legs:
                          - venue: hyperliquid
                            ticker: <venue ticker>
                            side: 'yes'
                            quantity: '5'
                            limit_price: '0.50'
                            notional_usd: '2.5'
                            expected_fill_quantity: '5'
                            expected_average_price: '0.47'
                            expected_fee_usd: '0'
                            expected_resting_fee_usd: '0'
                          - venue: hyperliquid
                            ticker: <venue ticker>
                            side: 'yes'
                            quantity: '5'
                            limit_price: '0.50'
                            notional_usd: '2.5'
                            expected_fill_quantity: '5'
                            expected_average_price: '0.47'
                            expected_fee_usd: '0'
                            expected_resting_fee_usd: '0'
                      would_submit: false
                      route_plan:
                        market_id: >-
                          mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                        action: buy
                        quantity: '5'
                        executable_quantity: '5'
                        average_price: '0.47'
                        legs:
                          - venue: hyperliquid
                            ticker: <venue ticker>
                            side: 'yes'
                            quantity: '5'
                            average_price: '0.47'
                            limit_price: '0.50'
                            fee_usd: '0'
                            executable: true
                          - venue: hyperliquid
                            ticker: <venue ticker>
                            side: 'yes'
                            quantity: '5'
                            average_price: '0.47'
                            limit_price: '0.50'
                            fee_usd: '0'
                            executable: true
                        expected_total_usd: '2.35'
                        max_total_usd: '2.5'
                        network_cost_usd: '0'
                        limited_by: null
                        quoted_at: '2026-10-11T18:00:00.000Z'
                        expires_at: '2026-10-11T18:00:15.000Z'
                        livemode: true
                      route: null
                      warnings:
                        - code: TRADING_UNAVAILABLE
                          message: >-
                            Live order placement is switched off. Test keys can
                            still place simulated orders.
                        - code: TRADING_UNAVAILABLE
                          message: >-
                            Live order placement is switched off. Test keys can
                            still place simulated orders.
                      livemode: true
                    meta:
                      timestampMs: 1791741600000
                      requestId: 0e7a3c91-5f2b-4d84-9c16-a8b4e2d7f031
        '400':
          description: The order terms are invalid or no venue takes them
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                market_gtc:
                  summary: A market order that would rest
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: market orders need time_in_force ioc or fok
                    meta:
                      timestampMs: 1792771200000
                      requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
                gtd_on_hyperliquid:
                  summary: gtd with only a Hyperliquid listing
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: >-
                        gtd orders are placed on Kalshi, Polymarket, or
                        Polymarket US, since Hyperliquid has no order expiry,
                        and this order has none of them to go to
                    meta:
                      timestampMs: 1792771200000
                      requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
                gtd_without_expiry:
                  summary: gtd without expires_at
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: gtd orders need expires_at
                    meta:
                      timestampMs: 1792771200000
                      requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
                Bad limit price:
                  summary: limit_price outside (0, 1)
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: limit_price must be strictly between 0 and 1
                    meta:
                      timestampMs: 1791741600000
                      requestId: 0e7a3c91-5f2b-4d84-9c16-a8b4e2d7f031
        '401':
          description: Missing, invalid, expired or revoked API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                Unknown key:
                  summary: Unknown, expired or revoked key
                  value:
                    success: false
                    error:
                      code: UNAUTHORIZED
                      message: Invalid, expired or revoked API key
                    meta:
                      timestampMs: 1791741600000
                      requestId: 0e7a3c91-5f2b-4d84-9c16-a8b4e2d7f031
                Missing key:
                  summary: No Authorization header
                  value:
                    success: false
                    error:
                      code: UNAUTHORIZED
                      message: Missing API key
                    meta:
                      timestampMs: 1791741600000
                      requestId: 0e7a3c91-5f2b-4d84-9c16-a8b4e2d7f031
        '403':
          description: The key lacks the scope this route needs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                Missing scope:
                  summary: The key lacks the read scope
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: This API key lacks the read scope
                    meta:
                      timestampMs: 1791741600000
                      requestId: 0e7a3c91-5f2b-4d84-9c16-a8b4e2d7f031
        '404':
          description: API error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                Not found:
                  summary: Market not found
                  value:
                    success: false
                    error:
                      code: NOT_FOUND
                      message: Market not found
                    meta:
                      timestampMs: 1791741600000
                      requestId: 0e7a3c91-5f2b-4d84-9c16-a8b4e2d7f031
        '409':
          description: >-
            A venue has stopped trading the market, so it has no book to quote;
            details.reason is MARKET_NOT_TRADABLE
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                market_not_tradable:
                  summary: The venue stopped trading the market
                  value:
                    success: false
                    error:
                      code: CONFLICT
                      message: Polymarket has stopped trading this market
                      details:
                        reason: MARKET_NOT_TRADABLE
                    meta:
                      timestampMs: 1792771200000
                      requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '422':
          description: The body is sized wrong; nothing was checked further
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                quantity_and_notional:
                  summary: Both or neither of quantity and notional
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Send exactly one of quantity or notional
                    meta:
                      timestampMs: 1792771200000
                      requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
                notional_gtc:
                  summary: notional on a resting order
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: >-
                        notional needs time_in_force ioc or fok; size a resting
                        order with quantity
                    meta:
                      timestampMs: 1792771200000
                      requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
                notional_sell:
                  summary: notional on a sell
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: notional sizes buys only; size a sell with quantity
                    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'
              examples:
                Rate limited:
                  summary: Over 5 requests a second; wait for Retry-After
                  value:
                    success: false
                    error:
                      code: RATE_LIMITED
                      message: Too many requests for this API key
                    meta:
                      timestampMs: 1791741600000
                      requestId: 0e7a3c91-5f2b-4d84-9c16-a8b4e2d7f031
        '500':
          description: API error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                Internal error:
                  summary: Unexpected server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An internal error occurred.
                    meta:
                      timestampMs: 1791741600000
                      requestId: 0e7a3c91-5f2b-4d84-9c16-a8b4e2d7f031
        '503':
          description: A venue failed or did not answer, or routing is paused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                Venue error:
                  summary: The venue failed or did not answer
                  value:
                    success: false
                    error:
                      code: UPSTREAM_ERROR
                      message: A required service is temporarily unavailable.
                    meta:
                      timestampMs: 1791741600000
                      requestId: 0e7a3c91-5f2b-4d84-9c16-a8b4e2d7f031
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.