---
title: "Create new order"
url: https://docs.truemarkets.co/api/gateway/create-order
description: "Creates a new order. For DeFi orders, returns unsigned payloads for client signing."
---

Docs index: https://docs.truemarkets.co/llms.txt

# Create new order

Creates a new order. For DeFi orders, returns unsigned payloads for client signing.

A DeFi order can spend funds committed to CeFi trading; they are freed before the
payloads are returned. If they can't be, the request fails with `422 funds_allocated`
(held by open CeFi orders) or `409 release_settling` (retry shortly).

**Rate limit:** counts against the Orders limit, 10 a second and 120 a minute (user token, per user); 100 a second and 1,200 a minute (organization api key, per organization). See [Rate limits](https://docs.truemarkets.co/developer-resources/rate-limits).

## Request

```
POST https://api.truemarkets.co/v1/gateway/orders
```

### Authentication

Bearer token in `Authorization`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `TM-On-Behalf-Of` | header | string (uuid) | no | Act as one of your organization's users. The value is the `user_id` returned when the user was created; the request then reads and writes that user's account. Requires an organization token and a user your organization created: `400` for a personal token, a repeated header or a non-UUID, `403` for a user outside your organization. Not accepted on organization-scoped routes. |

### Body

`application/json`, required

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `asset_id` | string (uuid) | no | Asset id from `GET /assets`. Preferred way to identify the asset; chain and venue are derived from it. Provide exactly one of `asset_id` or `base_asset`. |
| `base_asset` | string | no | Legacy asset identifier: asset symbol for CeFi (e.g. `BTC`); token contract address on `chain` for DeFi. Provide exactly one of `asset_id` or `base_asset`. |
| `qty` | string | yes | Quantity as a positive decimal string |
| `price` | string | no | Limit price per unit of base asset as a decimal string. Required for limit orders; must not be sent for market orders. |
| `trigger` | object | no | Makes the order a TP/SL trigger: a reduce-only market close that rests off-book and fires when the mark price crosses `price`. Perp-only (`hypercore-perp`). A `take_profit` must rest on the profitable side of the position and a `stop_loss` on the losing side, or the order is rejected. The order `type` must be `market`, and `price`/`leverage` must not be specified; `reduce_only` is implied. |
| `trigger.type` | string, one of `take_profit`, `stop_loss` | yes | Trigger direction relative to the position. |
| `trigger.price` | string | yes | Trigger price per unit of base asset as a decimal string. |
| `qty_unit` | string, one of `base`, `quote` | yes | Unit of the quantity. * **base** — Quantity is denominated in the base asset. Required for limit orders. Supported for market sell orders. * **quote** — Quantity is denominated in the quote asset. Required for market buy orders. For DeFi sell orders, `base` must be used instead. |
| `type` | string, one of `market`, `limit` | yes | The type of order to place — how the order executes. * **market** — Execute immediately at the best available price. Buy orders require `qty_unit: quote`. Price must not be specified. * **limit** — Place an order at a specific price. Requires `price` and `qty_unit: base`. `chain` is optional: omit it for a CeFi limit order, or supply a DeFi chain (e.g. `hypercore-spot`) to rest the order on-chain. With a `trigger`, the type is how the fired order executes and must be `market`. |
| `side` | string, one of `buy`, `sell` | yes | The side of the order. * **buy** — Purchase the base asset using the quote asset. * **sell** — Sell the base asset in exchange for the quote asset. |
| `chain` | string | no | Blockchain network for DeFi orders. Omit for CeFi orders. |
| `leverage` | integer (uint16) | no | Isolated-margin leverage for a perp order. Required when the resolved asset is a perp (a perp `asset_id`, or `chain: hypercore-perp`) and the order opens a position (not reduce-only); must not be sent for non-perp assets. |
| `reduce_only` | boolean | no | Marks a perp order as a reduce-only close — it only reduces an existing position and never opens one. Only valid for perp assets. |
| `venue` | string, one of `smart`, `cefi`, `defi` | no | Venue the order should trade on. * **smart** — The conductor chooses. For an asset that trades on both venues (a CeFi listing that settles to DeFi and the DeFi listing it settles on), a market order goes to the better price after fees and a limit order to CeFi; when only one venue is open to the user, the order goes there. Otherwise the order goes to the listing `asset_id` names. * **cefi** — The asset's CeFi listing, whichever listing `asset_id` names. `400` when the asset has no CeFi listing. * **defi** — The asset's DeFi listing, whichever listing `asset_id` names. `400` when the asset has no DeFi listing. |

## Responses

Every error status returns the same body, described in [Errors](https://docs.truemarkets.co/developer-resources/errors.md).

### 201

Order created successfully

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `order_id` | string | no | Unique order identifier. Empty when no order was created, e.g. a DeFi quote the account cannot fund. |
| `status` | string, one of `initialized`, `pending`, `cancel_pending`, `complete`, `canceled`, `active`, `failed` | no | The current status of the order. * **initialized** — Order has been created but not yet submitted. For DeFi orders, the client must sign the returned payloads and call the execute endpoint. For CeFi buy orders with insufficient balance, a funding bridge is prepared first. * **pending** — Order has been submitted but is not yet confirmed by the CeFi exchange or on-chain. * **active** — Order was accepted by the CeFi exchange and is open for trading. Applies to limit orders that are working in the order book. * **cancel_pending** — A cancellation request has been sent to the CeFi exchange and is awaiting confirmation. * **complete** — Order has been fully executed. For CeFi orders this means the CeFi exchange reported a fill; for DeFi orders the on-chain swap was confirmed. * **canceled** — Order was successfully canceled via a cancel request or by exchange/market conditions. * **failed** — Order was rejected by the CeFi exchange or DeFi execution failed (e.g. on-chain transaction reverted, balance check failed). |
| `venue` | string | no | Venue the order went to. For a user released to smart order routing it can differ from the venue of the listing the order named. |
| `route_reason` | string, one of `limit_order`, `best_price`, `cefi_no_market`, `cefi_unavailable`, `defi_unavailable`, `no_market`, `only_venue` | no | Why the smart order router chose `venue`; absent when the order was not routed. `limit_order` (limit orders rest on CeFi), `best_price` (the better price after fees), `cefi_no_market` / `cefi_unavailable` (CeFi could not price the order, so DeFi), `defi_unavailable` (DeFi could not price it, so CeFi), `no_market` (neither venue could, so the venue the order named), `only_venue` (the only venue of the pair open to the user). |
| `payloads` | array of object | no | Unsigned transaction payloads that the client must sign and return via the execute endpoint. Present for DeFi orders and CeFi buy orders that require a funding bridge. Empty or absent when the order is submitted immediately (e.g. CeFi sell orders). |
| `payloads[].digest` | string | yes | Lowercase hex SHA-256 of the `payload` bytes. A signing API that takes a pre-hashed input signs the hex-decoded digest; a library that hashes its input takes `payload` instead. Passing the hex digest to a library that hashes signs the wrong bytes. |
| `payloads[].payload` | string | yes | The exact text to sign: a Turnkey activity as JSON, including its trailing newline. Sign its UTF-8 bytes as-is with ECDSA P-256 and SHA-256; never decode, reformat or re-serialize it. |
| `quote` | object | no | DeFi orders only. For CeFi price previews, use `POST /quotes`. When `issues` reports an insufficient-balance problem, the response is quote-only: `order_id` is empty and there are no `payloads`. |
| `quote.base_asset` | string | no | Base asset identifier (e.g. `SOL`, `ETH`) |
| `quote.quote_asset` | string | no | Quote asset identifier (e.g. `USDC`) |
| `quote.qty` | string | no | Input quantity as a decimal string — the amount being swapped from |
| `quote.qty_out` | string | no | Expected output quantity as a decimal string — the amount the user will receive after fees |
| `quote.fee` | string | no | The whole fee the order is quoted to pay, every venue fee included, as a decimal string |
| `quote.fee_asset` | string | no | Asset in which the fee is denominated (e.g. `USDC`) |
| `quote.issues` | array of string | no | Warnings about the quote (e.g. high price impact, low liquidity, `Insufficient balance`). Empty when there are no issues. An `Insufficient balance` entry means the account cannot fund the trade, in which case the response is quote-only (empty `order_id`, no `payloads`). |
| `web_authn_payload` | string | no | WebAuthn payload (deprecated, use payloads instead) |

### 400

Bad request

### 401

Unauthorized

### 403

Forbidden. On order creation this also covers an asset that is not available to trade from the country the request came from.

### 404

Not found

### 409

Conflict

### 422

Request is well-formed but cannot be processed (e.g. leverage missing or out of range for a perp order)

### 500

Internal server error

### 503

Service unavailable
