Follow an order through trading, live updates, recorded reads and settlement.
Agara matches orders off-chain and settles fills on Base. Use the order ID to track how much can still trade and the fill ID to track each execution through settlement.
Trading covers order submission, validation, matching and cancellation. The placement response, open order quantity and individual fills describe different parts of the outcome.
Example: GTC limit BUY · 10 shares; 4 fill at the limit or better; 6 remain open, then are cancelled.
Authenticate and sign. Use an authorised wallet and the correct signing domain. Agara uses EIP-712 typed-data signing to authorise the order.
Keep the request consistent. Submit the signed instruction with matching API fields. Keep its signed hash, original request and any returned order ID so you can resolve an uncertain response.
Preserve the original on retry. Changing signed fields creates a new order identity. Read the original order's state before signing a replacement.
Request checks. Authentication, signature, order fields, signing time and any expiry must be valid. A valid signature alone does not guarantee that the order can trade.
Trading checks. The matching engine checks the current market state, supported price and size, available assets and execution constraints such as post-only or FOK.
Handle each result. A refused request includes a reason to act on. Batch items have individual outcomes; a batch is not an atomic group of dependent trades.
Separate time limits. All order types use a current signing timestamp. GTD additionally has a separate expiry deadline. The request's time checks still apply when retrying.
Support durability. The Raft Replicated Journal maintains a record of trading instructions to support recovery of trading state.
Track the trading result separately. Recording an instruction does not mean that its entire quantity filled. Use the returned order state and subsequent updates to follow the outcome.
Keep settlement distinct. A trading result does not establish on-chain confirmation. Executed fills continue through the settlement layer.
Respect the limit. A BUY executes at its limit price or lower; a SELL executes at its limit or higher. A limit controls the acceptable execution price, not whether a fill is guaranteed.
Track partial execution. In the example, 4 shares fill and the GTC order's remaining 6 rest on the book. Only that open remainder can trade later or be cancelled.
Keep individual fills. One order can produce several executions. Track the overall instruction by order ID and record each execution once by fill_id.
Policy
What happens to unfilled quantity
GTC
Can remain open until filled or cancelled.
GTD
Can remain open, subject to its expiry deadline.
FAK
Available quantity fills immediately; any remainder is cancelled.
FOK
The full quantity must execute immediately, otherwise the order is rejected.
Distinguish receipt from an outcome. Router 202 PENDING confirms receipt for processing. Order Service 202 UNKNOWN leaves placement unresolved. Neither confirms that the order is resting.
Read the order state. A successful response can describe an open, partly filled or completed order. Check its remaining quantity before deciding how much can still be cancelled.
Expect different arrival orders. A fill can arrive before the placement reply. Correlate them with the same order and count the fill once; a later response does not undo a confirmed fill.
Reconcile uncertainty. After a timeout or unresolved response, read the original order by ID or signed hash. A refused retry does not undo an earlier accepted order.
Cancellation affects the quantity still open when it is processed. Sending a cancel request does not freeze the order.
The boundary is when the engine processes cancellation. Sending the request does not freeze matching.
Cancel the remainder. All 6 remaining shares are still open in this example, so cancellation closes those 6. The 4-share fill stays valid.
Allow for races. Another fill can occur before cancellation takes effect, leaving less quantity to cancel. If the order has already filled completely, nothing remains open.
Confirm uncertain results. Reconcile or retry CANCEL_UNKNOWN for the same order. A cancellation request alone is not confirmation that the order is closed.
Size replacements from the final outcome. Account for fills before placing a replacement. A cancelled order can still have executions awaiting settlement.
A successful new cancel-all includes orders still resting when it is processed. An order confirmed open beforehand is included if its remainder is still resting at that point.
A pending placement can become open afterward. Stop new submissions, resolve pending placements and check remaining orders before relying on cancel-all to leave no open orders.
The matching engine produces order and fill updates. The account stream delivers them live, and the same activity becomes available through recorded order and trade reads. These paths can reach the client at different times.
Matching engine updates feed the event stream. Live delivery and recorded reads are separate from the HTTP reply.
Correlate the order. Use its order ID or signed hash to associate updates with the original instruction. Repeated order identifiers can describe different changes to the same order.
Count each execution once. The example produces a 4-share fill with fill_id: "8421". Deduplicate fills by that ID, rather than by order ID.
Update the open remainder.order_accepted indicates that quantity rested; here, 6 shares remain open. A later order_cancelled closes those 6 while preserving the earlier fill.
Allow for independent delivery. A fill may arrive before the HTTP placement reply or appear in history later. Preserve a confirmed fill when a later-arriving response has not yet caught up.
Reconcile missed activity. Reconnecting restores future messages; the account stream does not replay the gap. On a disconnect or sequence_reset, rebuild the affected account state.
Combine the stream with reads. Buffer new updates while refreshing orders, fills and portfolio state through REST. Include balances and positions when checking the effect of missed activity.
Retain known executions. Merge by stable identifiers and wait for reads to reflect fills already observed. Avoid creating a replacement order while the original outcome is unresolved.
The client reads recorded order and trade data through the API. The database holds the records: an order describes the instruction's state, while its trade history describes what actually executed.
The client reads recorded state through the API; cancellation preserves the 4-share fill. Quantities are in shares.
Read the order by its identity. The order lookup reports its current state and quantities. Use is_terminal to determine whether any remainder can still trade.
Keep matched and open quantities separate. After the example's fill, 4 shares are matched and 6 are open. After cancellation, the order is CANCELLED, 4 remain matched and 0 are open.
Read its executions independently. The order-trades endpoint still returns the same 4-share fill, 8421. Cancellation changes the order's remainder; it does not remove its earlier executions.
Allow recent reads to catch up. A live fill can arrive before recorded reads reflect it. Keep the fill and check again rather than treating its temporary absence as a reversal.
Match records by stable IDs. Use the order ID or signed hash for the instruction and fill_id for each execution. Seeing the same fill in the stream and in history is one execution.
Use the appropriate read. Order lookup answers what can still trade; order-trades lists its fills. Use portfolio trades when following settlement status and the transaction hash.
Complete the refresh. Follow pagination where supported and handle partial or unavailable results before treating the history refresh as complete.
The matching engine passes executed fills into settlement on Base. The client follows confirmation through the trade API, separately from the state of the order's unfilled remainder.
The matching engine supplies the fill, Base confirms the transaction, and the client reads the result through the API. Only the 4 executed shares enter settlement.
Start with the executed quantity. The 4-share fill exists after off-chain matching. Its trade can show MATCHED while settlement is still outstanding.
Distinguish the intermediate steps. Submission and transaction checks are stages in settlement. They are not additional order statuses, and submitting a transaction alone does not confirm the fill.
Follow the same execution. Confirmation updates the existing fill's settlement state. It does not create another trade to count.
Use portfolio trades. Find the original fill_id in GET /trade/v1/portfolio/trades. The confirmed trade shows CONFIRMED and its transaction_hash. The hash can be unavailable earlier.
Keep order and trade states distinct. The order can already be CANCELLED while its 4-share execution awaits confirmation. The 6 cancelled, unfilled shares never enter settlement.
Track an outstanding fill instead of replacing it. A pending confirmation is not evidence that matching failed. Follow the original trade's state; placing another order would be a separate trading instruction.