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
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.
bearerAuthAuthorizationBearer <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.
TM-On-Behalf-Of?stringAct 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.
uuidapplication/json- 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):
priceis required and must be a positive decimal stringqty_unitmust bebasechainis optional (omit for CeFi; include a DeFi chain such ashypercore-spotto rest the order on-chain)
Market orders (type: market):
priceis not accepted- Buy orders require
qty_unit: quote - Sell orders accept
qty_unit: baseorqty_unit: quote chainis optional (omit for CeFi, include for DeFi)
Perp orders (a perp asset_id, or chain: hypercore-perp with base_asset):
leverageis required to open a position (buy = long, sell = short) and must be between 1 and 50; it must be omitted for non-perp assetsreduce_only: truemarks the order as a close of the opposite position;leverageis then ignoredqtyis the isolated margin to commit; position notional =qty×leverageqty_unitmay bequote(margin) orbase(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
typemust bemarket;priceandleveragemust not be sent;reduce_onlyis implied
asset_id?stringAsset 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.
uuidbase_asset?stringLegacy 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*stringQuantity as a positive decimal string
price?stringLimit 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*stringUnit 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,
basemust be used instead.
"base""quote"type*OrderTypeThe 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
priceandqty_unit: base.chainis optional: omit it for a CeFi limit order, or supply a DeFi chain (e.g.hypercore-spot) to rest the order on-chain. With atrigger, the type is how the fired order executes and must bemarket.
"market""limit"side*OrderSideThe side of the order.
- buy — Purchase the base asset using the quote asset.
- sell — Sell the base asset in exchange for the quote asset.
"buy""sell"chain?stringBlockchain network for DeFi orders. Omit for CeFi orders.
"solana""base""robinhood""hypercore-spot""hypercore-perp"leverage?integerIsolated-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.
uint161 <= value <= 50reduce_only?booleanMarks a perp order as a reduce-only close — it only reduces an existing position and never opens one. Only valid for perp assets.
venue?stringVenue 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_idnames. - cefi — The asset's CeFi listing, whichever listing
asset_idnames.400when the asset has no CeFi listing. - defi — The asset's DeFi listing, whichever listing
asset_idnames.400when the asset has no DeFi listing.
"smart""smart""cefi""defi"Order created successfully
application/json- 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?stringUnique order identifier. Empty when no order was created, e.g. a DeFi quote the account cannot fund.
status?OrderStatusThe 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).
"initialized""pending""cancel_pending""complete""canceled""active""failed"venue?stringVenue the order went to. For a user released to smart order routing it can differ from the venue of the listing the order named.
"defi""cefi"route_reason?stringWhy 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).
"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?stringDeprecatedWebAuthn payload (deprecated, use payloads instead)
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"}'{ "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"}