> ## Documentation Index
> Fetch the complete documentation index at: https://developer.uphold.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create order

> Create an order to buy or sell an asset.

> [!NOTE]
>
> This endpoint is currently available in **Sandbox** only. It is not yet available in **Production**.

> [!NOTE]
>
> In Sandbox the orders you create are not stored, so a replayed `clientOrderId` returns the same order `id` with a `201`, and reusing it with a different payload is not refused.

## Accounts

The `origin` and `destination` objects identify the accounts the amount leaves and the proceeds are credited to. Both must belong to the same user, and the origin must hold the amount when the order is created. On a `sell` the origin is the base asset account and the destination the quote asset account, and a `buy` is the other way round.

## Quantity and price

The order is sized by its `quantity`, in the base asset of the pair. The assets traded are the ones of the `origin` and `destination` accounts, and the `side` says which of them is the base asset. A `price` is required on a `limit` order and not allowed on a `market` order. The venue holds the bounds the quantity and the price must respect, so an order that breaks one is refused with a `409` whose `details` name the rule and its `limit`. A pair that cannot be traded is refused with `asset_pair_not_supported`. Read more about [type and side](../introduction#type-and-side).

## Client order id

The `clientOrderId` is an idempotency key. Replaying it returns the existing order with a `200`, and reusing it with a different payload is refused.

> [!WARNING]
>
> After a `5xx` or a timeout, replay the same `clientOrderId` before anything else. Never send a new one until the replay has answered, or the amount may be traded twice.

## Order outcome

A `201` means the order was created, not that it traded: check its `status` and `timeline`. A fill-or-kill order that could not fill in full comes back `closed` with a `canceled` event and its reason.

Read more about the [order lifecycle](../introduction#order-lifecycle).


## OpenAPI

````yaml _media/specs/trading-openapi.mintlify.json post /trading/orders
openapi: 3.1.0
info:
  version: 0.1.0
  title: Trading API
  description: >-
    The Trading API provides resources to estimate prices and place fill-or-kill
    orders.
  contact:
    name: Uphold API Team
    email: developer@uphold.com
    url: https://developer.uphold.com
servers:
  - url: https://api.enterprise.sandbox.uphold.com
    description: Sandbox
  - url: https://api.enterprise.uphold.com
    description: Production
security:
  - OAuth2: []
tags:
  - name: Prices
    description: Prices.
  - name: Orders
    description: Orders.
paths:
  /trading/orders:
    post:
      tags:
        - Orders
      summary: Create order
      description: Create an order to buy or sell an asset.
      operationId: trading.create-order
      requestBody:
        $ref: '#/components/requestBodies/create-trading-order-request-body'
      responses:
        '200':
          $ref: '#/components/responses/create-trading-order-replayed-response'
        '201':
          $ref: '#/components/responses/create-trading-order-response'
        '404':
          $ref: '#/components/responses/create-trading-order-not-found-response'
        '409':
          $ref: '#/components/responses/create-trading-order-conflict-response'
        '503':
          $ref: >-
            #/components/responses/create-trading-order-service-unavailable-response
      security:
        - OAuth2:
            - trading.orders:create
components:
  requestBodies:
    create-trading-order-request-body:
      content:
        application/json:
          schema:
            type: object
            properties:
              clientOrderId:
                description: >-
                  A unique key you choose for the order. Replaying it returns
                  the existing order.
                type: string
                minLength: 1
                maxLength: 64
              side:
                $ref: '#/components/schemas/trading-order-side'
              type:
                $ref: '#/components/schemas/trading-order-type'
              origin:
                $ref: '#/components/schemas/trading-account-node'
                description: The account the traded amount leaves.
              destination:
                $ref: '#/components/schemas/trading-account-node'
                description: The account the proceeds are credited to.
              quantity:
                allOf:
                  - $ref: '#/components/schemas/non-zero-decimal-amount'
                  - description: The quantity of the base asset to trade.
              price:
                allOf:
                  - $ref: '#/components/schemas/non-zero-decimal-amount'
                  - description: >-
                      The limit price, in the quote asset per one unit of the
                      base asset. Required on a limit order, and not allowed on
                      a market order.
              timeInForce:
                $ref: '#/components/schemas/trading-order-time-in-force'
            additionalProperties: false
            required:
              - clientOrderId
              - side
              - type
              - origin
              - destination
              - quantity
              - timeInForce
          examples:
            Sell At Market By Quantity:
              value:
                clientOrderId: 8d5f1c0e-1b2a-4c3d-9e8f-77a0b1c2d3e4
                side: sell
                type: market
                origin:
                  type: account
                  id: 651ffcd3-a706-4c91-82ce-5a5eb9c1da62
                destination:
                  type: account
                  id: 9a3d7e4b-2c1f-4e8d-b7a6-5f4e3d2c1b0a
                quantity: '0.5'
                timeInForce: fok
            Sell With A Limit:
              value:
                clientOrderId: 3a9e1f7c-2d4b-4e6a-8c1f-5b7d9e2a4c61
                side: sell
                type: limit
                origin:
                  type: account
                  id: 651ffcd3-a706-4c91-82ce-5a5eb9c1da62
                destination:
                  type: account
                  id: 9a3d7e4b-2c1f-4e8d-b7a6-5f4e3d2c1b0a
                quantity: '0.5'
                price: '61500.00'
                timeInForce: fok
            Buy At Market:
              value:
                clientOrderId: 5c1e8a3d-7f2b-4d9e-a6c0-3b8f1e5d9a24
                side: buy
                type: market
                origin:
                  type: account
                  id: 9a3d7e4b-2c1f-4e8d-b7a6-5f4e3d2c1b0a
                destination:
                  type: account
                  id: 651ffcd3-a706-4c91-82ce-5a5eb9c1da62
                quantity: '0.25'
                timeInForce: fok
  responses:
    create-trading-order-replayed-response:
      description: Order already existed.
      content:
        application/json:
          schema:
            type: object
            properties:
              order:
                $ref: '#/components/schemas/trading-order'
            required:
              - order
          examples:
            Order Replayed:
              value:
                order:
                  id: 0192f3a1-7c2e-7d4b-9a1f-3e5c8b2d4f60
                  clientOrderId: 8d5f1c0e-1b2a-4c3d-9e8f-77a0b1c2d3e4
                  side: sell
                  type: limit
                  origin:
                    type: account
                    id: 651ffcd3-a706-4c91-82ce-5a5eb9c1da62
                  destination:
                    type: account
                    id: 9a3d7e4b-2c1f-4e8d-b7a6-5f4e3d2c1b0a
                  quantity: '0.5'
                  price: '61500.00'
                  timeInForce: fok
                  status: closed
                  execution:
                    quantity: '0.5'
                    notional: '30959.57'
                    averagePrice: '61919.14'
                  timeline:
                    - event: created
                      createdAt: '2026-10-12T10:31:04.512Z'
                    - event: filled
                      createdAt: '2026-10-12T10:31:05.104Z'
                  createdAt: '2026-10-12T10:31:04.512Z'
                  updatedAt: '2026-10-12T10:31:05.104Z'
      headers:
        x-uphold-request-id:
          description: >-
            A unique identifier for the request that can be shared with Uphold
            for troubleshooting purposes.
          required: true
          schema:
            type: string
            format: uuid
          examples:
            Request ID:
              value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
    create-trading-order-response:
      description: Order created.
      content:
        application/json:
          schema:
            type: object
            properties:
              order:
                $ref: '#/components/schemas/trading-order'
            required:
              - order
          examples:
            Order Completed:
              value:
                order:
                  id: 0192f3a1-7c2e-7d4b-9a1f-3e5c8b2d4f60
                  clientOrderId: 8d5f1c0e-1b2a-4c3d-9e8f-77a0b1c2d3e4
                  side: sell
                  type: limit
                  origin:
                    type: account
                    id: 651ffcd3-a706-4c91-82ce-5a5eb9c1da62
                  destination:
                    type: account
                    id: 9a3d7e4b-2c1f-4e8d-b7a6-5f4e3d2c1b0a
                  quantity: '0.5'
                  price: '61500.00'
                  timeInForce: fok
                  status: closed
                  execution:
                    quantity: '0.5'
                    notional: '30959.57'
                    averagePrice: '61919.14'
                  timeline:
                    - event: created
                      createdAt: '2026-10-12T10:31:04.512Z'
                    - event: filled
                      createdAt: '2026-10-12T10:31:05.104Z'
                  createdAt: '2026-10-12T10:31:04.512Z'
                  updatedAt: '2026-10-12T10:31:05.104Z'
            Limit Not Met:
              value:
                order:
                  id: 0192f3a3-9c1d-7e4b-8a2f-3d6c9e1b7a58
                  clientOrderId: 7e2c9a4d-1f6b-4d8e-b3a5-9c1e7f2d4b06
                  side: sell
                  type: limit
                  origin:
                    type: account
                    id: 651ffcd3-a706-4c91-82ce-5a5eb9c1da62
                  destination:
                    type: account
                    id: 9a3d7e4b-2c1f-4e8d-b7a6-5f4e3d2c1b0a
                  quantity: '0.5'
                  price: '62500.00'
                  timeInForce: fok
                  status: closed
                  execution:
                    quantity: '0'
                    notional: '0'
                    averagePrice: null
                  timeline:
                    - event: created
                      createdAt: '2026-10-12T10:36:41.330Z'
                    - event: canceled
                      reason: limit-price-not-met
                      createdAt: '2026-10-12T10:36:41.902Z'
                  createdAt: '2026-10-12T10:36:41.330Z'
                  updatedAt: '2026-10-12T10:36:41.902Z'
            Order Processing:
              value:
                order:
                  id: 0192f3a6-2e9c-7b1d-8f4a-5c3e7a1b9d02
                  clientOrderId: a4d7c2e9-3b6f-4e1a-9c8d-2f5b7e0a1c63
                  side: sell
                  type: market
                  origin:
                    type: account
                    id: 651ffcd3-a706-4c91-82ce-5a5eb9c1da62
                  destination:
                    type: account
                    id: 9a3d7e4b-2c1f-4e8d-b7a6-5f4e3d2c1b0a
                  quantity: '1'
                  timeInForce: fok
                  status: pending
                  execution:
                    quantity: '0'
                    notional: '0'
                    averagePrice: null
                  timeline:
                    - event: created
                      createdAt: '2026-10-12T10:52:40.220Z'
                  createdAt: '2026-10-12T10:52:40.220Z'
                  updatedAt: '2026-10-12T10:52:40.220Z'
      headers:
        x-uphold-request-id:
          description: >-
            A unique identifier for the request that can be shared with Uphold
            for troubleshooting purposes.
          required: true
          schema:
            type: string
            format: uuid
          examples:
            Request ID:
              value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
    create-trading-order-not-found-response:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Origin Not Found:
              value:
                code: entity_not_found
                message: The origin cannot be found
                details:
                  entity: account
                  context: body
                  property: origin
            Destination Not Found:
              value:
                code: entity_not_found
                message: The destination cannot be found
                details:
                  entity: account
                  context: body
                  property: destination
      headers:
        x-uphold-request-id:
          description: >-
            A unique identifier for the request that can be shared with Uphold
            for troubleshooting purposes.
          required: true
          schema:
            type: string
            format: uuid
          examples:
            Request ID:
              value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
    create-trading-order-conflict-response:
      description: Business logic error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Quantity Below Minimum:
              value:
                code: transaction_amount_invalid
                message: The amount minimum limit was not met
                details:
                  context: body
                  property: quantity
                  rule: minimum-limit-not-met
                  limit:
                    minimumAmount: '0.0001'
            Quantity Above Maximum:
              value:
                code: transaction_amount_invalid
                message: The amount maximum limit was exceeded
                details:
                  context: body
                  property: quantity
                  rule: maximum-limit-exceeded
                  limit:
                    maximumAmount: '10'
            Quantity Increment Invalid:
              value:
                code: transaction_amount_invalid
                message: The amount is not a multiple of the allowed increment
                details:
                  context: body
                  property: quantity
                  rule: invalid-increment
                  limit:
                    increment: '0.00000001'
            Price Increment Invalid:
              value:
                code: transaction_amount_invalid
                message: The amount is not a multiple of the allowed increment
                details:
                  context: body
                  property: price
                  rule: invalid-increment
                  limit:
                    increment: '0.01'
            Insufficient Book Depth:
              value:
                code: transaction_amount_invalid
                message: The amount exceeds the available order book depth
                details:
                  context: body
                  property: quantity
                  rule: insufficient-book-depth
                  limit:
                    availableAmount: '7.84'
            Asset Pair Not Supported:
              value:
                code: asset_pair_not_supported
                message: The asset pair is not supported for trading
            Order Type Not Available:
              value:
                code: operation_not_allowed
                message: The order type is not available for this asset pair
                details:
                  reasons:
                    - order-type-not-available
            Price Out Of Bounds:
              value:
                code: operation_not_allowed
                message: The venue price deviates too much from the reference rate
                details:
                  reasons:
                    - price-out-of-bounds
            Client Order Id Already Used:
              value:
                code: duplicate
                message: The client order id was already used with a different order
                details:
                  context: body
                  property: clientOrderId
            Unspecified Error:
              value:
                code: operation_not_allowed
                message: Order not allowed due to an unspecified error
                details:
                  reasons:
                    - unspecified-error
      headers:
        x-uphold-request-id:
          description: >-
            A unique identifier for the request that can be shared with Uphold
            for troubleshooting purposes.
          required: true
          schema:
            type: string
            format: uuid
          examples:
            Request ID:
              value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
    create-trading-order-service-unavailable-response:
      description: The venue is unavailable, or the request timed out.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Service Unavailable:
              value:
                code: service_unavailable
                message: Service Unavailable
      headers:
        x-uphold-request-id:
          description: >-
            A unique identifier for the request that can be shared with Uphold
            for troubleshooting purposes.
          required: true
          schema:
            type: string
            format: uuid
          examples:
            Request ID:
              value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
  schemas:
    trading-order-side:
      description: Whether the base asset is bought or sold.
      type: string
      enum:
        - buy
        - sell
    trading-order-type:
      description: The type of the order.
      type: string
      enum:
        - market
        - limit
    trading-account-node:
      type: object
      properties:
        type:
          description: The type of the node.
          type: string
          enum:
            - account
        id:
          description: The account id.
          type: string
          format: uuid
      additionalProperties: false
      required:
        - type
        - id
    non-zero-decimal-amount:
      type: string
      pattern: ^(?!0+(\.0+)?$)\d+(\.\d+)?$
    trading-order-time-in-force:
      description: How long the order stays active. Only `fok` is supported for now.
      type: string
      enum:
        - fok
    trading-order:
      type: object
      properties:
        id:
          description: The id of the order.
          type: string
          format: uuid
        clientOrderId:
          description: The key chosen when the order was created.
          type: string
        side:
          $ref: '#/components/schemas/trading-order-side'
        type:
          $ref: '#/components/schemas/trading-order-type'
        origin:
          $ref: '#/components/schemas/trading-account-node'
        destination:
          $ref: '#/components/schemas/trading-account-node'
        quantity:
          description: The quantity the order was sized by.
          type: string
        price:
          description: The limit price. Absent on a market order.
          type: string
        timeInForce:
          $ref: '#/components/schemas/trading-order-time-in-force'
        status:
          $ref: '#/components/schemas/trading-order-status'
        execution:
          $ref: '#/components/schemas/trading-order-execution'
        timeline:
          description: The events of the order's lifecycle, oldest first.
          type: array
          items:
            $ref: '#/components/schemas/trading-order-timeline-item'
        createdAt:
          description: The time at which the order was created.
          type: string
          format: date-time
        updatedAt:
          description: The last time at which the order was updated.
          type: string
          format: date-time
      required:
        - id
        - clientOrderId
        - side
        - type
        - origin
        - destination
        - quantity
        - timeInForce
        - status
        - execution
        - timeline
        - createdAt
        - updatedAt
    error:
      description: The error information.
      allOf:
        - $ref: '#/components/schemas/feedback'
    trading-order-status:
      description: The status of the order. `closed` does not mean the order executed.
      type: string
      enum:
        - pending
        - open
        - closed
    trading-order-execution:
      description: What the order has executed so far.
      type: object
      properties:
        quantity:
          description: The base quantity executed.
          type: string
        notional:
          description: The gross amount executed, in the quote asset.
          type: string
        averagePrice:
          description: >-
            The average price, in the quote asset per one unit of the base
            asset. Null until something executes.
          type:
            - string
            - 'null'
      required:
        - quantity
        - notional
        - averagePrice
    trading-order-timeline-item:
      type: object
      properties:
        event:
          description: The event that occurred in the order's lifecycle.
          type: string
          enum:
            - created
            - filled
            - canceled
            - rejected
            - failed
        reason:
          $ref: '#/components/schemas/trading-order-reason'
        createdAt:
          description: The time at which the event occurred.
          type: string
          format: date-time
      required:
        - event
        - createdAt
    feedback:
      description: A feedback message with a code and human-readable description.
      type: object
      properties:
        code:
          description: A short string with a brief explanation about the code reported.
          type: string
        message:
          description: A human-readable message providing more details.
          type: string
        details:
          description: Additional information about the feedback reported.
          type: object
          additionalProperties: true
      required:
        - code
        - message
    trading-order-reason:
      description: Why the order did not execute.
      type: string
      enum:
        - insufficient-liquidity
        - limit-price-not-met
        - unspecified-error
        - venue-closed
        - venue-limit-exceeded
        - venue-rejected
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth 2.0
      flows:
        clientCredentials:
          tokenUrl: /core/oauth2/token
          scopes:
            trading.prices:create: Grants access to estimate prices.
            trading.orders:create: Grants access to create orders.
            trading.orders:read: Grants access to read orders and their trades.

````