For AI agents: the documentation index is at /llms.txt, and this page is available as Markdown at /api/gateway/create-order.md.

Create new order

Organization tokenNo token

POST
/orders

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.

Authorization

bearerAuth
headerAuthorizationBearer <JWT>

An access token from POST /v1/auth/api-key/token. An organization token lasts one hour and has no refresh token; a personal token can be refreshed.

Header Parameters

TM-On-Behalf-Of?string

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.

Formatuuid

Request Body

application/json
  1. body

Request to create a new order.

Identifying the asset — provide exactly one of asset_id or base_asset (supplying both or neither is a 400). asset_id is the id from GET /assets and is preferred; base_asset is the legacy identifier.

Choosing the venue — venue defaults to smart. For an asset that trades on both venues, cefi or defi sends the order to that venue's listing whichever listing asset_id names, and smart lets the conductor choose; the response says which venue it used.

Limit orders (type: limit):

  • price is required and must be a positive decimal string
  • qty_unit must be base
  • chain is optional (omit for CeFi; include a DeFi chain such as hypercore-spot to rest the order on-chain)

Market orders (type: market):

  • price is not accepted
  • Buy orders require qty_unit: quote
  • Sell orders accept qty_unit: base or qty_unit: quote
  • chain is optional (omit for CeFi, include for DeFi)

Perp orders (a perp asset_id, or chain: hypercore-perp with base_asset):

  • leverage is required to open a position (buy = long, sell = short) and must be between 1 and 50; it must be omitted for non-perp assets
  • reduce_only: true marks the order as a close of the opposite position; leverage is then ignored
  • qty is the isolated margin to commit; position notional = qty × leverage
  • qty_unit may be quote (margin) or base (position size) on either side

Trigger orders (a trigger object, perp-only):

  • the order rests off-book and fires as a reduce-only market close when the mark price crosses trigger.price
  • a take-profit must rest on the profitable side of the position and a stop-loss on the losing side, or the quote is rejected
  • type must be market; price and leverage must not be sent; reduce_only is implied
asset_id?string

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.

Formatuuid
base_asset?string

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

Quantity as a positive decimal string

price?string

Limit price per unit of base asset as a decimal string. Required for limit orders; must not be sent for market orders.

trigger?

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.

qty_unit*string

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.
Value in"base""quote"
type*OrderType

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.
Value in"market""limit"
side*OrderSide

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.
Value in"buy""sell"
chain?string

Blockchain network for DeFi orders. Omit for CeFi orders.

Value in"solana""base""robinhood""hypercore-spot""hypercore-perp"
leverage?integer

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.

Formatuint16
Range1 <= value <= 50
reduce_only?boolean

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

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.
Default"smart"
Value in"smart""cefi""defi"

Response Body

Order created successfully

application/json
  1. response

Response from creating an order. For DeFi orders (and CeFi buy orders requiring a funding bridge), the response includes unsigned payloads that must be signed by the client and submitted via the execute endpoint. For CeFi sell orders and sufficiently funded CeFi buy orders, the order is submitted immediately and no payloads are returned. When a DeFi order cannot be funded, the response is quote-only: it carries the quote (with an Insufficient balance entry in quote.issues), an empty order_id, and no payloads, and no order is created.

order_id?string

Unique order identifier. Empty when no order was created, e.g. a DeFi quote the account cannot fund.

status?OrderStatus

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).
Value in"initialized""pending""cancel_pending""complete""canceled""active""failed"
venue?string

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.

Value in"defi""cefi"
route_reason?string

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

Value in"limit_order""best_price""cefi_no_market""cefi_unavailable""defi_unavailable""no_market""only_venue"
payloads?array<>

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

quote?

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.

web_authn_payload?stringDeprecated

WebAuthn payload (deprecated, use payloads instead)

Example Request
curl -X POST 'https://api.truemarkets.co/v1/gateway/orders' \  -H 'TM-On-Behalf-Of: 3f6d2c0e-8a41-4c2b-9f1e-2b7d5c0a9e11' \  -H 'Content-Type: application/json' \  -d '{  "qty": "100",  "qty_unit": "quote",  "type": "market",  "side": "buy"}'
Example Response
{  "order_id": "string",  "status": "complete",  "venue": "defi",  "route_reason": "limit_order",  "payloads": [    {      "digest": "string",      "payload": "string"    }  ],  "quote": {    "base_asset": "string",    "quote_asset": "string",    "qty": "string",    "qty_out": "string",    "fee": "string",    "fee_asset": "string",    "issues": [      "string"    ]  },  "web_authn_payload": "string"}