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

# Amend an order

> Changes the limit price, the size or both of a resting good til canceled order on one venue. Lean cancels the order and, once the cancel is confirmed with its final fill, places a new good til canceled order on the same venue with the same post_only for the rest of the new size: the answer is the new order, its replaces_order_id names the old one, and the old order’s replaced_by_order_id names the new one. Each keeps its own fills. A Kalshi, Polymarket US or Hyperliquid cancel is confirmed within the request. A live Polymarket cancel is confirmed some time after it is requested, so the first amend usually answers 409 REPLACEMENT_PENDING; send the same amend again once the old order reads canceled and the replacement is placed for what did not fill. The new order is placed as the calling key places one. Every check the new order faces, from the venue’s price and size rules and a post_only price that would trade to the key’s caps, the rolling day and the account’s cash or shares, runs before the cancel with what the old order holds counted as free, and a refusal leaves the order resting. Only a change between that check and the placement, such as another order spending the cash, can refuse the new order after the cancel, and the old order then stays canceled. Split, routed and immediate or cancel orders cannot be amended.



## OpenAPI

````yaml api-reference/openapi.json PATCH /orders/{id}
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/{id}:
    patch:
      tags:
        - Orders
      summary: Amend an order
      description: >-
        Changes the limit price, the size or both of a resting good til canceled
        order on one venue. Lean cancels the order and, once the cancel is
        confirmed with its final fill, places a new good til canceled order on
        the same venue with the same post_only for the rest of the new size: the
        answer is the new order, its replaces_order_id names the old one, and
        the old order’s replaced_by_order_id names the new one. Each keeps its
        own fills. A Kalshi, Polymarket US or Hyperliquid cancel is confirmed
        within the request. A live Polymarket cancel is confirmed some time
        after it is requested, so the first amend usually answers 409
        REPLACEMENT_PENDING; send the same amend again once the old order reads
        canceled and the replacement is placed for what did not fill. The new
        order is placed as the calling key places one. Every check the new order
        faces, from the venue’s price and size rules and a post_only price that
        would trade to the key’s caps, the rolling day and the account’s cash or
        shares, runs before the cancel with what the old order holds counted as
        free, and a refusal leaves the order resting. Only a change between that
        check and the placement, such as another order spending the cash, can
        refuse the new order after the cancel, and the old order then stays
        canceled. Split, routed and immediate or cancel orders cannot be
        amended.
      operationId: amendOrder
      parameters:
        - schema:
            type: string
            format: uuid
            example: 8a1e5c07-4b3f-4d62-9f18-2c7e0a95d4b1
          required: true
          name: id
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                limit_price:
                  type: string
                  description: >-
                    The new worst price per share, in dollars. Omit to keep the
                    current one.
                quantity:
                  type: string
                  pattern: ^\d+(?:\.\d+)?$
                  description: >-
                    The new total size in shares, counting what already filled.
                    Omit to keep the current one.
                client_order_id:
                  type: string
                  pattern: ^[A-Za-z0-9_-]{1,64}$
                  description: >-
                    The client_order_id of the new order that replaces this one.
                    Omit and Lean picks one.
              additionalProperties: false
            example:
              client_order_id: bot-0002
              limit_price: '0.52'
              quantity: '12'
      responses:
        '200':
          description: The order that replaced it
          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'
              example:
                success: true
                data:
                  id: 3f6b2d90-7c41-4e8a-b5d2-91a0c4e7f356
                  client_order_id: bot-0002
                  market_id: >-
                    mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                  title: >-
                    Denver Broncos at Los Angeles Chargers: DEN -3.5, Denver
                    Broncos -3.5
                  outcome: DEN
                  venue: hyperliquid
                  ticker: hl:9999
                  side: 'yes'
                  action: buy
                  type: limit
                  time_in_force: gtc
                  expires_at: null
                  quantity: '12'
                  filled_quantity: '0'
                  remaining_quantity: '12'
                  limit_price: '0.52'
                  avg_fill_price: null
                  notional_usd: '6.24'
                  filled_notional_usd: null
                  status: open
                  venue_status: null
                  venue_order_id: null
                  status_reason: null
                  legs: []
                  post_only: true
                  replaces_order_id: 8a1e5c07-4b3f-4d62-9f18-2c7e0a95d4b1
                  replaced_by_order_id: null
                  created_at: '2026-10-29T18:00:00.000Z'
                  updated_at: '2026-10-29T18:05:00.000Z'
                  livemode: false
                  route: null
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '400':
          description: API error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: VALIDATION_ERROR
                  message: Invalid request
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '401':
          description: Missing, invalid, expired or revoked API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: UNAUTHORIZED
                  message: Invalid, expired or revoked API key
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '403':
          description: The key lacks the scope this route needs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: FORBIDDEN
                  message: This API key lacks the scope this route needs
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '404':
          description: API error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: NOT_FOUND
                  message: Not found
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '409':
          description: >-
            The order cannot be amended. details.reason is ORDER_NOT_OPEN,
            ORDER_REPLACED with details.replaced_by_order_id,
            ORDER_NOT_AMENDABLE, or REPLACEMENT_PENDING with details.order_id
            when the order’s cancel was requested and nothing was placed in its
            place yet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: CONFLICT
                  message: The order cannot be amended
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '422':
          description: >-
            The new terms are refused: a key limit, the account’s cash or
            shares, or POST_ONLY_WOULD_CROSS for a post only order that would
            now trade
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: VALIDATION_ERROR
                  message: Refused by a limit; nothing was changed
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '429':
          description: API error
          headers:
            Retry-After:
              description: Seconds remaining in the upstream read cooldown, when available
              schema:
                type: integer
                minimum: 0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: RATE_LIMITED
                  message: Too many requests for this API key
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '500':
          description: API error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: INTERNAL_ERROR
                  message: An internal error occurred.
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '503':
          description: API error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: UPSTREAM_ERROR
                  message: A required service is temporarily unavailable.
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
components:
  schemas:
    ApiError:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - VALIDATION_ERROR
                - NOT_FOUND
                - UNAUTHORIZED
                - FORBIDDEN
                - CONFLICT
                - UPSTREAM_ERROR
                - RATE_LIMITED
                - INTERNAL_ERROR
                - FEATURE_DISABLED
                - CONDITIONAL_SELL_REJECTED
                - CONDITIONAL_SELL_ACTIVE
            message:
              type: string
              minLength: 1
            details:
              nullable: true
          required:
            - code
            - message
        meta:
          type: object
          properties:
            timestampMs:
              type: integer
              minimum: 0
            requestId:
              type: string
              minLength: 1
            traceId:
              type: string
              minLength: 1
            cachedAtMs:
              type: integer
              minimum: 0
            source:
              type: string
              enum:
                - cache
                - database
                - clickhouse
                - upstream
                - fallback
                - internal
          required:
            - timestampMs
            - requestId
      required:
        - success
        - error
        - meta
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        A Lean API key, sent as `Authorization: Bearer <key>`. A test key
        (`lean_sk_test_...`) simulates orders and fills with no money; a live
        key (`lean_sk_live_...`) trades for real within the key's limits. Every
        successful response says which mode answered in `data.livemode`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.