Order management
Submit, track and cancel signed orders reliably. Understand concurrency, control request volume and recover when an outcome is uncertain.
Use this guide with the Orders - New API reference. Account setup, history, portfolio reads and streams continue to use the Trading API.
For balance checks, BUY commitments and SELL share reservations, see Collateral locking.
How orders are processed
Use POST /order/v1/orders/signed to submit a signed order. Each order must pass authentication and trading checks before it can execute or rest on the book.
- Submit — Send the signed order
- Validate — Check access and order terms
- Process — Fill, rest or reject
- Respond — Report the available state
Keep the original signed request and track the order by its returned ID or signed hash. Use the response, account events and order reads together: a response can report an order’s state or say that the outcome is still unknown.
This guide covers /order/v1. If you also use /trade/v1, interpret its placement acknowledgement separately: 202 PENDING confirms receipt for processing, not acceptance onto the book.
Concurrency and request ordering
Submit independent orders concurrently, but match each response to its original request. Requests can execute or receive responses in a different order from how they were sent.
Wait for confirmation whenever one action depends on another. For example, confirm cancellation before placing a replacement if both orders must not be active at the same time.
For batches, use each result’s index to identify the input order. For later events and reads, use the order ID or signed hash. Response order does not establish execution order.
Latency and throughput
Reuse connections, limit concurrent requests and measure response times as you increase traffic. Track unresolved requests as well as successful responses.
Prepare orders locally
Reuse your HTTP client and its connection pool. Complete wallet setup and approvals before trading. For GTC, FAK and FOK, sign close to submission; for GTD, choose a deadline that leaves enough time for submission. See time in force and expiry.
Use streams for ongoing updates
Use the market and account streams to follow changes. Reserve reads for the initial state, reconciliation and uncertain outcomes. Keep processing incoming messages while making HTTP requests.
Control bursts and request volume
Limit concurrent requests so that stale quotes do not accumulate in your client. Batch independent orders when it reduces HTTP overhead, and handle each order’s result separately.
Leave capacity for cancellations and recovery reads. Your account’s tokens and sessions share the rate allowances; adding connections does not increase them.
Checks before an order can trade
Prepare valid order terms before sending a request. A valid signature alone does not guarantee that an order can trade.
- Market and outcome: use the current token ID for an active Agara market.
- Price and quantity: follow the market’s tick size and supported precision, and keep the API fields consistent with the signed amounts.
- Funds and shares: account for existing orders and fills when checking what is available for another order.
- Time: sign the current Unix time in seconds. For GTD, also set a separate expiry deadline.
Authenticate the request and sign the order
Send a valid bearer token with the scope required for the action:
| Action | Required scope |
|---|---|
| Signed placement, including batches | orders:place_signed |
| Cancellation, including cancel-all | orders:cancel |
| Order reads | orders:read |
API traders use an agt_… token. Placement also requires the EIP-712 signature for the authenticated wallet. Complete account setup and approvals before trading, and use the correct chain, signing domain and deposit-wallet address.
For a 401, check the credential. For INSUFFICIENT_SCOPE, use a token authorised for the action. For AUTH_UNAVAILABLE, retry later while retaining any unresolved signed requests.
Inspect a rejection’s reason before changing the request. For an uncertain submission, follow timeouts and uncertain outcomes before signing a replacement.
See amounts and rounding.
Batch orders
A batch sends multiple signed orders in one HTTP request. POST /order/v1/orders/signed/batch accepts 1–32 signed orders for the authenticated wallet. Orders may target different markets.
| Batch behaviour | How to handle it |
|---|---|
| Results follow input order | Use each result’s zero-based index to find the corresponding order. Result order does not establish execution order. |
| Items succeed or fail individually | Inspect every item. One rejection does not undo other accepted orders. |
| HTTP 202 contains individual results | Read each item’s accepted, delayed, rejected or unknown outcome; HTTP 202 does not mean that every order succeeded. |
| An item can be delayed before matching | Track its original ID or hash through reads and account events. A delayed item is waiting, not a confirmed fill or resting order. |
| Malformed JSON rejects the request | Send a valid { "orders": [...] } document. Invalid fields within an otherwise valid item fail that item individually. |
| An item’s result can be unknown | Retain its original signed request and resolve that order before replacing it. |
Keep dependent orders out of the same batch when their execution order matters. Each order retains its own timestamp and expiry requirements; the batch does not have a separate execution deadline.
See timeouts and uncertain outcomes for handling an unknown item without creating a second order.
If you use a generated client or response validator, update it from the current Order Service schema before submitting batches to markets with taker delays. Handle all four outcomes. An unrecognised outcome is not proof of rejection: retain the signed request and read the original order before deciding whether to retry.
Taker delays
Keep tracking the original order when you receive TAKE_ORDER_DELAY. The placement request has completed with HTTP 202, but the order is waiting before matching. In a batch, the corresponding item has outcome: "delayed". Neither response confirms a fill or a resting order.
For which orders wait, delay settings and order-type behaviour, see Taker delay. The delay is a minimum wait, not a deadline for receiving a result.
- Subscribe before submitting. Listen to account events and retain the exact signed body, order hash and returned ID.
- Track the existing order. Follow events and look up the original ID or hash. Use
status: "TAKE_ORDER_DELAY"to recognise the wait; do not infer completion frompending_operationalone. - Wait for an outcome. Do not resubmit merely because the expected delay has elapsed. Processing or delivery can take longer. The original HTTP request will not return a second response.
- Retry with the same identity when needed. Keep the signed body and associated API fields unchanged. A retry while the order is still waiting does not create another waiting copy or shorten the wait. Signing new fields can create a separate order.
- Reconcile before replacing. Account for fills and any resting remainder before signing a replacement. A rejection event remains valid even if a later lookup returns HTTP 404 with
code: "order_not_found".
| Situation | What to do |
|---|---|
| You want to cancel or edit a waiting order | Cancellation returns HTTP 409 with code: "order_not_cancellable"; edits are unsupported. Follow the outcome, then cancel any unfilled remainder that becomes open. |
| You send cancel-all while some orders are waiting | Keep tracking those orders. Cancel-all does not remove them; check for orders that become open afterward. |
| Other orders need the same funds or shares | Budget for all pending commitments in your client. The wait reserves neither funds nor shares, so several delayed orders are not all guaranteed to succeed. |
| GTD expiry approaches | Do not assume the delay extends expiry. Track the final outcome before submitting another order. |
| A service interruption occurs | Reconcile events and reads for the original order. A waiting order can be lost before matching, and retrying it may start a new delay. |
After a stream disconnect or an uncertain result, follow stream recovery and timeouts and uncertain outcomes. Preserve the original identity throughout recovery.
Cancellation strategies
| Action | When to use it | What it covers |
|---|---|---|
| Cancel by order ID | You have the ID returned for the original order. | The unfilled remainder of that order. Completed fills remain valid. |
| Cancel by signed hash | You retained the signed hash but missed the placement reply. | The corresponding signed order, when it can be identified. This does not cancel a future placement. |
| Cancel all | You want to remove the wallet’s resting orders across markets. | Orders already on the book when cancellation is processed. It does not include placements still being prepared or arriving afterward. |
Use DELETE /order/v1/orders/{order_id} or DELETE /order/v1/orders/by-hash/{hash}. If cancellation by hash returns NOT_FOUND, look up the order by hash and use the returned order ID when available.
Cancellation boundary
A successful cancel-all removes every order for the wallet that is still resting when the cancellation is processed. If an order was confirmed open before you sent a new cancel-all request, its unfilled remainder is guaranteed to be cancelled if it is still resting at that point. Fills and expiry can happen before cancellation; completed fills remain valid.
Confirmation here means an accepted resting order, such as an OPEN response or an order_accepted event. A 202 PENDING receipt, a TAKE_ORDER_DELAY acknowledgement or an UNKNOWN outcome does not establish that the order is on the book. Cancel-all itself is confirmed by 200 COMPLETED; CANCEL_UNKNOWN means its outcome still needs to be resolved.
Placement validation and cancellation can overlap. In a timing race, an order still being validated can reach the book after cancel-all has completed and remain active or execute. This can happen even when its placement request was sent before the cancellation request.
Stop new submissions and resolve pending placements before relying on cancel-all to leave no open orders. If any placements remain unresolved when you cancel, check their outcomes afterward and cancel any orders that subsequently become open.
Retry a cancellation without creating a new action
For a single order, retry cancellation using the same ID or hash. For cancel-all, send POST /order/v1/orders/cancel-all with a fresh, nonzero UUID for a new cancellation request:
{
"request_id": "<fresh nonzero UUID>"
}Reuse that request_id when retrying the same cancel-all. Its repeated result does not confirm cancellation of orders placed afterward. Generate a new ID for a new cancel-all request.
A cancellation can race with a fill or expiry. After ORDER_NOT_OPEN or NOT_FOUND, read the final order state. Disconnecting your client is not a cancellation request.
Cancel and replace
To change an order’s price or quantity, cancel the original and submit a new signed order. These endpoints do not provide an amend operation.
- Pause new submissions for the quote you are replacing.
- Resolve the original placement. Keep its signed body, hash and any returned order ID.
- Cancel its unfilled remainder and confirm the result through the response, events and order reads.
- Account for any fills before calculating the replacement quantity.
- Sign and submit a new order only when you intend new exposure.
If simultaneous exposure is unacceptable, wait until the original is confirmed closed. A timeout or an uncertain cancellation is not confirmation.
Example
You want a total of 10 shares. The original order fills 4 before you cancel it. If the target is still 10, the replacement is for the remaining 6 shares.
Partial fills and cancellation events
Process both fill and cancellation notifications. A cancellation removes only the unfilled remainder; it does not reverse trades that already happened.
A partial FAK can return PARTIALLY_FILLED with zero remaining quantity. When a read includes order, check order.is_terminal to distinguish a partly filled order that is finished from one still working. A compact response without order does not provide that flag; continue tracking events and reading the order until its outcome is clear.
Deduplicate fills by fill_id. Multiple fills can belong to the same order, so deduplicating by order ID would discard valid executions.
See tracking orders and fills.
Time in force and expiry
| Time in force | What happens | Client consideration |
|---|---|---|
| GTC — Good till cancelled | Available quantity can fill immediately; the remainder can stay open until filled or cancelled. | Continue tracking fills and the remaining quantity. |
| GTD — Good till date | Any unfilled quantity expires at the specified time. | Expiry closes the remainder; it does not reverse earlier fills. |
| FAK — Fill and kill | Available quantity fills immediately and the remainder is cancelled. An unfillable order can be rejected. | A partially filled FAK has no resting remainder. |
| FOK — Fill or kill | The whole quantity fills immediately or the order is rejected. | Do not expect a resting remainder or a partial execution. |
These APIs use LIMIT orders. For market-style execution, use FAK with a price bound that reflects the worst price you are willing to accept.
Keep submission timestamps and expiry distinct
| Order | Time requirement | Retry behaviour |
|---|---|---|
| GTC / GTD / FAK / FOK | Sign the current Unix time in seconds as timestamp. The accepted window is from 65 minutes before to five minutes after the server’s current time, inclusive. | The window applies to every placement attempt, including retries and individual batch items. An old retry can be rejected even when the original order was accepted. |
| GTD expiry | Also set expiration_unix_seconds to the expiry deadline, independently of timestamp. When the API checks the request, expiry must be at least 30 seconds away. It can be more than an hour away. | Both the signing-time window and the expiry minimum apply to retries. Read or cancel the original if either check would fail. |
The submission window does not expire a resting order or prevent reading or cancelling it. GTD expiry is separate from the signed creation time and need not equal it. Use seconds, not milliseconds, and keep your signing clock accurate; do not send a zero timestamp.
Example: the API checks the request at 12:00:00 UTC
For all four time-in-force values, the signed timestamp can be from 10:55:00 to 12:05:00, inclusive. A GTD order signed at 12:00:00 can separately set its expiry to 14:00:00. The earliest permitted expiry at this check is 12:00:30; leave enough time for the request to reach the API.
Post-only orders
Set post_only: true on GTC or GTD orders to prevent immediate execution. An order that would cross is rejected; its price is not automatically adjusted.
Refresh your orderbook before choosing another quote after a rejection. The book can move between signing and processing, so a price that appeared passive when signed can still be rejected.
Example
If the best ask is 0.60, a post-only buy at 0.60 would cross and is rejected. Agara does not move that quote to a different price for you.
Responses, events and reads
HTTP responses, account events and REST reads reach your client through different paths. They can arrive in a different order from the activity they describe. An order_accepted or fill event can arrive before the placement’s HTTP reply, while order history and portfolio reads may reflect that activity later.
Correlate each update with its order ID or signed hash, and record each fill once using fill_id. Retain confirmed fills when a later-arriving response or read has not yet caught up. Arrival time alone does not make that response newer, and an absent fill in a read does not undo a fill event.
Reconcile subsequent reads with the events you have already received. A REST balance may already include a streamed fill, so do not add that fill to the balance again. A delayed reply or read is not a reason to place the same trade as a new order.
Read the response body as well as the HTTP status. The meaning depends on the operation.
| Response | Meaning | What to do |
|---|---|---|
| Placement: HTTP 200 | An order state is available. The order may be open, partly filled or finished. A repeated request can return the existing order’s state. | Record the returned order ID and state, then follow subsequent events. |
| Placement: HTTP 202, TAKE_ORDER_DELAY | The order is waiting before matching. No fill or resting order is confirmed. | Track the original ID or hash through reads and account events. Do not sign a replacement just because the order is delayed. |
| Placement: HTTP 202, UNKNOWN | The placement outcome is uncertain. The order may have been accepted. | Keep the original signed request and resolve it before placing a replacement. |
| Single-order cancellation: HTTP 200, CANCELLED | Cancellation is confirmed, or the order was already cancelled. | Preserve any fills that happened before cancellation. |
| Single-order cancellation: HTTP 202, CANCEL_UNKNOWN | The cancellation outcome is uncertain. | Retry cancellation of the same order. |
| Cancel-all: HTTP 200, COMPLETED | The cancellation request completed for orders resting when it was processed. | Reconcile remaining orders and pending placements against the cancellation boundary. |
| Cancel-all: HTTP 202, CANCEL_UNKNOWN | The cancel-all outcome is uncertain. | Retry with the same request_id to resolve that cancellation. |
| Batch: HTTP 202 | The body contains individual order results. | Handle each item separately. |
| Order read: HTTP 200 | An order view is available, including pending or uncertain states. | Inspect the state and whether the order is finished. |
Check status and pending_operation to see whether submission or cancellation is unresolved. TAKE_ORDER_DELAY means the order is still waiting. Treat as_of as the response time; recent fills may not yet appear in that read.
For partial executions, also check order.is_terminal in the order read. See partial fills and cancellation events.
Tracking orders and fills
Subscribe to account events before placing orders and wait for subscription confirmation. The account stream reports activity from both supported submission routes.
| Notification | Client action |
|---|---|
order_accepted | Track the accepted order. A fully filled order can produce fills without a later acceptance notification. |
fill | Record the executed price and quantity once per fill_id, including when the remainder is later cancelled. |
order_cancelled | Close the remaining quantity. Check the reason, including expiry, and retain previous fills. |
order_rejected | Record the rejected attempt and its reason. Keep your own record of the rejection. |
Process account-event sequence numbers without requiring consecutive values; a numerical gap alone does not show that messages were missed. Process sequence: 0 rejection notices too, and associate them with the relevant order.
Stream recovery
This section applies to the account WebSocket, /trade/v1/account-stream, and its account_events channel.
The account stream is live-only, with no replay. Reconnecting restores future delivery; it does not recover messages missed during the gap. Orders can fill, expire or be cancelled while your client is disconnected. A disconnect does not cancel resting orders.
When to reconnect
| What your client observes | Action |
|---|---|
| The socket closes or the transport fails | Open a new connection. Disconnects can happen periodically without an error frame or advance notice. |
A recognised error requests action: "reconnect" | Follow its recovery instruction, then open a new socket. For identity_token_expired, refresh the token first. |
| Authentication, scope or wallet setup is rejected | Correct the reported problem before retrying. Repeatedly reconnecting with the same invalid credentials cannot restore the subscription. |
sequence_reset on the only trusted connection | Pause new placements and reconcile through REST. The subscription remains active: buffer subsequent events on that socket instead of closing it solely because of the reset. |
Use capped exponential backoff with jitter for connection attempts; respect Retry-After on HTTP 429. Track heartbeat, pong, errors and closure separately for each socket. An account with no trading activity can legitimately have no data updates.
Only one account subscription attempt is allowed per connection. Open a new socket to retry a failed subscription, rotate credentials or subscribe after unsubscribing. See authentication and connection failures.
Reconnect and reconcile
Pause new placements whenever account delivery coverage is uncertain. Keep the original signed requests and resolve them through reads; neither a lost socket nor an absent notification proves that an order failed.
- Reconnect and authenticate. After backoff, open a new socket and send the subscription below with a valid token carrying
account:stream. - Wait for
subscribed, then buffer events. Start buffering before the first recovery read. Reading REST first leaves an interval in which an event can occur before the subscription starts. - Read the account state. Fully page
POST /trade/v1/orders/listand refreshPOST /trade/v1/portfolio/open-orders/list. Read positions, summary, recent trades and activities through the portfolio API. Follow everynext_cursor; resolve pending placements and cancellations by their original order ID or signed hash. - Check incomplete or lagging reads. If positions report
AGARAinunavailable_exchanges, retry the whole positions read. If any trades page reports it, discard that accumulated pagination walk and restart without a cursor. Retry503 ORDER_STATE_RECOVERING; it does not establish an order's outcome. - Reconcile records and inventory separately. Record each fill once by
fill_id. A fill event can arrive before history: pollGET /trade/v1/orders/{order_id}/tradesuntil it appears, then verify that the order reflects its fills and any later cancellation. Refresh positions and summary for buffered fill, token or collateral changes. - Resume after reconciliation. Confirm that unresolved orders and observed account effects are reflected in the reads. Two identical reads alone do not prove that an effect has arrived. If delivery is interrupted again or an effect cannot be verified, keep placements paused and repeat recovery.
{
"op": "subscribe",
"channels": [{ "name": "account_events", "token": "agt_…" }]
}REST responses have no matching account-stream sequence watermark. A returned balance or position may already include a buffered event. Do not add buffered fills, mint/merge quantities, redemptions or collateral changes to that snapshot blindly: duplicate suppression between sockets cannot tell you what REST already includes.
Use the account-stream reconciliation checks for observable order, batch and inventory outcomes. Retain known fills while reads catch up, and use timeouts and uncertain outcomes before replacing an unresolved order.
Deduplicating account events
Scope every key by environment, account and account_events channel. Apply these rules to data updates from overlapping connections:
| Event | Duplicate key | Handling |
|---|---|---|
fill | fill_id | Different fills of one order have different IDs. An order ID identifies the order, not an execution. |
order_accepted, order_cancelled | Positive sequence + kind | Process distinct transitions in order, even when their order ID or hash repeats. |
order_rejected | order_id + kind | These notices use sequence: 0. Handle them outside positive-sequence ordering; never discard them against the latest positive sequence. |
tokens_minted, tokens_merged, tokens_redeemed, payouts_redeemed | Positive sequence + kind | Apply every distinct event, including all outcome legs in one message. A batch hash and index can repeat for an operation, its compensation and later recovery. |
collateral_deposited, collateral_withdrawn | Positive sequence + kind | Keep balance updates in order. Equal amounts or balances do not identify a duplicate. |
Positive sequences can have gaps because other accounts' activity advances the counter. Do not require sequence == last_sequence + 1. A backwards positive sequence within one uninterrupted connection requires recovery; an older copy arriving on a slower redundant connection is a different case.
Handle subscribed, unsubscribed, heartbeat, pong, subscription lists, errors, sequence_reset and closures per connection, outside data-event deduplication. Suppressing a reset or error because another socket sent the same payload loses that connection's health signal.
Using a standby account connection
Two connections for the same account can reduce disruption from an individual socket failure. They can share dependencies, so they do not provide independent sources or guarantee that no messages are lost.
- Read both continuously. Use one active processor and a standby whose delivery overlaps the active connection and whose buffered events retain their order.
- Establish coverage before failover. A new socket being connected or acknowledged does not establish a synchronized standby. For example, it can first deliver sequence
103while the active socket is still delivering102. A shared maximum or seen-set alone must not cause102to be discarded or the transitions to be applied in reverse order. - Switch only to a synchronized standby. If it has maintained continuous coverage and can continue in order, promote it and reconnect the failed socket in the background. Establish overlap again before trusting the replacement for failover.
- Reconcile when coverage is uncertain. If both sockets are interrupted, the only trusted source resets, or ordering across the handover cannot be established, follow the REST procedure above.
Rejection notices are best-effort and can be lost without sequence_reset. Keep rejection responses and resolve outstanding orders through REST; healthy redundant sockets do not prove that every rejection was delivered.
Timeouts and uncertain outcomes
A timeout does not mean that an order was rejected. Keep the exact signed body, its hash and any returned order ID until the outcome is known.
- Read the original order by ID or signed hash.
- Prefer order reads and account events to repeated placement requests. If the outcome remains uncertain, keep the original unresolved and pause new orders that would depend on it.
- If you retry a placement, keep the exact signed body and all associated API fields unchanged. The signing-time window and, for GTD, the expiry minimum still apply. A retry refusal does not undo an earlier accepted order.
- Sign a replacement only when you intend a new order and have accounted for the original.
Keep the original signed fields unchanged when recovering a lost response. Changing the salt, timestamp or signed amounts changes the order identity and can create another order.
A temporary 404 ORDER_NOT_FOUND after an uncertain submission is not proof that it never executed. Recent order activity may not yet be visible in a read.
| Result | Recommended action |
|---|---|
PLACE_PENDING or PLACE_OUTCOME_UNKNOWN | Resolve the placement before retrying cancellation. |
ORDER_CONFLICT | Check that the retry uses the original signed request and associated fields. |
validation_failed | Check the request fields and signing clock. If this was a retry, resolve the original order before signing a replacement. |
order_expiration_too_soon | Check the original order before signing a replacement with a later expiry. |
ORDER_STATE_RECOVERING or ORDER_LOOKUP_UNAVAILABLE | Retry the read. A failed lookup does not establish that the placement failed. |
Check the error code and HTTP status when a lookup fails. In that response, status: REJECTED describes the failed lookup, not necessarily the original placement. Retain rejection responses and events because a later read may not return them.
Look up the original order
GET /order/v1/orders/{order_id}
GET /order/v1/orders/by-hash/{hash}Continue reconciling if a read is temporarily unavailable or does not yet reflect a confirmed event.
Other considerations
Amounts and rounding
price_micro and shares_micro use integer millionths. A price of 0.5 is "500000"; one share is "1000000". Use integer strings when your client cannot represent large JSON integers exactly.
collateral_micro = floor(price_micro × shares_micro / 1_000_000)Round down using this formula when preparing signed amounts. For BUY, maker_amount is collateral and taker_amount is shares; SELL reverses them. Keep those amounts consistent with the requested price, quantity and the market’s permitted precision.
Shared rate allowances
Rate allowances are shared across an account’s tokens and sessions. Opening more connections or using another token does not create an independent allowance.
Order reads count toward the Read allowance. Placements, batches and cancellations count toward both Read and their respective action allowance. A signed batch counts as one batch request regardless of its item count. A request refused for exceeding an action’s rate limit can still count toward Read.
Respect Retry-After and the X-RateLimit-* headers. On 429, reduce the send rate and wait before retrying. Keep capacity available for cancellations and recovery reads.
Order history and settlement
Use account events and order reads to track execution. Trade history, portfolio activity and settlement information can update at different times; a temporary delay in one view does not mean the trade failed.
Retain confirmed fills while reconciling subsequent updates. A filled order confirms execution; it does not by itself confirm completed onchain settlement.
Validate your client’s handling of order outcomes
Exercise the cases your client must recover from before relying on it for unattended trading:
- An order that rests, fills completely, or fills partly before cancellation.
- A post-only rejection and a batch with mixed results.
- A placement timeout followed by a lookup of the original order.
- A cancel-all retry with the same request ID, followed by a new cancellation request.
- A GTD expiry, a stream disconnect and a rate-limit response.
Check both the final order state and the recorded fills. A successful HTTP request alone does not verify the whole lifecycle.