How transactions work

The build → sign → submit pattern, previews, and error surfaces.

You never assemble instructions by hand. Every write goes through the same shape:

POST /transaction-builder/{action}   →   unsigned transactionBase64
        │
        ▼
decode → sign (client-side) → submit to the right RPC → confirm
        │
        ▼
read updated state from the basket snapshot (not the response)

The build → sign → submit mechanics — decode code, which RPC, who signs, blockhash expiry — live on Signing & submitting. This page covers the ideas behind them.

Quotes vs. plain builders

• Quote builders (open, close, reverse, collateral) return a rich object — projected leverage, entry/liq price, fees — with the transaction under transactionBase64.

• Plain builders (triggers, limits, most funds ops) return just { "transactionBase64": "…" }.

Preview before you commit

Two ways to compute without spending anything:

• Omit owner on open-position → you get the quote back with transactionBase64: null.

• Use the preview/* endpoints for fees, exit fees, TP/SL PnL, and margin changes — no transaction built at all.

State is in the basket, not the response

A trade response is a quote of what will happen, not confirmed state. After a transaction confirms, read the truth from GET /owner/{owner} or the WebSocket. There can be brief lag between submitting and the committed state appearing.

Two error surfaces

• HTTP errors (4xx/5xx) return { "error": "…" }.

• Compute errors on quote endpoints return 200 with { "err": "…" } in the body — a well-formed request the engine couldn't price.

Full matrix and recovery: Errors.