{
"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/build-order": {
"post": {
"summary": "Build Order (Hosted)",
"description": "Construct an unsigned order for Polymarket or Opinion so the caller can inspect it before signing. Returns the EIP-712 typed-data payload, the resolved catalog identifiers, and a `built_order_id` to pass to `submitOrderHosted` after signing locally. Useful when you want to display order details to an end user before they approve the signature — for one-shot \"just place the order\" usage, call `createOrderHosted` instead.\n\nIdentify the target outcome by EITHER (a) catalog `outcome_id` UUID (canonical, cross-venue) OR (b) `venue` + `venue_outcome_id` (the venue-native id returned by `client.fetch_markets()` on a venue client). Both shapes are accepted; the SDK picks the right one automatically based on what you pass in.\n\nSee the [signing guide](/guides/signing) for the wallet flow.",
"tags": [
"Trading (Hosted)"
],
"operationId": "buildOrderHosted",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BuildOrderHostedRequest"
}
}
}
},
"responses": {
"200": {
"description": "Built order with typed data to sign.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BuildOrderHostedResponse"
}
}
}
},
"401": {
"description": "Invalid or missing PMXT API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostedErrorResponse"
}
}
}
},
"403": {
"description": "Insufficient escrow balance to back the requested order size.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostedErrorResponse"
}
}
}
},
"404": {
"description": "Outcome not found in the catalog.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostedErrorResponse"
}
}
}
},
"422": {
"description": "Invalid order parameters (e.g. price out of range, denom mismatch).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostedErrorResponse"
}
}
}
},
"503": {
"description": "Catalog unavailable -- temporary upstream failure.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostedErrorResponse"
}
}
}
}
},
"x-codeSamples": [
{
"lang": "python",
"label": "Polymarket",
"source": "# All hosted venues are funded once on Polygon — see /guides/escrow-lifecycle.\n# Hosted writes need: pmxt_api_key + wallet_address + private_key (signs EIP-712 locally).\n# The SDK accepts either a catalog UUID or a venue-native id from client.fetch_markets().\nimport pmxt\n\nclient = pmxt.Polymarket(\n pmxt_api_key=\"YOUR_PMXT_API_KEY\",\n wallet_address=\"0xYourWallet\", # EVM address — its Polygon USDC funds the escrow\n private_key=\"0x...\", # any EVM key controlling that address\n)\nmarket = client.fetch_markets({\"query\": \"trump 2028\"})[0]\nyes = next(o for o in market.outcomes if o.label.lower() == \"yes\")\norder = client.build_order(\n outcome=yes,\n side=\"buy\",\n type=\"limit\",\n amount=10,\n price=0.55,\n)\nprint(order.id, order.status)\n"
},
{
"lang": "javascript",
"label": "Polymarket",
"source": "// All hosted venues are funded once on Polygon — see /guides/escrow-lifecycle.\n// Hosted writes need: pmxtApiKey + walletAddress + privateKey (signs EIP-712 locally).\n// The SDK accepts either a catalog UUID or a venue-native id from client.fetchMarkets().\nimport { Polymarket } from \"pmxtjs\";\n\nconst client = new Polymarket({\n pmxtApiKey: \"YOUR_PMXT_API_KEY\",\n walletAddress: \"0xYourWallet\", // EVM address — its Polygon USDC funds the escrow\n privateKey: \"0x...\", // any EVM key controlling that address\n});\n\nconst markets = await client.fetchMarkets({ query: \"trump 2028\" });\nconst market = markets[0];\nconst yes = market.outcomes.find((o) => o.label.toLowerCase() === \"yes\")!;\nconst order = await client.buildOrder({\n outcome: yes,\n side: \"buy\",\n type: \"limit\",\n amount: 10,\n price: 0.55,\n});\nconsole.log(order.id, order.status);\n"
},
{
"lang": "python",
"label": "Opinion",
"source": "# All hosted venues are funded once on Polygon — see /guides/escrow-lifecycle.\n# Hosted writes need: pmxt_api_key + wallet_address + private_key (signs EIP-712 locally).\n# The SDK accepts either a catalog UUID or a venue-native id from client.fetch_markets().\nimport pmxt\n\nclient = pmxt.Opinion(\n pmxt_api_key=\"YOUR_PMXT_API_KEY\",\n wallet_address=\"0xYourWallet\", # EVM address — its Polygon USDC funds the escrow\n private_key=\"0x...\", # any EVM key controlling that address\n)\nmarket = client.fetch_markets({\"query\": \"trump 2028\"})[0]\nyes = next(o for o in market.outcomes if o.label.lower() == \"yes\")\norder = client.build_order(\n outcome=yes,\n side=\"buy\",\n type=\"limit\",\n amount=10,\n price=0.55,\n)\nprint(order.id, order.status)\n"
},
{
"lang": "javascript",
"label": "Opinion",
"source": "// All hosted venues are funded once on Polygon — see /guides/escrow-lifecycle.\n// Hosted writes need: pmxtApiKey + walletAddress + privateKey (signs EIP-712 locally).\n// The SDK accepts either a catalog UUID or a venue-native id from client.fetchMarkets().\nimport { Opinion } from \"pmxtjs\";\n\nconst client = new Opinion({\n pmxtApiKey: \"YOUR_PMXT_API_KEY\",\n walletAddress: \"0xYourWallet\", // EVM address — its Polygon USDC funds the escrow\n privateKey: \"0x...\", // any EVM key controlling that address\n});\n\nconst markets = await client.fetchMarkets({ query: \"trump 2028\" });\nconst market = markets[0];\nconst yes = market.outcomes.find((o) => o.label.toLowerCase() === \"yes\")!;\nconst order = await client.buildOrder({\n outcome: yes,\n side: \"buy\",\n type: \"limit\",\n amount: 10,\n price: 0.55,\n});\nconsole.log(order.id, order.status);\n"
}
],
"x-mint": {
"content": "\n **Available on:** Polymarket, Opinion. Other venues raise `NotSupported` in hosted mode — for those, run a [local PMXT service](/guides/self-hosted).\n\n\n\n **Before your first call:** fund your PreFundedEscrow with USDC (one-time per venue). See [escrow lifecycle](/guides/escrow-lifecycle).\n\n\n\n Use any EVM private key. PMXT custodies USDC on Polygon for every hosted venue — including Opinion (BSC), which PMXT settles cross-chain for you.\n"
}
}
},
"/v0/trade/submit-order": {
"post": {
"summary": "Submit Order (Hosted)",
"description": "Submit a signed order to Polymarket or Opinion and return the resulting `Order` with id, fill status, average price, and on-chain tx hash. The `built_order_id` must come from a recent `buildOrderHosted` call and be submitted before its expiry.\n\nFor most callers, prefer `createOrderHosted`, which builds, signs, and submits in a single call.",
"tags": [
"Trading (Hosted)"
],
"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": "# All hosted venues are funded once on Polygon — see /guides/escrow-lifecycle.\n# Hosted writes need: pmxt_api_key + wallet_address + private_key (signs EIP-712 locally).\n# No catalog UUID lookup required — venue-native ids from fetch_markets() work directly.\nimport pmxt\n\nclient = pmxt.Polymarket(\n pmxt_api_key=\"YOUR_PMXT_API_KEY\",\n wallet_address=\"0xYourWallet\", # EVM address — its Polygon USDC funds the escrow\n private_key=\"0x...\", # any EVM key controlling that address\n)\nmarket = client.fetch_markets({\"query\": \"trump 2028\"})[0]\nbuilt = client.build_order(\n outcome=market.yes,\n side=\"buy\",\n type=\"limit\",\n amount=10,\n price=0.55,\n)\norder = client.submit_order(built)\nprint(order.id, order.status)\n"
},
{
"lang": "javascript",
"label": "Polymarket",
"source": "// All hosted venues are funded once on Polygon — see /guides/escrow-lifecycle.\n// Hosted writes need: pmxtApiKey + walletAddress + privateKey (signs EIP-712 locally).\n// No catalog UUID lookup required — venue-native ids from fetchMarkets() work directly.\nimport { Polymarket } from \"pmxtjs\";\n\nconst client = new Polymarket({\n pmxtApiKey: \"YOUR_PMXT_API_KEY\",\n walletAddress: \"0xYourWallet\", // EVM address — its Polygon USDC funds the escrow\n privateKey: \"0x...\", // any EVM key controlling that address\n});\n\nconst [market] = await client.fetchMarkets({ query: \"trump 2028\" });\nconst built = await client.buildOrder({\n outcome: market.yes,\n side: \"buy\",\n type: \"limit\",\n amount: 10,\n price: 0.55,\n});\nconst order = await client.submitOrder(built);\nconsole.log(order.id, order.status);\n"
},
{
"lang": "python",
"label": "Opinion",
"source": "# All hosted venues are funded once on Polygon — see /guides/escrow-lifecycle.\n# Hosted writes need: pmxt_api_key + wallet_address + private_key (signs EIP-712 locally).\n# No catalog UUID lookup required — venue-native ids from fetch_markets() work directly.\nimport pmxt\n\nclient = pmxt.Opinion(\n pmxt_api_key=\"YOUR_PMXT_API_KEY\",\n wallet_address=\"0xYourWallet\", # EVM address — its Polygon USDC funds the escrow\n private_key=\"0x...\", # any EVM key controlling that address\n)\nmarket = client.fetch_markets({\"query\": \"trump 2028\"})[0]\nbuilt = client.build_order(\n outcome=market.yes,\n side=\"buy\",\n type=\"limit\",\n amount=10,\n price=0.55,\n)\norder = client.submit_order(built)\nprint(order.id, order.status)\n"
},
{
"lang": "javascript",
"label": "Opinion",
"source": "// All hosted venues are funded once on Polygon — see /guides/escrow-lifecycle.\n// Hosted writes need: pmxtApiKey + walletAddress + privateKey (signs EIP-712 locally).\n// No catalog UUID lookup required — venue-native ids from fetchMarkets() work directly.\nimport { Opinion } from \"pmxtjs\";\n\nconst client = new Opinion({\n pmxtApiKey: \"YOUR_PMXT_API_KEY\",\n walletAddress: \"0xYourWallet\", // EVM address — its Polygon USDC funds the escrow\n privateKey: \"0x...\", // any EVM key controlling that address\n});\n\nconst [market] = await client.fetchMarkets({ query: \"trump 2028\" });\nconst built = await client.buildOrder({\n outcome: market.yes,\n side: \"buy\",\n type: \"limit\",\n amount: 10,\n price: 0.55,\n});\nconst order = await client.submitOrder(built);\nconsole.log(order.id, order.status);\n"
}
],
"x-mint": {
"content": "\n **Available on:** Polymarket, Opinion. Other venues raise `NotSupported` in hosted mode — for those, run a [local PMXT service](/guides/self-hosted).\n\n\n\n **Before your first call:** fund your PreFundedEscrow with USDC (one-time per venue). See [escrow lifecycle](/guides/escrow-lifecycle).\n\n\n\n Use any EVM private key. PMXT custodies USDC on Polygon for every hosted venue — including Opinion (BSC), which PMXT settles cross-chain for you.\n"
}
}
},
"/v0/trade/create-order": {
"post": {
"summary": "Create Order (Hosted)",
"description": "Place a limit or market order on Polymarket or Opinion in one call. The SDK builds the EIP-712 order payload, signs it locally with your `private_key`, and submits it against your [PreFundedEscrow](/guides/escrow-lifecycle) balance. Returns the resulting `Order` — id, fill status, average fill price, fees, and the on-chain settlement tx hash once it lands.\n\nIdentify the target outcome by EITHER (a) catalog `outcome_id` UUID (canonical, cross-venue) OR (b) `venue` + `venue_outcome_id` (the venue-native id returned by `client.fetch_markets()` on a venue client such as `pmxt.Polymarket`). The natural workflow — `market = client.fetch_markets(...)[0]; client.create_order(outcome=market.yes, ...)` — works without any catalog UUID lookup.\n\nUse `buildOrderHosted` + `submitOrderHosted` separately only when you need to inspect or display the order payload before signing (e.g. a custodial flow where a human approves each trade).",
"tags": [
"Trading (Hosted)"
],
"operationId": "createOrderHosted",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BuildOrderHostedRequest"
}
}
}
},
"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"
}
}
}
},
"403": {
"description": "Insufficient escrow balance.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostedErrorResponse"
}
}
}
},
"404": {
"description": "Outcome not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostedErrorResponse"
}
}
}
},
"422": {
"description": "Invalid order parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostedErrorResponse"
}
}
}
},
"503": {
"description": "Catalog unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostedErrorResponse"
}
}
}
}
},
"x-codeSamples": [
{
"lang": "python",
"label": "Polymarket",
"source": "# All hosted venues are funded once on Polygon — see /guides/escrow-lifecycle.\n# Hosted writes need: pmxt_api_key + wallet_address + private_key (signs EIP-712 locally).\n# The SDK accepts either a catalog UUID or a venue-native id from client.fetch_markets().\nimport pmxt\n\nclient = pmxt.Polymarket(\n pmxt_api_key=\"YOUR_PMXT_API_KEY\",\n wallet_address=\"0xYourWallet\", # EVM address — its Polygon USDC funds the escrow\n private_key=\"0x...\", # any EVM key controlling that address\n)\nmarket = client.fetch_markets({\"query\": \"trump 2028\"})[0]\nyes = next(o for o in market.outcomes if o.label.lower() == \"yes\")\norder = client.create_order(\n outcome=yes,\n side=\"buy\",\n type=\"limit\",\n amount=10,\n price=0.55,\n)\nprint(order.id, order.status)\n"
},
{
"lang": "javascript",
"label": "Polymarket",
"source": "// All hosted venues are funded once on Polygon — see /guides/escrow-lifecycle.\n// Hosted writes need: pmxtApiKey + walletAddress + privateKey (signs EIP-712 locally).\n// The SDK accepts either a catalog UUID or a venue-native id from client.fetchMarkets().\nimport { Polymarket } from \"pmxtjs\";\n\nconst client = new Polymarket({\n pmxtApiKey: \"YOUR_PMXT_API_KEY\",\n walletAddress: \"0xYourWallet\", // EVM address — its Polygon USDC funds the escrow\n privateKey: \"0x...\", // any EVM key controlling that address\n});\n\nconst markets = await client.fetchMarkets({ query: \"trump 2028\" });\nconst market = markets[0];\nconst yes = market.outcomes.find((o) => o.label.toLowerCase() === \"yes\")!;\nconst order = await client.createOrder({\n outcome: yes,\n side: \"buy\",\n type: \"limit\",\n amount: 10,\n price: 0.55,\n});\nconsole.log(order.id, order.status);\n"
},
{
"lang": "python",
"label": "Opinion",
"source": "# All hosted venues are funded once on Polygon — see /guides/escrow-lifecycle.\n# Hosted writes need: pmxt_api_key + wallet_address + private_key (signs EIP-712 locally).\n# The SDK accepts either a catalog UUID or a venue-native id from client.fetch_markets().\nimport pmxt\n\nclient = pmxt.Opinion(\n pmxt_api_key=\"YOUR_PMXT_API_KEY\",\n wallet_address=\"0xYourWallet\", # EVM address — its Polygon USDC funds the escrow\n private_key=\"0x...\", # any EVM key controlling that address\n)\nmarket = client.fetch_markets({\"query\": \"trump 2028\"})[0]\nyes = next(o for o in market.outcomes if o.label.lower() == \"yes\")\norder = client.create_order(\n outcome=yes,\n side=\"buy\",\n type=\"limit\",\n amount=10,\n price=0.55,\n)\nprint(order.id, order.status)\n"
},
{
"lang": "javascript",
"label": "Opinion",
"source": "// All hosted venues are funded once on Polygon — see /guides/escrow-lifecycle.\n// Hosted writes need: pmxtApiKey + walletAddress + privateKey (signs EIP-712 locally).\n// The SDK accepts either a catalog UUID or a venue-native id from client.fetchMarkets().\nimport { Opinion } from \"pmxtjs\";\n\nconst client = new Opinion({\n pmxtApiKey: \"YOUR_PMXT_API_KEY\",\n walletAddress: \"0xYourWallet\", // EVM address — its Polygon USDC funds the escrow\n privateKey: \"0x...\", // any EVM key controlling that address\n});\n\nconst markets = await client.fetchMarkets({ query: \"trump 2028\" });\nconst market = markets[0];\nconst yes = market.outcomes.find((o) => o.label.toLowerCase() === \"yes\")!;\nconst order = await client.createOrder({\n outcome: yes,\n side: \"buy\",\n type: \"limit\",\n amount: 10,\n price: 0.55,\n});\nconsole.log(order.id, order.status);\n"
}
],
"x-mint": {
"content": "\n **Available on:** Polymarket, Opinion. Other venues raise `NotSupported` in hosted mode — for those, run a [local PMXT service](/guides/self-hosted).\n\n\n\n **Before your first call:** fund your PreFundedEscrow with USDC (one-time per venue). See [escrow lifecycle](/guides/escrow-lifecycle).\n\n\n\n Use any EVM private key. PMXT custodies USDC on Polygon for every hosted venue — including Opinion (BSC), which PMXT settles cross-chain for you.\n"
}
}
},
"/v0/orders/cancel/build": {
"post": {
"summary": "Cancel Order -- Build (Hosted)",
"description": "Build the unsigned cancel payload for an existing open order on Polymarket or Opinion. Returns the EIP-712 typed-data to sign locally plus a `cancel_id` you submit to `POST /v0/orders/cancel` once signed.\n\nThe SDK's `cancelOrder()` chains both steps — call this endpoint directly only if you need to show the cancel payload to an end user before signing.",
"tags": [
"Trading (Hosted)"
],
"operationId": "cancelOrderHosted",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CancelBuildHostedRequest"
}
}
}
},
"responses": {
"200": {
"description": "Cancel build response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CancelBuildHostedResponse"
}
}
}
},
"401": {
"description": "Invalid or missing PMXT API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostedErrorResponse"
}
}
}
},
"404": {
"description": "Order not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostedErrorResponse"
}
}
}
},
"422": {
"description": "Invalid order ID.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostedErrorResponse"
}
}
}
}
},
"x-codeSamples": [
{
"lang": "python",
"label": "Polymarket",
"source": "# All hosted venues are funded once on Polygon — see /guides/escrow-lifecycle.\n# Hosted writes need: pmxt_api_key + wallet_address + private_key (signs EIP-712 locally).\n# outcome_id is a catalog UUID from client.fetch_events() — not a venue-native ID.\nimport pmxt\n\nclient = pmxt.Polymarket(\n pmxt_api_key=\"YOUR_PMXT_API_KEY\",\n wallet_address=\"0xYourWallet\", # EVM address — its Polygon USDC funds the escrow\n private_key=\"0x...\", # any EVM key controlling that address\n)\ncancelled = client.cancel_order(\"order_abc123\")\nprint(cancelled.id, cancelled.status)\n"
},
{
"lang": "javascript",
"label": "Polymarket",
"source": "// All hosted venues are funded once on Polygon — see /guides/escrow-lifecycle.\n// Hosted writes need: pmxtApiKey + walletAddress + privateKey (signs EIP-712 locally).\n// outcomeId is a catalog UUID from client.fetchEvents() — not a venue-native ID.\nimport { Polymarket } from \"pmxtjs\";\n\nconst client = new Polymarket({\n pmxtApiKey: \"YOUR_PMXT_API_KEY\",\n walletAddress: \"0xYourWallet\", // EVM address — its Polygon USDC funds the escrow\n privateKey: \"0x...\", // any EVM key controlling that address\n});\n\nconst cancelled = await client.cancelOrder(\"order_abc123\");\nconsole.log(cancelled.id, cancelled.status);\n"
},
{
"lang": "python",
"label": "Opinion",
"source": "# All hosted venues are funded once on Polygon — see /guides/escrow-lifecycle.\n# Hosted writes need: pmxt_api_key + wallet_address + private_key (signs EIP-712 locally).\n# outcome_id is a catalog UUID from client.fetch_events() — not a venue-native ID.\nimport pmxt\n\nclient = pmxt.Opinion(\n pmxt_api_key=\"YOUR_PMXT_API_KEY\",\n wallet_address=\"0xYourWallet\", # EVM address — its Polygon USDC funds the escrow\n private_key=\"0x...\", # any EVM key controlling that address\n)\ncancelled = client.cancel_order(\"order_abc123\")\nprint(cancelled.id, cancelled.status)\n"
},
{
"lang": "javascript",
"label": "Opinion",
"source": "// All hosted venues are funded once on Polygon — see /guides/escrow-lifecycle.\n// Hosted writes need: pmxtApiKey + walletAddress + privateKey (signs EIP-712 locally).\n// outcomeId is a catalog UUID from client.fetchEvents() — not a venue-native ID.\nimport { Opinion } from \"pmxtjs\";\n\nconst client = new Opinion({\n pmxtApiKey: \"YOUR_PMXT_API_KEY\",\n walletAddress: \"0xYourWallet\", // EVM address — its Polygon USDC funds the escrow\n privateKey: \"0x...\", // any EVM key controlling that address\n});\n\nconst cancelled = await client.cancelOrder(\"order_abc123\");\nconsole.log(cancelled.id, cancelled.status);\n"
}
],
"x-mint": {
"content": "\n **Available on:** Polymarket, Opinion. Other venues raise `NotSupported` in hosted mode — for those, run a [local PMXT service](/guides/self-hosted).\n\n\n\n **Before your first call:** fund your PreFundedEscrow with USDC (one-time per venue). See [escrow lifecycle](/guides/escrow-lifecycle).\n\n\n\n Use any EVM private key. PMXT custodies USDC on Polygon for every hosted venue — including Opinion (BSC), which PMXT settles cross-chain for you.\n"
}
}
},
"/v0/user/{address}/balances": {
"get": {
"summary": "Fetch Balance (Hosted)",
"description": "Check the USDC available for trading on Polymarket and Opinion for `address`. Returns the balance held inside the PMXT [PreFundedEscrow](/guides/escrow-lifecycle) contract on behalf of the wallet — *not* the venue-native CLOB-proxy balance. Top up by sending USDC to the escrow.",
"tags": [
"Orders & Positions (Hosted)"
],
"operationId": "fetchBalanceHosted",
"parameters": [
{
"in": "path",
"name": "address",
"required": true,
"schema": {
"type": "string"
},
"description": "EVM wallet address (lowercase or checksum)."
}
],
"responses": {
"200": {
"description": "Balance for the wallet.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BalanceV0"
}
}
}
},
"401": {
"description": "Invalid or missing PMXT API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostedErrorResponse"
}
}
}
},
"503": {
"description": "Catalog or escrow indexer temporarily unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostedErrorResponse"
}
}
}
}
},
"x-codeSamples": [
{
"lang": "python",
"label": "Polymarket",
"source": "# Hosted reads need: pmxt_api_key + wallet_address (private_key is only required for writes).\nimport pmxt\n\nclient = pmxt.Polymarket(\n pmxt_api_key=\"YOUR_PMXT_API_KEY\",\n wallet_address=\"0xYourWallet\",\n)\nbalance = client.fetch_balance()\nprint(balance.amount, balance.currency)\n"
},
{
"lang": "javascript",
"label": "Polymarket",
"source": "// Hosted reads need: pmxtApiKey + walletAddress (privateKey is only required for writes).\nimport { Polymarket } from \"pmxtjs\";\n\nconst client = new Polymarket({\n pmxtApiKey: \"YOUR_PMXT_API_KEY\",\n walletAddress: \"0xYourWallet\",\n});\n\nconst balance = await client.fetchBalance();\nconsole.log(balance.amount, balance.currency);\n"
},
{
"lang": "python",
"label": "Opinion",
"source": "# Hosted reads need: pmxt_api_key + wallet_address (private_key is only required for writes).\nimport pmxt\n\nclient = pmxt.Opinion(\n pmxt_api_key=\"YOUR_PMXT_API_KEY\",\n wallet_address=\"0xYourWallet\",\n)\nbalance = client.fetch_balance()\nprint(balance.amount, balance.currency)\n"
},
{
"lang": "javascript",
"label": "Opinion",
"source": "// Hosted reads need: pmxtApiKey + walletAddress (privateKey is only required for writes).\nimport { Opinion } from \"pmxtjs\";\n\nconst client = new Opinion({\n pmxtApiKey: \"YOUR_PMXT_API_KEY\",\n walletAddress: \"0xYourWallet\",\n});\n\nconst balance = await client.fetchBalance();\nconsole.log(balance.amount, balance.currency);\n"
}
],
"x-mint": {
"content": "\n **Available on:** Polymarket, Opinion. Other venues raise `NotSupported` in hosted mode — for those, run a [local PMXT service](/guides/self-hosted).\n\n\n\n Use any EVM private key. PMXT custodies USDC on Polygon for every hosted venue — including Opinion (BSC), which PMXT settles cross-chain for you.\n"
}
}
},
"/v0/user/{address}/positions": {
"get": {
"summary": "Fetch Positions (Hosted)",
"description": "List the open positions held by `address` across Polymarket and Opinion. Each position carries the catalog `market_id` / `outcome_id`, size, average entry price, and — when available — the current mark price and unrealized PnL.",
"tags": [
"Orders & Positions (Hosted)"
],
"operationId": "fetchPositionsHosted",
"parameters": [
{
"in": "path",
"name": "address",
"required": true,
"schema": {
"type": "string"
},
"description": "EVM wallet address."
}
],
"responses": {
"200": {
"description": "Positions list.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PositionV0"
}
}
}
}
},
"401": {
"description": "Invalid or missing PMXT API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostedErrorResponse"
}
}
}
},
"503": {
"description": "Catalog or indexer temporarily unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostedErrorResponse"
}
}
}
}
},
"x-codeSamples": [
{
"lang": "python",
"label": "Polymarket",
"source": "# Hosted reads need: pmxt_api_key + wallet_address (private_key is only required for writes).\nimport pmxt\n\nclient = pmxt.Polymarket(\n pmxt_api_key=\"YOUR_PMXT_API_KEY\",\n wallet_address=\"0xYourWallet\",\n)\nfor position in client.fetch_positions():\n print(position.market_id, position.shares, position.current_value)\n"
},
{
"lang": "javascript",
"label": "Polymarket",
"source": "// Hosted reads need: pmxtApiKey + walletAddress (privateKey is only required for writes).\nimport { Polymarket } from \"pmxtjs\";\n\nconst client = new Polymarket({\n pmxtApiKey: \"YOUR_PMXT_API_KEY\",\n walletAddress: \"0xYourWallet\",\n});\n\nfor (const position of await client.fetchPositions()) {\n console.log(position.marketId, position.shares, position.currentValue);\n}\n"
},
{
"lang": "python",
"label": "Opinion",
"source": "# Hosted reads need: pmxt_api_key + wallet_address (private_key is only required for writes).\nimport pmxt\n\nclient = pmxt.Opinion(\n pmxt_api_key=\"YOUR_PMXT_API_KEY\",\n wallet_address=\"0xYourWallet\",\n)\nfor position in client.fetch_positions():\n print(position.market_id, position.shares, position.current_value)\n"
},
{
"lang": "javascript",
"label": "Opinion",
"source": "// Hosted reads need: pmxtApiKey + walletAddress (privateKey is only required for writes).\nimport { Opinion } from \"pmxtjs\";\n\nconst client = new Opinion({\n pmxtApiKey: \"YOUR_PMXT_API_KEY\",\n walletAddress: \"0xYourWallet\",\n});\n\nfor (const position of await client.fetchPositions()) {\n console.log(position.marketId, position.shares, position.currentValue);\n}\n"
}
],
"x-mint": {
"content": "\n **Available on:** Polymarket, Opinion. Other venues raise `NotSupported` in hosted mode — for those, run a [local PMXT service](/guides/self-hosted).\n\n\n\n Use any EVM private key. PMXT custodies USDC on Polygon for every hosted venue — including Opinion (BSC), which PMXT settles cross-chain for you.\n"
}
}
},
"/v0/orders/open": {
"get": {
"summary": "Fetch Open Orders (Hosted)",
"description": "List the resting limit orders placed by `address` that have not yet filled or been cancelled. Each entry includes the catalog `market_id` / `outcome_id`, side, size, price, and time-in-force. Optionally filter by `venue` to scope to Polymarket or Opinion only.",
"tags": [
"Orders & Positions (Hosted)"
],
"operationId": "fetchOpenOrdersHosted",
"parameters": [
{
"in": "query",
"name": "address",
"required": true,
"schema": {
"type": "string"
},
"description": "EVM wallet address."
},
{
"in": "query",
"name": "venue",
"schema": {
"type": "string",
"enum": [
"polymarket",
"opinion"
]
},
"description": "Restrict to a single hosted venue."
}
],
"responses": {
"200": {
"description": "Open orders list.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OrderV0"
}
}
}
}
},
"401": {
"description": "Invalid or missing PMXT API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostedErrorResponse"
}
}
}
}
},
"x-codeSamples": [
{
"lang": "python",
"label": "Polymarket",
"source": "# Hosted reads need: pmxt_api_key + wallet_address (private_key is only required for writes).\nimport pmxt\n\nclient = pmxt.Polymarket(\n pmxt_api_key=\"YOUR_PMXT_API_KEY\",\n wallet_address=\"0xYourWallet\",\n)\nfor order in client.fetch_open_orders():\n print(order.id, order.side, order.price, order.remaining)\n"
},
{
"lang": "javascript",
"label": "Polymarket",
"source": "// Hosted reads need: pmxtApiKey + walletAddress (privateKey is only required for writes).\nimport { Polymarket } from \"pmxtjs\";\n\nconst client = new Polymarket({\n pmxtApiKey: \"YOUR_PMXT_API_KEY\",\n walletAddress: \"0xYourWallet\",\n});\n\nfor (const order of await client.fetchOpenOrders()) {\n console.log(order.id, order.side, order.price, order.remaining);\n}\n"
},
{
"lang": "python",
"label": "Opinion",
"source": "# Hosted reads need: pmxt_api_key + wallet_address (private_key is only required for writes).\nimport pmxt\n\nclient = pmxt.Opinion(\n pmxt_api_key=\"YOUR_PMXT_API_KEY\",\n wallet_address=\"0xYourWallet\",\n)\nfor order in client.fetch_open_orders():\n print(order.id, order.side, order.price, order.remaining)\n"
},
{
"lang": "javascript",
"label": "Opinion",
"source": "// Hosted reads need: pmxtApiKey + walletAddress (privateKey is only required for writes).\nimport { Opinion } from \"pmxtjs\";\n\nconst client = new Opinion({\n pmxtApiKey: \"YOUR_PMXT_API_KEY\",\n walletAddress: \"0xYourWallet\",\n});\n\nfor (const order of await client.fetchOpenOrders()) {\n console.log(order.id, order.side, order.price, order.remaining);\n}\n"
}
],
"x-mint": {
"content": "\n **Available on:** Polymarket, Opinion. Other venues raise `NotSupported` in hosted mode — for those, run a [local PMXT service](/guides/self-hosted).\n\n\n\n Use any EVM private key. PMXT custodies USDC on Polygon for every hosted venue — including Opinion (BSC), which PMXT settles cross-chain for you.\n"
}
}
},
"/v0/user/{address}/trades": {
"get": {
"summary": "Fetch My Trades (Hosted)",
"description": "List historical fills for `address` on Polymarket and Opinion. Each trade carries the executed price, size, fees, and the on-chain settlement tx hash.\n\nIn hosted mode, closed orders are modelled as trades — use this endpoint instead of `fetchClosedOrders` / `fetchAllOrders` (which raise `NotSupported`).",
"tags": [
"Orders & Positions (Hosted)"
],
"operationId": "fetchMyTradesHosted",
"parameters": [
{
"in": "path",
"name": "address",
"required": true,
"schema": {
"type": "string"
},
"description": "EVM wallet address."
}
],
"responses": {
"200": {
"description": "Trade history.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UserTradeV0"
}
}
}
}
},
"401": {
"description": "Invalid or missing PMXT API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostedErrorResponse"
}
}
}
}
},
"x-codeSamples": [
{
"lang": "python",
"label": "Polymarket",
"source": "# Hosted reads need: pmxt_api_key + wallet_address (private_key is only required for writes).\nimport pmxt\n\nclient = pmxt.Polymarket(\n pmxt_api_key=\"YOUR_PMXT_API_KEY\",\n wallet_address=\"0xYourWallet\",\n)\nfor trade in client.fetch_my_trades():\n print(trade.id, trade.side, trade.amount, trade.price, trade.tx_hash)\n"
},
{
"lang": "javascript",
"label": "Polymarket",
"source": "// Hosted reads need: pmxtApiKey + walletAddress (privateKey is only required for writes).\nimport { Polymarket } from \"pmxtjs\";\n\nconst client = new Polymarket({\n pmxtApiKey: \"YOUR_PMXT_API_KEY\",\n walletAddress: \"0xYourWallet\",\n});\n\nfor (const trade of await client.fetchMyTrades()) {\n console.log(trade.id, trade.side, trade.amount, trade.price, trade.txHash);\n}\n"
},
{
"lang": "python",
"label": "Opinion",
"source": "# Hosted reads need: pmxt_api_key + wallet_address (private_key is only required for writes).\nimport pmxt\n\nclient = pmxt.Opinion(\n pmxt_api_key=\"YOUR_PMXT_API_KEY\",\n wallet_address=\"0xYourWallet\",\n)\nfor trade in client.fetch_my_trades():\n print(trade.id, trade.side, trade.amount, trade.price, trade.tx_hash)\n"
},
{
"lang": "javascript",
"label": "Opinion",
"source": "// Hosted reads need: pmxtApiKey + walletAddress (privateKey is only required for writes).\nimport { Opinion } from \"pmxtjs\";\n\nconst client = new Opinion({\n pmxtApiKey: \"YOUR_PMXT_API_KEY\",\n walletAddress: \"0xYourWallet\",\n});\n\nfor (const trade of await client.fetchMyTrades()) {\n console.log(trade.id, trade.side, trade.amount, trade.price, trade.txHash);\n}\n"
}
],
"x-mint": {
"content": "\n **Available on:** Polymarket, Opinion. Other venues raise `NotSupported` in hosted mode — for those, run a [local PMXT service](/guides/self-hosted).\n\n\n\n Use any EVM private key. PMXT custodies USDC on Polygon for every hosted venue — including Opinion (BSC), which PMXT settles cross-chain for you.\n"
}
}
},
"/v0/orders/{order_id}": {
"get": {
"summary": "Fetch Order (Hosted)",
"description": "Look up a single order on Polymarket or Opinion by its `order_id` (the same id returned from `createOrderHosted` or `fetchOpenOrdersHosted`). Returns the order's current status, filled / remaining size, average fill price, and — once settled — the on-chain tx hash.",
"tags": [
"Orders & Positions (Hosted)"
],
"operationId": "fetchOrderHosted",
"parameters": [
{
"in": "path",
"name": "order_id",
"required": true,
"schema": {
"type": "string"
},
"description": "Unified order id."
}
],
"responses": {
"200": {
"description": "The order.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrderV0"
}
}
}
},
"401": {
"description": "Invalid or missing PMXT API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostedErrorResponse"
}
}
}
},
"404": {
"description": "Order not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostedErrorResponse"
}
}
}
}
},
"x-codeSamples": [
{
"lang": "python",
"label": "Polymarket",
"source": "# Hosted reads need: pmxt_api_key + wallet_address (private_key is only required for writes).\nimport pmxt\n\nclient = pmxt.Polymarket(\n pmxt_api_key=\"YOUR_PMXT_API_KEY\",\n wallet_address=\"0xYourWallet\",\n)\norder = client.fetch_order(\"order_abc123\")\nprint(order.id, order.status, order.filled, order.remaining)\n"
},
{
"lang": "javascript",
"label": "Polymarket",
"source": "// Hosted reads need: pmxtApiKey + walletAddress (privateKey is only required for writes).\nimport { Polymarket } from \"pmxtjs\";\n\nconst client = new Polymarket({\n pmxtApiKey: \"YOUR_PMXT_API_KEY\",\n walletAddress: \"0xYourWallet\",\n});\n\nconst order = await client.fetchOrder(\"order_abc123\");\nconsole.log(order.id, order.status, order.filled, order.remaining);\n"
},
{
"lang": "python",
"label": "Opinion",
"source": "# Hosted reads need: pmxt_api_key + wallet_address (private_key is only required for writes).\nimport pmxt\n\nclient = pmxt.Opinion(\n pmxt_api_key=\"YOUR_PMXT_API_KEY\",\n wallet_address=\"0xYourWallet\",\n)\norder = client.fetch_order(\"order_abc123\")\nprint(order.id, order.status, order.filled, order.remaining)\n"
},
{
"lang": "javascript",
"label": "Opinion",
"source": "// Hosted reads need: pmxtApiKey + walletAddress (privateKey is only required for writes).\nimport { Opinion } from \"pmxtjs\";\n\nconst client = new Opinion({\n pmxtApiKey: \"YOUR_PMXT_API_KEY\",\n walletAddress: \"0xYourWallet\",\n});\n\nconst order = await client.fetchOrder(\"order_abc123\");\nconsole.log(order.id, order.status, order.filled, order.remaining);\n"
}
],
"x-mint": {
"content": "\n **Available on:** Polymarket, Opinion. Other venues raise `NotSupported` in hosted mode — for those, run a [local PMXT service](/guides/self-hosted).\n\n\n\n Use any EVM private key. PMXT custodies USDC on Polygon for every hosted venue — including Opinion (BSC), which PMXT settles cross-chain for you.\n"
}
}
}
},
"components": {
"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."
}
},
"schemas": {
"UnifiedOutcome": {
"type": "object",
"required": [
"outcomeId",
"marketId",
"label"
],
"properties": {
"outcomeId": {
"type": "string"
},
"marketId": {
"type": "string"
},
"label": {
"type": "string"
},
"price": {
"type": "number",
"nullable": true
},
"priceChange24h": {
"type": "number",
"nullable": true
},
"bestBid": {
"type": "number",
"nullable": true
},
"bestAsk": {
"type": "number",
"nullable": true
},
"metadata": {
"type": "object",
"nullable": true
}
}
},
"UnifiedMarket": {
"type": "object",
"required": [
"marketId",
"title",
"slug",
"outcomes"
],
"properties": {
"marketId": {
"type": "string"
},
"eventId": {
"type": "string",
"nullable": true
},
"title": {
"type": "string"
},
"slug": {
"type": "string"
},
"description": {
"type": "string",
"nullable": true
},
"url": {
"type": "string",
"nullable": true
},
"image": {
"type": "string",
"nullable": true
},
"category": {
"type": "string",
"nullable": true
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"volume": {
"type": "number",
"nullable": true
},
"volume24h": {
"type": "number"
},
"liquidity": {
"type": "number"
},
"openInterest": {
"type": "number",
"nullable": true
},
"resolutionDate": {
"type": "string",
"format": "date-time",
"nullable": true
},
"tickSize": {
"type": "number",
"nullable": true
},
"status": {
"type": "string",
"nullable": true
},
"contractAddress": {
"type": "string",
"nullable": true
},
"outcomes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UnifiedOutcome"
}
}
}
},
"UnifiedEvent": {
"type": "object",
"required": [
"id",
"title",
"slug",
"markets"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string",
"nullable": true
},
"slug": {
"type": "string"
},
"markets": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UnifiedMarket"
}
},
"volume24h": {
"type": "number",
"nullable": true
},
"volume": {
"type": "number",
"nullable": true
},
"url": {
"type": "string",
"nullable": true
},
"image": {
"type": "string",
"nullable": true
},
"category": {
"type": "string",
"nullable": true
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
}
}
},
"ListMeta": {
"type": "object",
"required": [
"count",
"limit",
"offset"
],
"properties": {
"count": {
"type": "integer"
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
}
}
},
"ErrorResponse": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"RateLimitError": {
"type": "object",
"required": [
"error",
"plan",
"limit",
"used"
],
"properties": {
"error": {
"type": "string"
},
"plan": {
"type": "string"
},
"limit": {
"type": "integer"
},
"used": {
"type": "integer"
},
"window": {
"type": "string"
}
}
},
"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",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string",
"description": "Stable hosted-mode error 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"
},
"exchange": {
"type": "string",
"nullable": true
},
"detail": {
"type": "object",
"additionalProperties": {},
"nullable": true
}
}
}
}
},
"BuildOrderHostedRequest": {
"type": "object",
"description": "Hosted build-order request. The caller must identify the target outcome in one of two ways: either (a) pass a catalog `outcome_id` UUID, or (b) pass `venue` plus `venue_outcome_id` (the venue-native identifier returned by `client.fetch_markets()` on a venue client such as `pmxt.Polymarket` or `pmxt.Opinion`). `market_id` is optional in both cases -- the backend derives it from the supplied identifier when omitted.",
"required": [
"side",
"amount",
"user_address"
],
"properties": {
"market_id": {
"type": "string",
"format": "uuid",
"description": "Catalog market UUID. Optional -- derived from `outcome_id` or `(venue, venue_outcome_id)` when omitted."
},
"outcome_id": {
"type": "string",
"format": "uuid",
"description": "Catalog outcome UUID. Provide this OR `(venue, venue_outcome_id)`."
},
"venue": {
"type": "string",
"enum": [
"polymarket",
"opinion"
],
"description": "Venue name. Required when identifying the outcome via `venue_outcome_id` instead of the catalog `outcome_id` UUID."
},
"venue_outcome_id": {
"type": "string",
"description": "Venue-native outcome identifier (e.g. Polymarket `tokenId`, Opinion outcome hash). Required when `venue` is supplied instead of `outcome_id`."
},
"side": {
"type": "string",
"enum": [
"buy",
"sell"
]
},
"order_type": {
"type": "string",
"enum": [
"market",
"limit"
],
"default": "market"
},
"amount": {
"type": "number",
"minimum": 0,
"description": "Order size. For `market` buys, in USDC; for `market` sells / `limit`, in shares."
},
"denom": {
"type": "string",
"enum": [
"shares",
"usdc"
],
"default": "shares"
},
"price": {
"type": "number",
"minimum": 0,
"maximum": 1,
"nullable": true,
"description": "Required for `limit` orders. Probability in [0, 1]."
},
"slippage_pct": {
"type": "number",
"minimum": 0,
"maximum": 100,
"nullable": true
},
"user_address": {
"type": "string",
"description": "EVM wallet address that will sign the resulting typed data."
}
}
},
"BuildOrderHostedResponse": {
"type": "object",
"description": "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.",
"required": [
"built_order_id",
"side",
"typed_data",
"quote"
],
"properties": {
"built_order_id": {
"type": "string",
"description": "Opaque server-side key used by `submitOrderHosted` to look up the build context."
},
"side": {
"type": "string",
"enum": [
"buy",
"sell"
]
},
"typed_data": {
"type": "object",
"description": "EIP-712 typed data for the order. Sign locally with the wallet that matches `user_address`."
},
"pull_typed_data": {
"type": "object",
"nullable": true,
"description": "Optional secondary EIP-712 payload for venues that require a pull-authorization (e.g. Polymarket neg-risk markets)."
},
"quote": {
"type": "object",
"description": "Pre-trade quote: expected average fill price, slippage, and fees.",
"properties": {
"best_price": {
"type": "number"
},
"expected_avg_price": {
"type": "number"
},
"expected_slippage_pct": {
"type": "number"
},
"estimated_cost_or_proceeds": {
"type": "number"
},
"fillable": {
"type": "boolean"
},
"liquidity": {
"type": "number"
},
"fee_amount": {
"type": "number"
},
"tick_size": {
"type": "string"
}
}
},
"resolved": {
"type": "object",
"nullable": true,
"description": "Venue-native fields resolved from the catalog UUIDs (`venue`, `token_id`, `neg_risk`, `tick_size`).",
"properties": {
"venue": {
"type": "string",
"enum": [
"polymarket",
"opinion"
]
},
"token_id": {
"type": "string"
},
"neg_risk": {
"type": "boolean"
},
"tick_size": {
"type": "number"
},
"opinion_market_id": {
"type": "integer",
"nullable": true
}
}
}
}
},
"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"
},
"signature": {
"type": "string",
"description": "Hex-encoded EIP-712 signature."
},
"pull_signature": {
"type": "string",
"nullable": true,
"description": "Signature for the secondary pull-authorization, required when `pull_typed_data` was returned."
},
"wait": {
"type": "boolean",
"default": false,
"description": "When `true`, the server waits for on-chain settlement before responding."
}
}
},
"CancelBuildHostedRequest": {
"type": "object",
"required": [
"order_id",
"user_address"
],
"properties": {
"order_id": {
"type": "string",
"description": "Unified order id, as returned by `fetchOpenOrdersHosted`."
},
"user_address": {
"type": "string"
}
}
},
"CancelBuildHostedResponse": {
"type": "object",
"required": [
"cancel_id",
"typed_data",
"deadline"
],
"properties": {
"cancel_id": {
"type": "string"
},
"typed_data": {
"type": "object"
},
"pull_typed_data": {
"type": "object",
"nullable": true
},
"deadline": {
"type": "integer",
"description": "Unix epoch (s) after which the cancel build expires."
}
}
},
"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"
},
"market_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"outcome_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"side": {
"type": "string",
"enum": [
"buy",
"sell"
],
"nullable": true
},
"type": {
"type": "string",
"enum": [
"market",
"limit"
],
"nullable": true
},
"amount": {
"type": "number",
"nullable": true
},
"price": {
"type": "number",
"nullable": true
},
"filled": {
"type": "number"
},
"remaining": {
"type": "number"
},
"status": {
"type": "string"
},
"fee": {
"type": "number",
"nullable": true
},
"timestamp": {
"type": "string",
"nullable": true
},
"tx_hash": {
"type": "string",
"nullable": true,
"description": "On-chain transaction hash. Null until settled."
},
"chain": {
"type": "string",
"nullable": true
},
"block_number": {
"type": "integer",
"nullable": true
}
}
},
"UserTradeV0": {
"type": "object",
"description": "Hosted-mode `UserTrade` shape. Mirrors `pmxt.UserTrade`.",
"properties": {
"id": {
"type": "string",
"nullable": true
},
"market_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"outcome_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"side": {
"type": "string",
"enum": [
"buy",
"sell"
],
"nullable": true
},
"amount": {
"type": "number",
"nullable": true
},
"price": {
"type": "number",
"nullable": true
},
"fee": {
"type": "number",
"nullable": true
},
"timestamp": {
"type": "string",
"nullable": true
},
"tx_hash": {
"type": "string",
"nullable": true
},
"chain": {
"type": "string",
"nullable": true
},
"venue": {
"type": "string",
"enum": [
"polymarket",
"opinion"
],
"nullable": true
}
}
},
"PositionV0": {
"type": "object",
"description": "Hosted-mode `Position` shape. `current_price`, `current_value`, `entry_price`, `realized_pnl`, and `outcome_label` may be null when the server doesn't yet have the data.",
"required": [
"venue",
"shares"
],
"properties": {
"market_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"outcome_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"venue": {
"type": "string",
"enum": [
"polymarket",
"opinion"
]
},
"shares": {
"type": "number"
},
"current_price": {
"type": "number",
"nullable": true
},
"current_value": {
"type": "number",
"nullable": true
},
"outcome_label": {
"type": "string",
"nullable": true
},
"entry_price": {
"type": "number",
"nullable": true
},
"realized_pnl": {
"type": "number",
"nullable": true
}
}
},
"BalanceV0": {
"type": "object",
"description": "Hosted-mode `Balance` shape. Returns USDC held inside the PMXT `PreFundedEscrow` contract.",
"required": [
"currency",
"amount"
],
"properties": {
"currency": {
"type": "string",
"default": "USDC"
},
"amount": {
"type": "number"
},
"venue": {
"type": "string",
"enum": [
"polymarket",
"opinion"
],
"nullable": true,
"description": "Set when the hosted backend returns a per-venue breakdown; null when balance is venue-agnostic."
}
}
}
}
}
}