Build Order

Build an order without placing it. Returns the order’s typed-data payload (for the wallet to sign) plus a built_order_id to pass to submitOrderHosted once it’s signed.

Use this when you want a human to approve each trade before it submits — for example, surfacing the order details in a wallet popup. For everything else, use createOrderHosted, which builds + signs + submits in one call.

POST /v0/trade/build-order

Python

Polymarket

# Current hosted venues are funded once on Polygon — see /guides/escrow-lifecycle.
# Hosted writes need: pmxt_api_key + wallet_address + private_key (signs EIP-712 locally).
# Pass an outcome straight from client.fetch_markets() — no UUID lookup needed.
import pmxt

client = pmxt.Polymarket(
    pmxt_api_key="YOUR_PMXT_API_KEY",
    wallet_address="0xYourWallet",    # EVM address — its Polygon USDC funds the escrow
    private_key="0x...",    # any EVM key controlling that address
)
market = client.fetch_markets({"query": "trump 2028"})[0]
yes = next(o for o in market.outcomes if o.label.lower() == "yes")
order = client.build_order(
    outcome=yes,
    side="buy",
    type="limit",
    amount=10,
    price=0.55,
)
print(order.id, order.status)

200

{
  "built_order_id": "<string>",
  "typed_data": {},
  "quote": {
    "best_price": 123,
    "expected_avg_price": 123,
    "expected_slippage_pct": 123,
    "estimated_cost_or_proceeds": 123,
    "fillable": true,
    "liquidity": 123,
    "fee_amount": 123,
    "tick_size": "<string>"
  },
  "pull_typed_data": {},
  "resolved": {
    "token_id": "<string>",
    "neg_risk": true,
    "tick_size": 123,
    "opinion_market_id": 123
  }
}

{
  "error": {
    "message": "<string>",
    "retryable": true,
    "exchange": "<string>",
    "detail": {}
  }
}

{
  "error": {
    "message": "<string>",
    "retryable": true,
    "exchange": "<string>",
    "detail": {}
  }
}

{
  "error": {
    "message": "<string>",
    "retryable": true,
    "exchange": "<string>",
    "detail": {}
  }
}

{
  "error": {
    "message": "<string>",
    "retryable": true,
    "exchange": "<string>",
    "detail": {}
  }
}

{
  "error": {
    "message": "<string>",
    "retryable": true,
    "exchange": "<string>",
    "detail": {}
  }
}

Available on: Polymarket, Opinion, Limitless. Other venues raise NotSupported in hosted mode — for those, run a local PMXT service.

Before your first call: deposit USDC on Polygon at pmxt.dev/dashboard/wallet (one-time setup). For the programmatic flow, see escrow lifecycle.

Use any EVM private key. Your USDC sits in a non-custodial PreFundedEscrow on Polygon — for Polymarket, Opinion, and Limitless. PMXT cannot move funds without your EIP-712 signature.

Authorizations

Authorization · string · header · required

Required when calling the hosted API directly (curl, requests, fetch). SDK users pass credentials via constructor params instead.

Body

application/json

Hosted build-order request. Identify the target outcome by passing venue + venue_outcome_id from client.fetch_markets() (the SDK does this automatically when you pass outcome= to create_order or build_order).

side · enum<string> · required

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

Available options: buy, sell

amount · number · 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.

Required range: x >= 0

user_address · string · required

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

venue · enum<string>

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

Available options: polymarket, opinion, limitless

venue_outcome_id · string

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

order_type · enum<string> · default: market

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.

Available options: market, limit

denom · enum<string> · default: shares

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).

Available options: shares, usdc

price · number | null

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

Required range: 0 <= x <= 1

slippage_pct · number | null

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.

Required range: 0 <= x <= 100

Response

200

application/json

Built order with typed data to sign.

Hosted build-order response. The caller must sign typed_data locally (and pull_typed_data if present) and POST the signatures back via submitOrderHosted before the order expires.

built_order_id · string · required

Opaque server-side key used by submitOrderHosted to look up the build context.

side · enum<string> · required

Echo of the order side from the request.

Available options: buy, sell

typed_data · object · required

EIP-712 typed-data payload to sign locally with the wallet key matching user_address. Return the signature in SubmitOrderHostedRequest.signature.

quote · object · required

Pre-trade quote: expected average fill price, slippage, and fees.

Show child attributes

pull_typed_data · object | null

Optional secondary EIP-712 payload for venues that require a separate pull-authorization (notably Polymarket neg-risk markets and sell orders). Sign with the same wallet and return in SubmitOrderHostedRequest.pull_signature. null when not required.

resolved · object | null

Venue-side fields resolved from the supplied outcome — token ids, contract addresses, etc. Useful when you want to cross-reference the order against the venue's own API. null if resolution failed.

Show child attributes