pending right away and finish in the background. You find out how a trade
ended by polling, or by listening for webhooks and WebSocket events. Always keep going until you
reach a terminal state.
Two levels of status
A fill split across two venues is one trade with two orders.
Order statuses
A market order never shows
open, partially_filled_open, or cancel_pending.
partialFillReason is an open set. Known values: venue_capacity, price_slipped,
venue_cancelled, venue_expired, venue_closed, user_cancelled, timeout,
clearinghouse_capacity, native_remainder_voided, bridge_shortfall.
bridge_shortfall means a bridge delivered less than quoted, so the order was downsized before
submit. It replaces venue_capacity on a downsized market order that ends partial_fill. A
downsized order the venue filled in full still ends filled, with no reason.
On a market order, remainingSizeRaw is set only on partial_fill (requested shares minus filled
shares) and stays null on filled. Limit orders always carry it, 0 once complete.
The diagram shows the usual paths. Not every order visits every state, and a failure can happen
from any in-flight state. Branch on the status you read, not on the path you expect.
Trade states
GET /execution/status rolls the orders up into overallState:
Stop tracking the trade when
terminal is true. It can stay false for a short time after
every order is final while remaining execution steps finish. If you requested an app-paid
referral, continue tracking that payout separately: its purpose: "referral_payout" signing
request can appear after the trade is filled. See Referrals.
Poll a quote-based trade
Use this forPOST /execution/fill, and for POST /execution/orders using the quoteId in its
response.
filledAmountRaw and actualSharesRaw are 6-decimal integer strings: 1000000 is $1 or 1 share.
quotedPriceRaw is a 0–1 decimal string such as "0.53", not a 6-decimal integer. executionPriceRaw is the effective filled USD per received/sold share, including fee effects already reflected in those quantities; it is omitted without usable fill quantities and never falls back to the quote.
limitPriceRaw is the price-scaled integer: 530000 is 0.53. sizeRaw (listed as limitSizeRaw on GET /execution/orders) uses the share scale: 1000000 is 1 share. Do not read 530000 as dollars.
404 means no order is recorded for that quoteId for this user yet. Right after a fill request,
the request may still be running, so a 404 is not final and should be retried. Do not get a new
quote until Errors, retries & idempotency says to.
API reference: Get execution status.
Poll by order id or your own id
GET /execution/orders lists the user’s orders. Filter it to one order:
status, filledAmountRaw, actualSharesRaw, executionPrice (not
executionPriceRaw), txHash, and errorMessage. executionPrice is a 0–1 decimal string such
as "0.53", equal to filledAmountRaw / actualSharesRaw. It includes a venue fee only where filledAmountRaw
does: a sell’s proceeds are net of fee, while a buy’s cost excludes it and the fee is reported
separately in actualVenueFeeRaw. On Hyperliquid it is the quote until the realized fill is recorded, shortly after filled. filledAmountRaw and actualSharesRaw stay 6-decimal integer strings (1000000 is
$1 or 1 share).
On a Polymarket market order, filledAmountRaw on a buy is the collateral the order paid, before
the venue fee in actualVenueFeeRaw. On a sell it is what the wallet received, after the venue
fee; filledCostRaw holds the gross proceeds and averageFillPriceRaw the price actually traded.
txHash is the Polygon transaction that settled the fill.
All of these are read from the fill’s on-chain OrderFilled log, usually within a minute of filled.
Until then, txHash holds the Polymarket order hash. A limit order keeps the order hash, since it
can settle across several transactions.
Poll until status is terminal. A resting limit order stays open until it fills,
is cancelled, or expires.
To recover a user’s resting orders on a new device, filter GET /execution/orders by status
(open, then partially_filled_open). GET /users/activity also lists orders in every status,
open and unfilled ones included.
Push instead of polling
Payloads are small. Read the order from the API for amounts and prices.
Retries and idempotency: Errors, retries & idempotency.