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/estimate and POST /market-orders — are gated server-side on the market-order user permission (via the x-required-permission annotation on the spec). A user without it gets 403 permission_denied on 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 a sub either. Call GET /private/v1/users/USERID/permissions first 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

FieldValues
statuspending → completed | canceled | failed
fillStatusopen → partial → filled
winningStatustbd → profit | loss | push (after the event settles)

Small naming inconsistency to be aware of: in webhook payloads, fillStatus uses resting instead of open for the same state. See Webhooks (push events). Treat them as synonyms.


3. POST /private/v1/market-orders/estimate

A no-commit quote. Use this to show the user what they'd get before they confirm.

Body (EstimateMarketOrderRequest):

{ "contractId": "183c6ffeb2b4b6772a5afb6336293240", "quantity": 25.00 }
  • quantity >= 0 allowed here. Use 0 to 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 *Adjusted variants include the ISV fee.
  • priceList — the price levels visible at estimate time. Echo both expectedAveragePrice and priceList back 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

Submit 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 > 0 required (strict — 0 is allowed for estimate but not for submit).
  • clientOrderId is optional — a caller-generated UUID that makes the submission idempotent. When you pass one, the order's refId is isv_ followed by that value, so you know the refId before the response arrives and a retry with the same clientOrderId won't create a second order. Omit it and the platform generates the refId. Generate a fresh UUID per order; reusing one for a different order is rejected as a duplicate.
  • expectedAveragePrice and priceList are required guardrails. Pass back exactly what you got from the prior /estimate response. 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's refId is isv_ followed by this value, and a second submission with the same clientOrderId returns 409 DUPLICATE_ORDER instead of placing a second order — so a request that timed out can be resolved with GET /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 new clientOrderId for a genuinely new order. Omit it and the platform generates the refId for you. A clientOrderId that isn't a valid UUID is a 422 on the clientOrderId field.

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. fee is computed from expectedAveragePrice (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 final currentAveragePrice. Treat the fee/ORDER_FEE value 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 refId here looks like isv_<uuid>. A per-fill ID (returned when you pass fills=true on the GET below) looks like isv_mo_<uuid>. But the refId on a wallet transaction (GET /private/v1/transactions, see Wallets) is the bare UUID with the isv_ prefix stripped — that's intentional, not a bug, but it means you can't match an order's refId against a transaction's refId by exact string comparison; strip the isv_ 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 in priceList. Re-call /estimate to get fresh expectedAveragePrice + 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_ORDER can come back at two different statuses, depending on cause. Reused clientOrderId (see above) is a 409. A separate, older trade-service-level dedup check — unrelated to clientOrderId — can also produce a code: "DUPLICATE_ORDER", but as a 422 alongside 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: poll GET /market-orders/{refId} and watch for status: "canceled" with filledQuantity: 0 shortly after submission. There is no 402 and no INSUFFICIENT_FUNDS code on this endpoint.

This cancellation is not distinguishable from any other no-fill cancellation. status: "canceled" with filledQuantity: 0 is 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 422 with field: "ORDER_NOT_FOUND" instead of QUANTITY_BELOW_MINIMUM. If you see ORDER_NOT_FOUND on 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}

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.

QueryDefaultEffect
fillsfalseSet 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
}

requestedQuantity and fee are NOT present here. They only appear on the initial POST /private/v1/market-orders response (section 4) — neither this GET-by-refId endpoint nor the list endpoint (section 6) return them, even though quantity here is already net of the fee. To get the fee amount again later, read the ORDER_FEE row from GET /private/v1/transactions?refId=<refId> rather than expecting it back on the order object.

Read these in pairs:

  • filledQuantity + openQuantity = quantity.
  • expectedAveragePrice is the floor at submission; currentAveragePrice is the actual achieved price so far.
  • eventId, marketId, and strike are sourced from the matched wagers — they're null until a wager has been spawned (i.e. before any fill activity), and strike is also null for 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.
  • fills is null by default. Pass ?fills=true to 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. true marks 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)

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:

FieldPresenceNotes
refIdalwaysDistinct from the parent refId — treat as opaque.
quantityalwaysQuantity of this fill (after fee, i.e. the size that actually matched).
filledQuantity / openQuantityalwaysPer-fill accounting. On a filled entry, openQuantity is 0.
createdAtalwaysWhen this fill occurred.
averagePriceoptionalAmerican price the fill matched at. Absent while pending.
fillStatusoptionalfilled | open | partial. Per-fill state, distinct from the parent order's fillStatus.
winningStatusoptionalprofit | loss | push | tbd. Set after settlement.
eventId, marketId, strike, updatedAtoptionalSame 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

Returns 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

NameTypeDefaultNotes
userIdUUIDunsetOnly honored on an ISV-only JWT (no sub) — required in that case. Ignored when the JWT carries a sub.
limitinteger251 ≤ limit ≤ 100.
tokenstringunsetOpaque cursor — pass the paging.token from the previous response.
orderBystringcreatedAtField to order by.
orderDirenumdescasc | desc.
statusstringunsetComma-separated MarketOrderStatus values to filter by — any of pending, completed, canceled, failed.
fillStatusstringunsetComma-separated FillStatus values to filter by — any of filled, partial, open.
dateRangeFilterenumalltoday | this_week | this_month | all. Filters by createdAt.

Response (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 no userId.
  • 401 — JWT missing/invalid.
  • 404 — ISV-only JWT with a userId that 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 quantity is deducted from the wallet atomically.
  • ISV fee — deducted automatically. Surfaced as fee on the initial submit response only (section 4) — for any later read, use the ORDER_FEE transaction in /transactions instead. 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. The winningStatus on the order flips and a ContractSettlementEvent fires 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 status stabilizes is plenty.
  • If you'd rather not poll at all, subscribe to the /push/market-orders webhook 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. winningStatus may still flip later when the event settles — that comes through the ContractSettlementEvent webhook.

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"


Did this page help you?