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

# Create an order

> The default way to buy across venues, in one call. Lean places the order on the venues that can fill it. A buy the account cannot pay for on those venues is bought through a route across venues instead when routing is on and the key has the route scope: Lean moves the money from the funding venue and buys on the execution venue, and `route` names both. A live key also needs the account to have enabled trading in the Lean app, because Lean signs the payment with its delegated signer; a test key routes against the simulator and never signs. Without a route, a buy the account cannot pay for is refused. To sign route payments yourself, use POST /v1/routed-orders and POST /v1/routed-orders/{id}/execute instead.



## OpenAPI

````yaml api-reference/openapi.json POST /orders
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:
    post:
      tags:
        - Orders
      summary: Place an order
      description: >-
        The default way to buy across venues, in one call. Lean places the order
        on the venues that can fill it. A buy the account cannot pay for on
        those venues is bought through a route across venues instead when
        routing is on and the key has the route scope: Lean moves the money from
        the funding venue and buys on the execution venue, and `route` names
        both. A live key also needs the account to have enabled trading in the
        Lean app, because Lean signs the payment with its delegated signer; a
        test key routes against the simulator and never signs. Without a route,
        a buy the account cannot pay for is refused. To sign route payments
        yourself, use POST /v1/routed-orders and POST
        /v1/routed-orders/{id}/execute instead.
      operationId: createOrder
      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: >-
            The order as recorded after every venue answered, or the original on
            replay. Venue outcomes are statuses, not errors: an ioc reads
            canceled with status_reason.code IOC_REMAINDER_CANCELED when the
            venue canceled what did not fill at once, with filled_quantity 0 if
            nothing matched, a venue rejection reads rejected, and a submit the
            venue did not confirm reads unconfirmed. Each leg carries its own
            status and status_reason. A routed buy has no legs and `route` names
            its funding and execution venues: a live one stays pending while the
            router moves the payment, and a test one is filled by the simulator
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      success:
                        type: boolean
                        enum:
                          - true
                      data:
                        type: object
                        properties:
                          id:
                            type: string
                            format: uuid
                          client_order_id:
                            type: string
                            minLength: 1
                          market_id:
                            type: string
                            minLength: 1
                            description: >-
                              The market id from GET /markets, however the
                              request named the market.
                          title:
                            type: string
                            nullable: true
                            minLength: 1
                          outcome:
                            type: string
                            nullable: true
                            minLength: 1
                          venue:
                            type: string
                            nullable: true
                            enum:
                              - kalshi
                              - polymarket
                              - polymarket_us
                              - hyperliquid
                          ticker:
                            type: string
                            nullable: true
                            minLength: 1
                          side:
                            type: string
                            nullable: true
                            enum:
                              - 'yes'
                              - 'no'
                          action:
                            type: string
                            enum:
                              - buy
                              - sell
                          type:
                            type: string
                            enum:
                              - limit
                              - market
                          time_in_force:
                            type: string
                            enum:
                              - gtc
                              - ioc
                              - fok
                              - gtd
                          expires_at:
                            type: string
                            nullable: true
                            format: date-time
                          quantity:
                            type: string
                            pattern: ^\d+(?:\.\d+)?$
                          filled_quantity:
                            type: string
                            pattern: ^\d+(?:\.\d+)?$
                          remaining_quantity:
                            type: string
                            pattern: ^\d+(?:\.\d+)?$
                            description: >-
                              Shares still working on the venues: the unfilled
                              size of each live venue order. Zero once the order
                              is final, since a canceled, expired or rejected
                              remainder no longer works.
                          limit_price:
                            type: string
                          avg_fill_price:
                            type: string
                            nullable: true
                            description: >-
                              Average price per share filled, size-weighted
                              across the venue orders that filled, excluding
                              fees. Null until every filled venue order has a
                              price.
                          notional_usd:
                            type: string
                            pattern: ^\d+(?:\.\d+)?$
                          filled_notional_usd:
                            type: string
                            nullable: true
                            pattern: ^\d+(?:\.\d+)?$
                          status:
                            type: string
                            enum:
                              - pending
                              - open
                              - partially_filled
                              - filled
                              - canceled
                              - rejected
                              - expired
                              - unconfirmed
                              - needs_attention
                              - cancel_requested
                          venue_status:
                            type: string
                            nullable: true
                          venue_order_id:
                            type: string
                            nullable: true
                          status_reason:
                            type: object
                            nullable: true
                            properties:
                              code:
                                type: string
                                minLength: 1
                              message:
                                type: string
                                minLength: 1
                            required:
                              - code
                              - message
                          legs:
                            type: array
                            items:
                              type: object
                              properties:
                                venue:
                                  type: string
                                  enum:
                                    - kalshi
                                    - polymarket
                                    - polymarket_us
                                    - hyperliquid
                                ticker:
                                  type: string
                                  minLength: 1
                                side:
                                  type: string
                                  enum:
                                    - 'yes'
                                    - 'no'
                                quantity:
                                  type: string
                                  pattern: ^\d+(?:\.\d+)?$
                                filled_quantity:
                                  type: string
                                  pattern: ^\d+(?:\.\d+)?$
                                limit_price:
                                  type: string
                                avg_fill_price:
                                  type: string
                                  nullable: true
                                status:
                                  type: string
                                  enum:
                                    - pending
                                    - open
                                    - partially_filled
                                    - filled
                                    - canceled
                                    - rejected
                                    - expired
                                    - unconfirmed
                                    - needs_attention
                                    - cancel_requested
                                venue_status:
                                  type: string
                                  nullable: true
                                venue_order_id:
                                  type: string
                                  nullable: true
                                cancel_requested_at:
                                  type: string
                                  nullable: true
                                  format: date-time
                                status_reason:
                                  type: object
                                  nullable: true
                                  properties:
                                    code:
                                      type: string
                                      minLength: 1
                                    message:
                                      type: string
                                      minLength: 1
                                  required:
                                    - code
                                    - message
                              required:
                                - venue
                                - ticker
                                - side
                                - quantity
                                - filled_quantity
                                - limit_price
                                - avg_fill_price
                                - status
                                - venue_status
                                - venue_order_id
                                - cancel_requested_at
                                - status_reason
                          post_only:
                            type: boolean
                          replaces_order_id:
                            type: string
                            nullable: true
                            format: uuid
                          replaced_by_order_id:
                            type: string
                            nullable: true
                            format: uuid
                          created_at:
                            type: string
                            format: date-time
                          updated_at:
                            type: string
                            format: date-time
                          livemode:
                            type: boolean
                          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
                        required:
                          - id
                          - client_order_id
                          - market_id
                          - title
                          - outcome
                          - venue
                          - ticker
                          - side
                          - action
                          - type
                          - time_in_force
                          - expires_at
                          - quantity
                          - filled_quantity
                          - remaining_quantity
                          - limit_price
                          - avg_fill_price
                          - notional_usd
                          - filled_notional_usd
                          - status
                          - venue_status
                          - venue_order_id
                          - status_reason
                          - legs
                          - post_only
                          - replaces_order_id
                          - replaced_by_order_id
                          - created_at
                          - updated_at
                          - livemode
                          - route
                      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:
                Filled:
                  summary: An ioc order that filled
                  value:
                    success: true
                    data:
                      id: 3f6c2a8e-91d4-4b7a-8c25-0e4d7b19a6f3
                      client_order_id: bot-2026-10-29-0001
                      market_id: >-
                        mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                      venue: hyperliquid
                      ticker: <venue ticker>
                      side: 'yes'
                      action: buy
                      type: limit
                      time_in_force: ioc
                      expires_at: null
                      quantity: '5'
                      filled_quantity: '5'
                      remaining_quantity: '0'
                      limit_price: '0.50'
                      avg_fill_price: '0.47'
                      notional_usd: '2.5'
                      filled_notional_usd: '2.35'
                      status: filled
                      venue_status: filled
                      venue_order_id: '91234567012'
                      status_reason: null
                      post_only: false
                      replaces_order_id: null
                      replaced_by_order_id: null
                      legs:
                        - venue: hyperliquid
                          ticker: <venue ticker>
                          side: 'yes'
                          quantity: '5'
                          filled_quantity: '5'
                          limit_price: '0.50'
                          avg_fill_price: '0.47'
                          status: filled
                          venue_status: filled
                          venue_order_id: '91234567012'
                          cancel_requested_at: null
                          status_reason: null
                        - venue: hyperliquid
                          ticker: <venue ticker>
                          side: 'yes'
                          quantity: '5'
                          filled_quantity: '5'
                          limit_price: '0.50'
                          avg_fill_price: '0.47'
                          status: filled
                          venue_status: filled
                          venue_order_id: '91234567012'
                          cancel_requested_at: null
                          status_reason: null
                      created_at: '2026-10-11T18:00:02.114Z'
                      updated_at: '2026-10-11T18:00:02.587Z'
                      livemode: true
                      route: null
                    meta:
                      timestampMs: 1791741602600
                      requestId: 9d2f6b18-3e7a-4c05-b8d1-4f0a7e2c6b93
                Resting:
                  summary: A gtc order on the book
                  value:
                    success: true
                    data:
                      id: 8a1e5c07-4b3f-4d62-9f18-2c7e0a95d4b1
                      client_order_id: bot-2026-10-29-0002
                      market_id: >-
                        mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                      venue: hyperliquid
                      ticker: <venue ticker>
                      side: 'yes'
                      action: buy
                      type: limit
                      time_in_force: gtc
                      expires_at: null
                      quantity: '10'
                      filled_quantity: '0'
                      remaining_quantity: '10'
                      limit_price: '0.45'
                      avg_fill_price: null
                      notional_usd: '4.5'
                      filled_notional_usd: '0'
                      status: open
                      venue_status: open
                      venue_order_id: '91234567388'
                      status_reason: null
                      post_only: false
                      replaces_order_id: null
                      replaced_by_order_id: null
                      legs:
                        - venue: hyperliquid
                          ticker: <venue ticker>
                          side: 'yes'
                          quantity: '10'
                          filled_quantity: '0'
                          limit_price: '0.45'
                          avg_fill_price: null
                          status: open
                          venue_status: open
                          venue_order_id: '91234567388'
                          cancel_requested_at: null
                          status_reason: null
                        - venue: hyperliquid
                          ticker: <venue ticker>
                          side: 'yes'
                          quantity: '10'
                          filled_quantity: '0'
                          limit_price: '0.45'
                          avg_fill_price: null
                          status: open
                          venue_status: open
                          venue_order_id: '91234567388'
                          cancel_requested_at: null
                          status_reason: null
                      created_at: '2026-10-11T18:04:40.902Z'
                      updated_at: '2026-10-11T18:04:41.317Z'
                      livemode: true
                      route: null
                    meta:
                      timestampMs: 1791741881330
                      requestId: 9d2f6b18-3e7a-4c05-b8d1-4f0a7e2c6b93
                Split:
                  summary: A buy split across two venues
                  value:
                    success: true
                    data:
                      id: 6b0f3d92-1e7c-4a85-b3d6-9c4a2f01e7b5
                      client_order_id: bot-2026-10-29-0003
                      market_id: >-
                        mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                      venue: null
                      ticker: null
                      side: null
                      action: buy
                      type: limit
                      time_in_force: ioc
                      expires_at: null
                      quantity: '40'
                      filled_quantity: '40'
                      remaining_quantity: '0'
                      limit_price: '0.50'
                      avg_fill_price: '0.48375'
                      notional_usd: '20'
                      filled_notional_usd: '19.35'
                      status: filled
                      venue_status: null
                      venue_order_id: null
                      status_reason: null
                      post_only: false
                      replaces_order_id: null
                      replaced_by_order_id: null
                      legs:
                        - venue: hyperliquid
                          ticker: <venue ticker>
                          side: 'yes'
                          quantity: '25'
                          filled_quantity: '25'
                          limit_price: '0.50'
                          avg_fill_price: '0.48'
                          status: filled
                          venue_status: filled
                          venue_order_id: '91234567455'
                          cancel_requested_at: null
                          status_reason: null
                        - venue: polymarket
                          ticker: <venue ticker>
                          side: 'yes'
                          quantity: '15'
                          filled_quantity: '15'
                          limit_price: '0.50'
                          avg_fill_price: '0.49'
                          status: filled
                          venue_status: filled
                          venue_order_id: 0x<venue order id>
                          cancel_requested_at: null
                          status_reason: null
                        - venue: hyperliquid
                          ticker: <venue ticker>
                          side: 'yes'
                          quantity: '25'
                          filled_quantity: '25'
                          limit_price: '0.50'
                          avg_fill_price: '0.48'
                          status: filled
                          venue_status: filled
                          venue_order_id: '91234567455'
                          cancel_requested_at: null
                          status_reason: null
                        - venue: polymarket
                          ticker: <venue ticker>
                          side: 'yes'
                          quantity: '15'
                          filled_quantity: '15'
                          limit_price: '0.50'
                          avg_fill_price: '0.49'
                          status: filled
                          venue_status: filled
                          venue_order_id: 0x<venue order id>
                          cancel_requested_at: null
                          status_reason: null
                      created_at: '2026-10-11T18:00:02.114Z'
                      updated_at: '2026-10-11T18:00:02.587Z'
                      livemode: true
                      route: null
                    meta:
                      timestampMs: 1791741603020
                      requestId: 9d2f6b18-3e7a-4c05-b8d1-4f0a7e2c6b93
                Test order:
                  summary: >-
                    A test key: filled in full at the limit price, nothing sent
                    to a venue
                  value:
                    success: true
                    data:
                      id: 4c8e1f53-0a7d-4b29-96e4-d3b5a2f8c107
                      client_order_id: bot-2026-10-29-0001
                      market_id: >-
                        mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                      venue: hyperliquid
                      ticker: <venue ticker>
                      side: 'yes'
                      action: buy
                      type: limit
                      time_in_force: ioc
                      expires_at: null
                      quantity: '5'
                      filled_quantity: '5'
                      remaining_quantity: '0'
                      limit_price: '0.50'
                      avg_fill_price: '0.50'
                      notional_usd: '2.5'
                      filled_notional_usd: '2.5'
                      status: filled
                      venue_status: null
                      venue_order_id: null
                      status_reason: null
                      post_only: false
                      replaces_order_id: null
                      replaced_by_order_id: null
                      legs:
                        - venue: hyperliquid
                          ticker: <venue ticker>
                          side: 'yes'
                          quantity: '5'
                          filled_quantity: '5'
                          limit_price: '0.50'
                          avg_fill_price: '0.50'
                          status: filled
                          venue_status: null
                          venue_order_id: null
                          cancel_requested_at: null
                          status_reason: null
                        - venue: hyperliquid
                          ticker: <venue ticker>
                          side: 'yes'
                          quantity: '5'
                          filled_quantity: '5'
                          limit_price: '0.50'
                          avg_fill_price: '0.50'
                          status: filled
                          venue_status: null
                          venue_order_id: null
                          cancel_requested_at: null
                          status_reason: null
                      created_at: '2026-10-11T18:00:02.114Z'
                      updated_at: '2026-10-11T18:00:02.114Z'
                      livemode: false
                      route: null
                    meta:
                      timestampMs: 1791741602130
                      requestId: 9d2f6b18-3e7a-4c05-b8d1-4f0a7e2c6b93
                Unfilled ioc:
                  summary: 'An ioc order that matched nothing: canceled, 0 filled'
                  value:
                    success: true
                    data:
                      id: 5b7d0e2c-3a91-4f68-b4c2-9e1f7a03d856
                      client_order_id: bot-2026-10-29-0005
                      market_id: >-
                        mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                      venue: hyperliquid
                      ticker: <venue ticker>
                      side: 'yes'
                      action: buy
                      type: limit
                      time_in_force: ioc
                      expires_at: null
                      quantity: '5'
                      filled_quantity: '0'
                      remaining_quantity: '0'
                      limit_price: '0.50'
                      avg_fill_price: null
                      notional_usd: '2.5'
                      filled_notional_usd: '0'
                      status: canceled
                      venue_status: canceled
                      venue_order_id: null
                      status_reason: null
                      post_only: false
                      replaces_order_id: null
                      replaced_by_order_id: null
                      legs:
                        - venue: hyperliquid
                          ticker: <venue ticker>
                          side: 'yes'
                          quantity: '5'
                          filled_quantity: '0'
                          limit_price: '0.50'
                          avg_fill_price: null
                          status: canceled
                          venue_status: canceled
                          venue_order_id: null
                          cancel_requested_at: null
                          status_reason: null
                        - venue: hyperliquid
                          ticker: <venue ticker>
                          side: 'yes'
                          quantity: '5'
                          filled_quantity: '0'
                          limit_price: '0.50'
                          avg_fill_price: null
                          status: canceled
                          venue_status: canceled
                          venue_order_id: null
                          cancel_requested_at: null
                          status_reason: null
                      created_at: '2026-10-11T18:00:02.114Z'
                      updated_at: '2026-10-11T18:00:02.587Z'
                      livemode: true
                      route: null
                    meta:
                      timestampMs: 1791741602600
                      requestId: 9d2f6b18-3e7a-4c05-b8d1-4f0a7e2c6b93
                Rejected:
                  summary: The venue refused the order
                  value:
                    success: true
                    data:
                      id: 0e4a9c71-d25b-4f3e-8a60-1b7c5d2e9f48
                      client_order_id: bot-2026-10-29-0006
                      market_id: >-
                        mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                      venue: hyperliquid
                      ticker: <venue ticker>
                      side: 'yes'
                      action: buy
                      type: limit
                      time_in_force: gtc
                      expires_at: null
                      quantity: '5'
                      filled_quantity: '0'
                      remaining_quantity: '0'
                      limit_price: '0.50'
                      avg_fill_price: null
                      notional_usd: '2.5'
                      filled_notional_usd: '0'
                      status: rejected
                      venue_status: null
                      venue_order_id: null
                      status_reason:
                        code: VENUE_REJECTED
                        message: <venue message>
                      post_only: false
                      replaces_order_id: null
                      replaced_by_order_id: null
                      legs:
                        - venue: hyperliquid
                          ticker: <venue ticker>
                          side: 'yes'
                          quantity: '5'
                          filled_quantity: '0'
                          limit_price: '0.50'
                          avg_fill_price: null
                          status: rejected
                          venue_status: null
                          venue_order_id: null
                          cancel_requested_at: null
                          status_reason:
                            code: VENUE_REJECTED
                            message: <venue message>
                        - venue: hyperliquid
                          ticker: <venue ticker>
                          side: 'yes'
                          quantity: '5'
                          filled_quantity: '0'
                          limit_price: '0.50'
                          avg_fill_price: null
                          status: rejected
                          venue_status: null
                          venue_order_id: null
                          cancel_requested_at: null
                          status_reason:
                            code: VENUE_REJECTED
                            message: <venue message>
                      created_at: '2026-10-11T18:00:02.114Z'
                      updated_at: '2026-10-11T18:00:02.587Z'
                      livemode: true
                      route: null
                    meta:
                      timestampMs: 1791741602600
                      requestId: 9d2f6b18-3e7a-4c05-b8d1-4f0a7e2c6b93
                Unconfirmed:
                  summary: >-
                    The venue did not confirm the order; read it back, do not
                    resend
                  value:
                    success: true
                    data:
                      id: c83f1a6e-7b04-4d92-9e5a-2f6d0b8c4a17
                      client_order_id: bot-2026-10-29-0007
                      market_id: >-
                        mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                      venue: hyperliquid
                      ticker: <venue ticker>
                      side: 'yes'
                      action: buy
                      type: limit
                      time_in_force: gtc
                      expires_at: null
                      quantity: '5'
                      filled_quantity: '0'
                      remaining_quantity: '5'
                      limit_price: '0.50'
                      avg_fill_price: null
                      notional_usd: '2.5'
                      filled_notional_usd: '0'
                      status: unconfirmed
                      venue_status: null
                      venue_order_id: null
                      status_reason:
                        code: SUBMISSION_UNKNOWN
                        message: >-
                          The venue did not confirm this order. Read it back by
                          client_order_id; do not resend it.
                      post_only: false
                      replaces_order_id: null
                      replaced_by_order_id: null
                      legs:
                        - venue: hyperliquid
                          ticker: <venue ticker>
                          side: 'yes'
                          quantity: '5'
                          filled_quantity: '0'
                          limit_price: '0.50'
                          avg_fill_price: null
                          status: unconfirmed
                          venue_status: null
                          venue_order_id: null
                          cancel_requested_at: null
                          status_reason:
                            code: SUBMISSION_UNKNOWN
                            message: >-
                              The venue did not confirm this order. Read it back
                              by client_order_id; do not resend it.
                        - venue: hyperliquid
                          ticker: <venue ticker>
                          side: 'yes'
                          quantity: '5'
                          filled_quantity: '0'
                          limit_price: '0.50'
                          avg_fill_price: null
                          status: unconfirmed
                          venue_status: null
                          venue_order_id: null
                          cancel_requested_at: null
                          status_reason:
                            code: SUBMISSION_UNKNOWN
                            message: >-
                              The venue did not confirm this order. Read it back
                              by client_order_id; do not resend it.
                      created_at: '2026-10-11T18:00:02.114Z'
                      updated_at: '2026-10-11T18:00:02.587Z'
                      livemode: true
                      route: null
                    meta:
                      timestampMs: 1791741602600
                      requestId: 9d2f6b18-3e7a-4c05-b8d1-4f0a7e2c6b93
        '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: 9d2f6b18-3e7a-4c05-b8d1-4f0a7e2c6b93
        '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: 9d2f6b18-3e7a-4c05-b8d1-4f0a7e2c6b93
                Missing key:
                  summary: No Authorization header
                  value:
                    success: false
                    error:
                      code: UNAUTHORIZED
                      message: Missing API key
                    meta:
                      timestampMs: 1791741600000
                      requestId: 9d2f6b18-3e7a-4c05-b8d1-4f0a7e2c6b93
        '403':
          description: >-
            The key lacks the trade scope, or a routed buy found the account has
            not enabled trading in the Lean app (ACCOUNT_NOT_DELEGATED, with
            details.order_id); nothing was paid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                Missing scope:
                  summary: The key lacks the trade scope
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: This API key lacks the trade scope
                    meta:
                      timestampMs: 1791741600000
                      requestId: 9d2f6b18-3e7a-4c05-b8d1-4f0a7e2c6b93
        '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: 9d2f6b18-3e7a-4c05-b8d1-4f0a7e2c6b93
        '409':
          description: >-
            client_order_id was already used with a different request, or the
            Polymarket wallet changed while the order was being placed (for
            example its signer delegation was revoked). Nothing was placed in
            either case; for the wallet, check its signer delegation in Lean,
            then retry; the same client_order_id can be reused. A routed buy
            whose payment could not be authorized answers with details.reason
            (QUOTE_EXPIRED, ROUTE_MOVED, PAYMENT_MISMATCH,
            AGENT_APPROVAL_REQUIRED) and details.order_id; nothing was paid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                client_order_id_reused:
                  summary: client_order_id reused with a different request
                  value:
                    success: false
                    error:
                      code: CONFLICT
                      message: >-
                        client_order_id was already used with a different
                        request
                      details:
                        order_id: 8a1e5c07-4b3f-4d62-9f18-2c7e0a95d4b1
                    meta:
                      timestampMs: 1792771200000
                      requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
                polymarket_not_ready:
                  summary: Polymarket wallet not ready for API orders
                  value:
                    success: false
                    error:
                      code: CONFLICT
                      message: >-
                        The Polymarket wallet is no longer ready for API orders.
                        Check its signer delegation and try again.
                    meta:
                      timestampMs: 1792771200000
                      requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '422':
          description: >-
            Refused by a key limit or a check made before any venue was called;
            nothing was placed
          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
                Per-order limit:
                  summary: quantity × limit_price is above the key limit
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Order notional exceeds this key's per-order limit
                      details:
                        reason: ORDER_NOTIONAL_LIMIT
                        max_order_notional_micros: 5000000
                    meta:
                      timestampMs: 1791741600000
                      requestId: 9d2f6b18-3e7a-4c05-b8d1-4f0a7e2c6b93
                Insufficient funds:
                  summary: No venue that could place it has the cash
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: >-
                        The trading account cannot pay for this order on the
                        venues that could place it
                      details:
                        reason: INSUFFICIENT_FUNDS
                    meta:
                      timestampMs: 1791741600000
                      requestId: 9d2f6b18-3e7a-4c05-b8d1-4f0a7e2c6b93
                Below minimum:
                  summary: Too small for every venue that could place it
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: >-
                        Order notional is below the minimum of every venue that
                        could place it
                      details:
                        reason: BELOW_VENUE_MINIMUM
                        min_order_notional_micros: 1000000
                    meta:
                      timestampMs: 1791741600000
                      requestId: 9d2f6b18-3e7a-4c05-b8d1-4f0a7e2c6b93
        '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: 9d2f6b18-3e7a-4c05-b8d1-4f0a7e2c6b93
        '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: 9d2f6b18-3e7a-4c05-b8d1-4f0a7e2c6b93
        '503':
          description: >-
            Order placement is unavailable. UPSTREAM_ERROR without
            details.order_id means a venue failed or timed out; look the order
            up by client_order_id before you resend it. FEATURE_DISABLED with
            details.reason LIVE_TRADING_DISABLED means live keys cannot place
            orders right now and test keys still can; TRADING_PAUSED with
            details.scope api_key or trading_account means this key or its
            account is paused until resumed from the dashboard. UPSTREAM_ERROR
            with details.order_id means a routed buy could not have its payment
            signed; nothing was paid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                Venue failed:
                  summary: A venue failed before anything was placed
                  value:
                    success: false
                    error:
                      code: UPSTREAM_ERROR
                      message: Hyperliquid upstream request failed
                    meta:
                      timestampMs: 1791741600000
                      requestId: 9d2f6b18-3e7a-4c05-b8d1-4f0a7e2c6b93
                Live trading off:
                  summary: >-
                    A live key on an account where live trading is not enabled
                    yet; test keys still work
                  value:
                    success: false
                    error:
                      code: FEATURE_DISABLED
                      message: >-
                        Live order placement is switched off. Test keys can
                        still place simulated orders.
                      details:
                        reason: LIVE_TRADING_DISABLED
                    meta:
                      timestampMs: 1791741600000
                      requestId: 9d2f6b18-3e7a-4c05-b8d1-4f0a7e2c6b93
                Key paused:
                  summary: >-
                    This key paused itself with POST /v1/account/pause; resume
                    from the dashboard
                  value:
                    success: false
                    error:
                      code: FEATURE_DISABLED
                      message: >-
                        Order placement is paused for this key: Strategy halted.
                        Reads and cancels still work.
                      details:
                        reason: TRADING_PAUSED
                        scope: api_key
                    meta:
                      timestampMs: 1791741600000
                      requestId: 4b8e1f27-9c3d-4a62-8e05-d7f9a1c3b640
                Venue unavailable:
                  summary: Retry later with the same client_order_id
                  value:
                    success: false
                    error:
                      code: UPSTREAM_ERROR
                      message: Hyperliquid upstream request failed
                    meta:
                      timestampMs: 1791741600000
                      requestId: 9d2f6b18-3e7a-4c05-b8d1-4f0a7e2c6b93
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.