Skip to main content
POST
/
v0
/
trade
/
submit-order
# All 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")
built = client.build_order(
    outcome=yes,
    side="buy",
    type="limit",
    amount=10,
    price=0.55,
)
order = client.submit_order(built)
print(order.id, order.status)
{
  "id": "<string>",
  "status": "<string>",
  "amount": 123,
  "price": 123,
  "filled": 123,
  "remaining": 123,
  "fee": 123,
  "timestamp": "<string>",
  "tx_hash": "<string>",
  "chain": "<string>",
  "block_number": 123
}
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 — the single funding location for every hosted venue (including Opinion, which PMXT settles cross-chain for you). 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 submit-order request. signature is the local EIP-712 signature over BuildOrderHostedResponse.typed_data.

​
built_order_id
string
required

Opaque key returned by buildOrderHosted. Identifies the server-side build context to submit against.

​
signature
string
required

Hex-encoded EIP-712 signature over BuildOrderHostedResponse.typed_data, produced locally with the wallet key matching user_address.

​
pull_signature
string | null

Hex-encoded EIP-712 signature over BuildOrderHostedResponse.pull_typed_data. Required when the build response returned a non-null pull_typed_data (Polymarket neg-risk markets and sell orders); null otherwise.

​
wait
boolean
default:false

When true, the server blocks until on-chain settlement before responding (returns the populated tx_hash). When false, returns immediately with the in-flight order.

Response

Order accepted by the hosted backend.

Hosted-mode Order shape. Mirrors pmxt.Order so the SDK can return it directly. tx_hash, chain, and block_number populate once execution settles on-chain.

​
id
string
required

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

​
status
string
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.

​
side
enum<string> | null

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

Available options:
buy,
sell
​
type
enum<string> | null

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

Available options:
market,
limit
​
amount
number | null

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.

​
price
number | null

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

​
filled
number

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

​
remaining
number

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

​
fee
number | null

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

​
timestamp
string | null

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

​
tx_hash
string | null

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

​
chain
string | null

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_number
integer | null

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