How trading works

Carbon is an RFQ (Request for Quote) venue. You don't match against an order book — you submit an intent, a solver (your counterparty) quotes and fills it, and the trade settles on-chain on Arbitrum.

Reads are synchronous, trades are asynchronous

This is the one behavior to design around.

	Reads (positions, balances, prices, markets)	Trades (open, close, cancel, margin)
Timing	Answer is in the response	Response is a tempId; the fill happens after
Pattern	Normal request/response	Submit, then poll

When you submit a trade, Carbon validates it, accepts it, and returns a tempId immediately — the fill (quote + on-chain settlement) completes over the next few seconds. You learn the outcome by polling a status endpoint.

Contract: treat a tempId as pending until a status endpoint reports a terminal state. Don't infer success from the 201, and don't blindly resubmit — poll first, and reconcile against GET /v1/positions/all if you time out.

Submit → poll, per operation

Every trade operation follows the same shape on its own request id:

Submit	Poll for the result
POST /v1/trade/create-position	GET /v1/positions/open-request/status
POST /v1/trade/close-position	GET /v1/positions/close-request/status
POST /v1/trade/cancel-quote	GET /v1/positions/cancel-request/status
POST /v1/trade/cancel-close-request	GET /v1/positions/cancel-close-request/status

Once an open confirms, the position appears in GET /v1/positions/all with its on-chain quoteId.

Minimal flow

// 1. Submit
const { data } = await post("/v1/trade/create-position", intent);
const tempId = data.tempId;

// 2. Poll until terminal (~1s apart, with a timeout)
for (let i = 0; i < 30; i++) {
  const { data } = await get("/v1/positions/open-request/status", { tempId });
  if (data.status === "SUCCESS") break; // filled → data.quoteId
  if (data.status === "FAILED") throw new Error(data.statusMessage);
  await sleep(1000);
}

Order types

• MARKET — fills at the solver's current price, bounded by your slippage.

• LIMIT — rests until a solver can fill at your limitPrice or better; cancel it with cancel-quote while pending.

Execution speed: instant vs on-chain

• Instant (default) — trades execute via off-chain signatures for low latency. Enabled by useInstantActions: true (the default), provided the subaccount has an instant-action token registered with the solver.

• On-chain — set useInstantActions: false to force a standard on-chain transaction. Slower, but needs no token. Some operations settle on-chain by nature. Only available in cross margin

Batching

Act on many positions in one call; each returns per-item results (grouped by a batchId) so one failure doesn't sink the rest:

batch-create-positions, batch-close-positions, batch-cancel-quotes, batch-cancel-close-requests, close-all-positions (all under /v1/trade/).