For AI agents: the documentation index is at /llms.txt, and this page is available as Markdown at /trading-api/place-orders.md.
Place orders
Every order is a POST /v1/gateway/orders with an asset, a size and a type. This page covers the calls you make most: place an order, list and read orders, and cancel one. Every call here uses your own token. Getting started walks through signing and executing a market buy.
Identify the asset
Send the asset's id from the catalog as asset_id. Older integrations name the asset with base_asset instead. Use asset_id for new code.
Place a market order
A market order executes now at the best available price, so it takes no price. Size a buy by what you spend, with qty_unit: "quote". Size a sell by what you sell, with qty_unit: "base".
The response carries the quote and the payloads to sign. Nothing moves until you sign them and execute.
const order = await post("/v1/gateway/orders", {
asset_id: assetId,
qty: "2",
qty_unit: "quote",
side: "buy",
type: "market",
});Limit orders
A limit order rests at your price until it fills or you cancel it, sized with qty_unit: "base". Limit orders aren't available for every asset yet; the create order reference has the current rules. On the exchange, the price must be a whole number of ticks; see Sizing.
List and read orders
GET /v1/gateway/orders lists your orders, newest first. Filter with status (comma-separated), and page with limit (up to 100) and the cursor from pagination.next_cursor. An order you created but never executed doesn't appear in the list. Read it by its id.
const orders = await get("/v1/gateway/orders?status=active");
const order = await get(`/v1/gateway/orders/${orderId}`);Cancel an order
Canceling a resting order is a wallet transaction too, so it works like placing one: the cancel call returns payloads, you sign them, and you execute the cancel.
const cancel = await post(
`/v1/gateway/orders/${orderId}/cancel`,
{},
);
const signatures = await Promise.all(
cancel.payloads.map((p) => stamp(p.payload)),
);
await post(`/v1/gateway/orders/${orderId}/cancel/execute`, {
signatures,
auth_type: "api_key",
});Sizing
In a pair such as SOL/USDC, the base asset is the one you buy or sell (SOL), and the quote asset is the one you price it in (USDC). qty_unit says which one qty counts. Every quantity is a positive decimal string.
qty_unit | Meaning | Allowed on |
|---|---|---|
quote | amount of the quote asset to spend, "10 USDC of SOL" | market buy |
base | amount of the base asset, "0.01 SOL" | market sell, limit orders |
An order that trades on the exchange (venue: "cefi") must also fit the exchange's increment sizes. The order's price bucket sets a tick size for price and a lot size for qty, and every order must be worth at least 1.00 in the quote asset. The exchange rejects an order that doesn't fit. A limit price must also sit inside the price bands.
Follow an order to a final state
- completefilled
- activea limit order, resting
- pendingstill settling
- failed
An order that isn't in a final state can still change, so read it again until it is.
If order_id comes back empty, no order was created, and quote.issues says why. Nothing moves until you execute, so you can retry a create that timed out.
When an order fails
| Status | Meaning |
|---|---|
201 with an empty order_id | The wallet can't fund the buy. quote.issues says why, and no order was created. |
422 with insufficient_balance | The wallet can't fund a sell or a perpetual order. |
422 with quote_stale | The quote expired or the price moved before execute landed. Place the order again. |
403 | The asset isn't available in your country. GET /assets/availability shows what's available. |
409 with already_submitted on execute | The transaction already landed. Read the order instead of executing again. |
Errors has the error body and the rest of the codes.
Perpetuals
A perpetual, or perp, is a contract that tracks an asset's price and never expires. Perpetuals aren't available for every asset; the ones that are appear in the catalog with type: "perp".
To open a position, send leverage, up to the asset's perp.max_leverage in the catalog. Margin is isolated. With qty_unit: "quote", qty is the margin you commit and the position's size is qty times leverage; with "base", qty is the position's size. To close a position, send reduce_only: true instead.
A trigger object turns the order into a take-profit or stop-loss that fires when the mark price crosses trigger.price. The create order reference has every rule.
Next: What you can trade
- Need help? Ask us on Discord, or email [email protected].
- See what changed in the changelog