v9

latestOpenAPI 3.0.0raw.githubusercontent.com2026-06-2491679.8 KB

Trading

Create Order

Place a buy or sell order on Polymarket, Opinion, or Limitless. Returns the resulting order with id, fill status, average price, fees, and the on-chain tx hash once it settles.

Most callers pass an outcome straight from client.fetch_markets():

market = client.fetch_markets({"query": "trump 2028"})[0]
order = client.create_order(outcome=market.yes, side="buy", amount=10, order_type="limit", price=0.55)

Need to show the order to a user before they sign it (custom approval UX)? Use buildOrderHosted + submitOrderHosted instead — together they do the same thing.

post/v0/trade/create-order

Request body

venue'polymarket' | 'opinion' | 'limitless'

Venue the outcome trades on. Inferred automatically from your client class in the SDKs.

venue_outcome_idstring

The outcome's identifier (e.g. Polymarket tokenId, Opinion outcome hash, or Limitless token address). Returned by client.fetch_markets().

side'buy' | 'sell' required

Direction of the order. buy opens or adds to a long position on the outcome; sell closes or reduces it.

order_type'market' | 'limit'

market fills immediately at the best available price (subject to slippage_pct); limit rests on the venue's order book at price until matched or cancelled.

amountnumber required

Order size. For market buys, in USDC dollars (the budget you want to spend). For market sells and all limit orders, in outcome shares.

denom'shares' | 'usdc'

Unit amount is denominated in. shares = outcome shares; usdc = USDC dollars. Market buys require usdc; market sells and limit orders require shares (the server validates this combination).

pricenumber nullable

Required for limit orders. Probability in [0, 1] -- e.g. 0.55 means buying / selling shares at 55 cents each. Ignored for market orders.

slippage_pctnumber nullable

Maximum acceptable slippage as a percent. Use aggressive defaults (30 for buys, 99.9 for sells) until the upstream economic validator tightens -- lower values frequently trip precision checks. Ignored for market orders, which pin worst-price to the domain extreme; the server defaults to 20 when omitted.

user_addressstring required

EVM wallet address that will sign the resulting typed data. Must match the wallet whose USDC funded the PMXT PreFundedEscrow on Polygon.

Response

Order accepted by the hosted backend.

idstring required

Unified order id. Stable across the order's lifetime; reuse it in fetchOrderHosted and cancelOrderHosted.

side'buy' | 'sell' nullable

Order direction. null on cancel responses, which only carry id and status.

type'market' | 'limit' nullable

Order type echoed from the build. null on cancel responses.

amountnumber nullable

Order size in outcome shares. For market submits, this is the shares actually obtained (tokens_bought / tokens_sold); for resting limit orders it is the total shares originally requested. null on cancel responses.

pricenumber nullable

Limit price in probability units [0, 1] for limit orders. null for market orders and cancel responses.

fillednumber

Shares filled so far. For market submits this equals the shares obtained on-chain; for resting limit orders it is the running fill total.

remainingnumber

Shares still outstanding (amount - filled, floored at 0). Reaches 0 when the order is fully filled or cancelled.

statusstring required

Lifecycle status. Open-order values include resting and partial; submit responses pass through the upstream status string (failed when an error was raised); cancel responses return the venue's cancel-acknowledgement status.

feenumber nullable

Total fee charged for this order, in USDC dollars. null until the venue reports fees (typically after settlement).

timestampstring nullable

ISO-8601 timestamp the order was created on the venue side. null on cancel responses.

tx_hashstring nullable

On-chain settlement transaction hash on Polygon. null until the order settles on-chain (resting limit orders stay null until matched).

chainstring nullable

Chain the order settled on. Always polygon for hosted orders today (Opinion settles cross-chain via the same Polygon escrow). null on cancel responses.

block_numberinteger nullable

Polygon block height at which the order settled. null until settlement.