Market Orders (single-contract trades)
A market order is a single-contract order at the best available price. There are three endpoints: estimate (no commit), submit (asynchronous fill), and a state read. The submit returns immediately with a refId, and you either poll or subscribe to webhooks to find out what happens next.
Auth: estimate and submit are user-scoped (sub must equal the acting user's UUID, plus subsig). The two reads — GET /market-orders and GET /market-orders/{refId} — also accept an ISV-only JWT (no sub) with ?userId= naming which of your users to read; see sections 5 and 6. See Authentication.
Required permission:
market-order. Only the two write endpoints —POST /market-orders/estimateandPOST /market-orders— are gated server-side on themarket-orderuser permission (via thex-required-permissionannotation on the spec). A user without it gets403 permission_deniedon those two calls. The two read endpoints are not permission-gated — a user can read their own order history and individual orders regardless of KYC or suspension status, and an ISV-scoped read isn't rejected for lacking asubeither. CallGET /private/v1/users/USERID/permissionsfirst to see whether a user is cleared to submit — see User Onboarding.
For multi-leg orders, see Parlays (2–12 leg trades) instead.
1. The flow
POST /private/v1/market-orders/estimate ─► see expected price + fee + available qty
POST /private/v1/market-orders ─► 202 with refId
GET /private/v1/market-orders/{refId} ─► poll status, fill progress, P/L
GET /private/v1/market-orders ─► the caller's order history (token-paginated)
Polling is the simplest option. For lower-latency updates without polling, subscribe to MarketOrderEvent webhooks — see Webhooks (push events).
2. The state model
| Field | Values |
|---|---|
status | pending → completed | canceled | failed |
fillStatus | open → partial → filled |
winningStatus | tbd → profit | loss | push (after the event settles) |
Small naming inconsistency to be aware of: in webhook payloads,
fillStatususesrestinginstead ofopenfor the same state. See Webhooks (push events). Treat them as synonyms.
3. POST /private/v1/market-orders/estimate
POST /private/v1/market-orders/estimateA no-commit quote. Use this to show the user what they'd get before they confirm.
Body (EstimateMarketOrderRequest):
{ "contractId": "183c6ffeb2b4b6772a5afb6336293240", "quantity": 25.00 }quantity >= 0allowed here. Use0to see the best available price without specifying a size.
Response (EstimateMarketOrderResponse):
{
"availableQuantity": 50.00,
"expectedAveragePrice": -110,
"expectedAveragePriceAdjusted": -115,
"expectedPayout": 45.45,
"expectedPayoutAdjusted": 43.10,
"expectedFeeAmount": 1.50,
"maxQuantity": 200.00,
"priceList": [-110, -109, -108]
}Field meanings:
availableQuantity— fillable at the expected average price.maxQuantity— total liquidity across all price levels. Taking the whole thing would mean a worse blended price.- Prices are in American format (
-110,+150). - The
*Adjustedvariants include the ISV fee. priceList— the price levels visible at estimate time. Echo bothexpectedAveragePriceandpriceListback into the submit request — they're a required guardrail (see below).
The common failures are 404 LINE_NOT_FOUND (the contract is unknown or has gone stale) or 422 with an insufficient-liquidity error (the requested quantity exceeds what's available).
4. POST /private/v1/market-orders
POST /private/v1/market-ordersSubmit the order. Asynchronous — the server returns 202 immediately with a reference ID, and the actual fill happens in the background.
Body (SubmitMarketOrderRequest):
{
"contractId": "183c6ffeb2b4b6772a5afb6336293240",
"quantity": 25.00,
"expectedAveragePrice": -110,
"priceList": [-110, -109, -108],
"clientOrderId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}quantity > 0required (strict —0is allowed for estimate but not for submit).clientOrderIdis optional — a caller-generated UUID that makes the submission idempotent. When you pass one, the order'srefIdisisv_followed by that value, so you know therefIdbefore the response arrives and a retry with the sameclientOrderIdwon't create a second order. Omit it and the platform generates therefId. Generate a fresh UUID per order; reusing one for a different order is rejected as a duplicate.expectedAveragePriceandpriceListare required guardrails. Pass back exactly what you got from the prior/estimateresponse. If the live price has moved off the listed levels, the backend rejects the submit so you can re-estimate before committing the user's funds. There's no way to bypass this — the only valid value is what came out of the estimate.clientOrderId(optional, UUID) makes the submission safe to retry. When given, the order'srefIdisisv_followed by this value, and a second submission with the sameclientOrderIdreturns409 DUPLICATE_ORDERinstead of placing a second order — so a request that timed out can be resolved withGET /market-orders/{refId}rather than risking a duplicate. It's consumed by the first submission that reaches the wallet even if that order is then rejected; use a newclientOrderIdfor a genuinely new order. Omit it and the platform generates therefIdfor you. AclientOrderIdthat isn't a valid UUID is a422on theclientOrderIdfield.
Response (202, MarketOrderResponse): mostly the same shape as the GET below, with initial status: "pending", fillStatus: "open", filledQuantity: 0 — with one difference: this is the only response that includes requestedQuantity and fee. Neither GET /market-orders/{refId} nor the list endpoint return them (see the note in section 5). If you need the fee amount after this initial response, read the ORDER_FEE transaction from /transactions instead of re-fetching the order.
The fee is locked in at submit time, off the expected price — it is never recalculated against the actual fill.
feeis computed fromexpectedAveragePrice(the price you echoed back from/estimate), before the order has matched against the book at all. Once the order fills,currentAveragePrice(section 5) reflects what actually happened, but the fee is not re-derived from it — there's no second fee computation anywhere downstream. If the true matched price moves off the expected price between estimate and fill, the fee you were charged won't exactly reconcile against the finalcurrentAveragePrice. Treat thefee/ORDER_FEEvalue as fixed at submission, not as something to re-derive from a later read.
{
"refId": "isv_xyz",
"contractId": "183c6ffeb2b4b6772a5afb6336293240",
"requestedQuantity": 25.00,
"fee": 0.50,
"quantity": 24.50,
"filledQuantity": 0,
"openQuantity": 24.50,
"expectedAveragePrice": -110,
"status": "pending",
"fillStatus": "open",
"winningStatus": "tbd",
"createdAt": "...",
"updatedAt": "..."
}The refId is not a UUID — it's a string, possibly prefixed with isv_. Treat it as opaque.
There are three different ID shapes across these surfaces — they don't string-match each other. The order's own
refIdhere looks likeisv_<uuid>. A per-fill ID (returned when you passfills=trueon the GET below) looks likeisv_mo_<uuid>. But therefIdon a wallet transaction (GET /private/v1/transactions, see Wallets) is the bare UUID with theisv_prefix stripped — that's intentional, not a bug, but it means you can't match an order'srefIdagainst a transaction'srefIdby exact string comparison; strip theisv_prefix yourself first if you need to correlate them.
Common failure modes (422, from the trade service):
-
INVALID_CONTRACT— unknown or expired contract. -
PRICE_CHANGED— the live price has moved off the levels inpriceList. Re-call/estimateto get freshexpectedAveragePrice+priceList, show the new quote to the user, then resubmit. -
CONTRACT_SUSPENDED— the contract was suspended between estimate and submit. -
QUANTITY_BELOW_MINIMUM/QUANTITY_ABOVE_MAXIMUM— the requested quantity falls outside the tradeable range. The enforced minimum is $1, net of fee. ProphetX recommends building in a $1.25–$1.50 floor on your own entry-amount UI as a safety margin, so a fee-adjusted stake doesn't land exactly on the enforced minimum and get rejected.
DUPLICATE_ORDERcan come back at two different statuses, depending on cause. ReusedclientOrderId(see above) is a409. A separate, older trade-service-level dedup check — unrelated toclientOrderId— can also produce acode: "DUPLICATE_ORDER", but as a422alongside the other codes in this list. Branch on the HTTP status, not just the code string, if you need to tell them apart.
Insufficient balance is NOT a submit-time error. The API accepts the order (
202,status: "pending") regardless of wallet balance — there is no synchronous funds check. If the balance isn't there when the matching engine goes to fill it, the order is canceled after the fact: pollGET /market-orders/{refId}and watch forstatus: "canceled"withfilledQuantity: 0shortly after submission. There is no402and noINSUFFICIENT_FUNDScode on this endpoint.This cancellation is not distinguishable from any other no-fill cancellation.
status: "canceled"withfilledQuantity: 0is the entire signal — the API does not currently report why the order was canceled (insufficient balance vs. liquidity never arriving vs. any other cause). Don't assume a canceled order with no fill means the user was short on funds; it might just mean the market never matched.
Known issue: a stake below the minimum currently comes back as
422withfield: "ORDER_NOT_FOUND"instead ofQUANTITY_BELOW_MINIMUM. If you seeORDER_NOT_FOUNDon a submit, check whether the stake is below the minimum before treating it as a missing-contract error. Tracked as BBPX-176.
5. GET /private/v1/market-orders/{refId}
GET /private/v1/market-orders/{refId}Not permission-gated (see the callout in the intro). With a sub claim in the JWT, the order must belong to that user. With an ISV-only JWT (no sub), the order may belong to any user of your ISV — useful for support tooling that needs to look up one order without minting a per-user token.
| Query | Default | Effect |
|---|---|---|
fills | false | Set to true to include a per-fill breakdown in response.fills. Omitted by default to keep the payload small. |
Response (MarketOrderResponse):
{
"refId": "isv_xyz",
"contractId": "183c6ffeb2b4b6772a5afb6336293240",
"quantity": 24.50,
"filledQuantity": 24.50,
"openQuantity": 0,
"expectedAveragePrice": -110,
"currentAveragePrice": -108,
"status": "completed",
"fillStatus": "filled",
"winningStatus": "tbd",
"eventId": 999999,
"marketId": 219,
"strike": 2.5,
"createdAt": "...",
"updatedAt": "...",
"fills": null
}
requestedQuantityandfeeare NOT present here. They only appear on the initialPOST /private/v1/market-ordersresponse (section 4) — neither this GET-by-refId endpoint nor the list endpoint (section 6) return them, even thoughquantityhere is already net of the fee. To get the fee amount again later, read theORDER_FEErow fromGET /private/v1/transactions?refId=<refId>rather than expecting it back on the order object.
Read these in pairs:
filledQuantity + openQuantity = quantity.expectedAveragePriceis the floor at submission;currentAveragePriceis the actual achieved price so far.eventId,marketId, andstrikeare sourced from the matched wagers — they'renulluntil a wager has been spawned (i.e. before any fill activity), andstrikeis alsonullfor markets that don't carry one (moneyline). Use them for downstream reconciliation if you need event/market context without re-fetching from the fixtures API.fillsisnullby default. Pass?fills=trueto have the backend populate it with a per-fill breakdown (below).isClosingOrder(boolean) is returned only by the list endpoint (GET /private/v1/market-orders, section 6) and is omitted here and on the submit response.truemarks the opposing order the platform placed to execute a cash-out (POST /positions/close) rather than an order the user submitted — see Positions and Cash Out. Filter on it if you only want user-placed orders in a history view.
Per-fill breakdown (?fills=true)
?fills=true)Each MarketOrderFill entry represents one discrete match against the order book — useful when you need to reconcile against a per-trade ledger rather than just the rolled-up order state.
{
"refId": "isv_xyz",
"...": "...",
"fills": [
{
"refId": "isv_xyz.f1",
"quantity": 10.00,
"filledQuantity": 10.00,
"openQuantity": 0,
"averagePrice": -110,
"fillStatus": "filled",
"winningStatus": "tbd",
"eventId": 999999,
"marketId": 219,
"strike": 2.5,
"createdAt": "...",
"updatedAt": "..."
},
{
"refId": "isv_xyz.f2",
"quantity": 14.50,
"filledQuantity": 14.50,
"openQuantity": 0,
"averagePrice": -107,
"fillStatus": "filled",
"winningStatus": "tbd",
"createdAt": "..."
}
]
}Field meanings:
| Field | Presence | Notes |
|---|---|---|
refId | always | Distinct from the parent refId — treat as opaque. |
quantity | always | Quantity of this fill (after fee, i.e. the size that actually matched). |
filledQuantity / openQuantity | always | Per-fill accounting. On a filled entry, openQuantity is 0. |
createdAt | always | When this fill occurred. |
averagePrice | optional | American price the fill matched at. Absent while pending. |
fillStatus | optional | filled | open | partial. Per-fill state, distinct from the parent order's fillStatus. |
winningStatus | optional | profit | loss | push | tbd. Set after settlement. |
eventId, marketId, strike, updatedAt | optional | Same semantics as on the parent order — sourced from the matched wager. strike is absent for moneyline markets. |
fills is null (not []) when ?fills=true is omitted. When ?fills=true is passed and the order has not matched yet, expect fills: [].
6. GET /private/v1/market-orders — list a user's orders
GET /private/v1/market-orders — list a user's ordersReturns a user's market-order history, most-recent first, token-paginated. Each item is the same MarketOrderResponse shape as the GET-by-refId above — no lighter summary view. Not permission-gated (see the callout in the intro).
With a sub claim in the JWT, returns that user's orders. With an ISV-only JWT (no sub), returns the orders of the user named by ?userId= (required in that case) — that user must belong to your ISV, or you get a 404.
Query parameters
| Name | Type | Default | Notes |
|---|---|---|---|
userId | UUID | unset | Only honored on an ISV-only JWT (no sub) — required in that case. Ignored when the JWT carries a sub. |
limit | integer | 25 | 1 ≤ limit ≤ 100. |
token | string | unset | Opaque cursor — pass the paging.token from the previous response. |
orderBy | string | createdAt | Field to order by. |
orderDir | enum | desc | asc | desc. |
status | string | unset | Comma-separated MarketOrderStatus values to filter by — any of pending, completed, canceled, failed. |
fillStatus | string | unset | Comma-separated FillStatus values to filter by — any of filled, partial, open. |
dateRangeFilter | enum | all | today | this_week | this_month | all. Filters by createdAt. |
Response (ListMarketOrdersResponse)
ListMarketOrdersResponse){
"marketOrders": [ { "refId": "isv_xyz", "isClosingOrder": false, "...": "..." } ],
"paging": { "limit": 25, "token": "eyJpZCI6MTAwfQ==" }
}paging.token is absent when there are no more pages — that's how you know to stop.
Each entry is a MarketOrderResponse plus isClosingOrder, which only this endpoint returns: true means the platform placed the order to execute a cash-out (POST /positions/close), false means the user submitted it. See section 5 and Positions and Cash Out.
Failure modes:
400— ISV-only JWT with nouserId.401— JWT missing/invalid.404— ISV-only JWT with auserIdthat doesn't belong to your ISV.500/503— server error / service temporarily unavailable.
7. Money movement is automatic
You don't move money for order flow. ProphetX handles it on its side:
- Order debit at submit — the order's
quantityis deducted from the wallet atomically. - ISV fee — deducted automatically. Surfaced as
feeon the initial submit response only (section 4) — for any later read, use theORDER_FEEtransaction in/transactionsinstead. You don't compute or post the fee yourself. - Settlement — when the contract settles, payouts (
PAY), refunds (PUSH/VOID), and the resulting balance change are credited to the wallet automatically. ThewinningStatuson the order flips and aContractSettlementEventfires for the contract.
See Wallets for the resulting TransactionType rows.
8. Polling guidance
A few notes to save you time:
- Don't tight-loop. A 1–2 second interval during active fill and longer once
statusstabilizes is plenty. - If you'd rather not poll at all, subscribe to the
/push/market-orderswebhook and let ProphetX push updates. Each event is wrapped in{ id, op, timestamp, data }— see Webhooks (push events). - A terminal
status(completed/canceled/failed) means no further fills.winningStatusmay still flip later when the event settles — that comes through theContractSettlementEventwebhook.
9. Curl
BASE="https://isv-api.sandbox.prophetx.dev/private/v1"
# 1. Estimate — grab expectedAveragePrice + priceList from this response
curl -X POST "$BASE/market-orders/estimate" \
-H "Authorization: Bearer $JWT_USER" \
-H "Content-Type: application/json" \
-d '{ "contractId":"abc...", "quantity":25 }'
# 2. Submit — echo expectedAveragePrice + priceList back from the estimate
curl -X POST "$BASE/market-orders" \
-H "Authorization: Bearer $JWT_USER" \
-H "Content-Type: application/json" \
-d '{
"contractId":"abc...",
"quantity":25,
"expectedAveragePrice":-110,
"priceList":[-110,-109,-108]
}'
# → 202 { "refId":"isv_xyz", "status":"pending", ... }
# 3. Poll (or wait for the webhook)
curl "$BASE/market-orders/isv_xyz" -H "Authorization: Bearer $JWT_USER"
# 3b. Poll with per-fill breakdown
curl "$BASE/market-orders/isv_xyz?fills=true" -H "Authorization: Bearer $JWT_USER"
# 4. History (most recent first; paginate via paging.token)
curl "$BASE/market-orders?limit=25&status=pending,completed&dateRangeFilter=this_week" \
-H "Authorization: Bearer $JWT_USER"Updated 5 days ago
