> ## Documentation Index
> Fetch the complete documentation index at: https://pmxt-sync-hosted-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Submit Order
> Submit a signed order returned by `buildOrderHosted` and get back the resulting order — id, fill status, average price, and the on-chain tx hash once it settles.
`built_order_id` must come from a recent `buildOrderHosted` call and be submitted before its expiry. For one-shot order placement, use `createOrderHosted` instead.
**Available on:** Polymarket, Opinion, Limitless. Other venues raise `NotSupported` in hosted mode — for those, run a [local PMXT service](/guides/self-hosted).
**Before your first call:** deposit USDC on Polygon at [pmxt.dev/dashboard/wallet](https://pmxt.dev/dashboard/wallet) (one-time setup). For the programmatic flow, see [escrow lifecycle](/guides/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.
## OpenAPI
````yaml /api-reference/openapi-hosted-trading.json post /v0/trade/submit-order
openapi: 3.0.0
info:
title: PMXT Hosted Router API
description: Hosted-only endpoints for cross-venue search, matching, arbitrage, and SQL.
version: 49fbcd4
servers:
- url: https://trade.pmxt.dev
description: Hosted trading (v0)
security:
- bearerAuth: []
tags:
- name: Trading (Hosted)
description: >-
Hosted trading endpoints. Build / submit / cancel orders via
`trade.pmxt.dev/v0/*`. Hosted-mode is the default when `pmxt_api_key` is
set.
- name: Orders & Positions (Hosted)
description: >-
Hosted account reads. Open orders, fills, balances, and positions via
`trade.pmxt.dev/v0/*`. Requires `pmxt_api_key` + `wallet_address`.
- name: MatchedMarkets
description: Cross-venue matched market and event clusters.
- name: SQL
description: Direct read-only SQL access to the catalog (Enterprise).
paths:
/v0/trade/submit-order:
post:
tags:
- Trading
summary: Submit Order
description: >-
Submit a signed order returned by `buildOrderHosted` and get back the
resulting order — id, fill status, average price, and the on-chain tx
hash once it settles.
`built_order_id` must come from a recent `buildOrderHosted` call and be
submitted before its expiry. For one-shot order placement, use
`createOrderHosted` instead.
operationId: submitOrderHosted
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitOrderHostedRequest'
responses:
'200':
description: Order accepted by the hosted backend.
content:
application/json:
schema:
$ref: '#/components/schemas/OrderV0'
'401':
description: Invalid or missing PMXT API key.
content:
application/json:
schema:
$ref: '#/components/schemas/HostedErrorResponse'
'410':
description: >-
`built_order_id` expired before submission. Re-run
`buildOrderHosted` and submit again.
content:
application/json:
schema:
$ref: '#/components/schemas/HostedErrorResponse'
'422':
description: Invalid signature or malformed payload.
content:
application/json:
schema:
$ref: '#/components/schemas/HostedErrorResponse'
x-codeSamples:
- lang: python
label: Polymarket
source: >
# 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")
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)
- lang: javascript
label: Polymarket
source: >
// Current hosted venues are funded once on Polygon — see
/guides/escrow-lifecycle.
// Hosted writes need: pmxtApiKey + walletAddress + privateKey
(signs EIP-712 locally).
// Pass an outcome straight from client.fetchMarkets() — no UUID
lookup needed.
import { Polymarket } from "pmxtjs";
const client = new Polymarket({
pmxtApiKey: "YOUR_PMXT_API_KEY",
walletAddress: "0xYourWallet", // EVM address — its Polygon USDC funds the escrow
privateKey: "0x...", // any EVM key controlling that address
});
const [market] = await client.fetchMarkets({ query: "trump 2028" });
const yes = market.outcomes.find((o) => o.label.toLowerCase() ===
"yes")!;
const built = await client.buildOrder({
outcome: yes,
side: "buy",
type: "limit",
amount: 10,
price: 0.55,
});
const order = await client.submitOrder(built);
console.log(order.id, order.status);
- lang: python
label: Opinion
source: >
# 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.Opinion(
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)
- lang: javascript
label: Opinion
source: >
// Current hosted venues are funded once on Polygon — see
/guides/escrow-lifecycle.
// Hosted writes need: pmxtApiKey + walletAddress + privateKey
(signs EIP-712 locally).
// Pass an outcome straight from client.fetchMarkets() — no UUID
lookup needed.
import { Opinion } from "pmxtjs";
const client = new Opinion({
pmxtApiKey: "YOUR_PMXT_API_KEY",
walletAddress: "0xYourWallet", // EVM address — its Polygon USDC funds the escrow
privateKey: "0x...", // any EVM key controlling that address
});
const [market] = await client.fetchMarkets({ query: "trump 2028" });
const yes = market.outcomes.find((o) => o.label.toLowerCase() ===
"yes")!;
const built = await client.buildOrder({
outcome: yes,
side: "buy",
type: "limit",
amount: 10,
price: 0.55,
});
const order = await client.submitOrder(built);
console.log(order.id, order.status);
components:
schemas:
SubmitOrderHostedRequest:
type: object
description: >-
Hosted submit-order request. `signature` is the local EIP-712 signature
over `BuildOrderHostedResponse.typed_data`.
required:
- built_order_id
- signature
properties:
built_order_id:
type: string
description: >-
Opaque key returned by `buildOrderHosted`. Identifies the
server-side build context to submit against.
signature:
type: string
description: >-
Hex-encoded EIP-712 signature over
`BuildOrderHostedResponse.typed_data`, produced locally with the
wallet key matching `user_address`.
pull_signature:
type: string
nullable: true
description: >-
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:
type: boolean
default: false
description: >-
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.
OrderV0:
type: object
description: >-
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.
required:
- id
- status
properties:
id:
type: string
description: >-
Unified order id. Stable across the order's lifetime; reuse it in
`fetchOrderHosted` and `cancelOrderHosted`.
side:
type: string
enum:
- buy
- sell
nullable: true
description: >-
Order direction. `null` on cancel responses, which only carry id and
status.
type:
type: string
enum:
- market
- limit
nullable: true
description: Order type echoed from the build. `null` on cancel responses.
amount:
type: number
nullable: true
description: >-
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:
type: number
nullable: true
description: >-
Limit price in probability units [0, 1] for limit orders. `null` for
market orders and cancel responses.
filled:
type: number
description: >-
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:
type: number
description: >-
Shares still outstanding (`amount - filled`, floored at 0). Reaches
0 when the order is fully filled or cancelled.
status:
type: string
description: >-
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.
fee:
type: number
nullable: true
description: >-
Total fee charged for this order, in USDC dollars. `null` until the
venue reports fees (typically after settlement).
timestamp:
type: string
nullable: true
description: >-
ISO-8601 timestamp the order was created on the venue side. `null`
on cancel responses.
tx_hash:
type: string
nullable: true
description: >-
On-chain settlement transaction hash on Polygon. `null` until the
order settles on-chain (resting limit orders stay `null` until
matched).
chain:
type: string
nullable: true
description: >-
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:
type: integer
nullable: true
description: >-
Polygon block height at which the order settled. `null` until
settlement.
HostedErrorResponse:
type: object
description: >-
Error envelope returned by `trade.pmxt.dev/v0/*` endpoints. Mirrors the
`ErrorDetail` shape used inside `BaseResponse.error` from the sidecar
spec.
required:
- error
properties:
error:
type: object
description: Structured error envelope. Always present on non-2xx responses.
properties:
message:
type: string
description: Human-readable explanation safe to surface to end users.
code:
type: string
description: >-
Stable hosted-mode error code. Use this (not `message`) for
branching in client code.
enum:
- HOSTED_TRADING_ERROR
- INSUFFICIENT_ESCROW_BALANCE
- ORDER_SIZE_TOO_SMALL
- INVALID_API_KEY
- OUTCOME_NOT_FOUND
- CATALOG_UNAVAILABLE
- BUILT_ORDER_EXPIRED
- INVALID_SIGNATURE
- NO_LIQUIDITY
- MISSING_WALLET_ADDRESS
- ORDER_NOT_FOUND
- INVALID_ORDER
retryable:
type: boolean
description: >-
`true` when the same request may succeed if retried (e.g.
transient catalog outage); `false` when the caller must change
inputs first.
exchange:
type: string
nullable: true
description: >-
Source venue that produced the error (e.g. `polymarket`,
`opinion`, `limitless`), when the failure originated upstream of
PMXT. `null` for PMXT-side errors.
detail:
type: object
additionalProperties: {}
nullable: true
description: >-
Free-form structured diagnostics (e.g. required minimum size,
escrow balance available). Shape varies per `code`.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Required when calling the hosted API directly (curl, requests, fetch).
SDK users pass credentials via constructor params instead.
````