Trading

Get a single order by ID (polysim-shape row).

Returns one order row in the same Polysimulator shape as GET /v1/orders. The order_id path param is the integer ID from an order row or returned by POST /v1/orders / POST /v1/clob/order.

ID space caveat: PendingOrder.id (limit orders) and Order.id (fills) are independent auto-increment sequences — the same integer can refer to different rows in each table. The default lookup precedence is PendingOrder first (matches DELETE semantics and the common limit-order polling case), then Order on miss. Every row returned by this endpoint and GET /v1/orders carries source: pass that value as ?source= to fetch the exact row again. ?source=filled forces the Order table; ?source=pending forces PendingOrder.

When parent_order_id is present on a fill row, it identifies the parent PendingOrder. Fetch that parent with GET /v1/orders/{parent_order_id}?source=pending.

GET

orders

{order_id}

Get a single order by ID (polysim-shape row).

curl --request GET \
  --url https://api.polysimulator.com/v1/orders/{order_id} \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.polysimulator.com/v1/orders/{order_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.polysimulator.com/v1/orders/{order_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.polysimulator.com/v1/orders/{order_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.polysimulator.com/v1/orders/{order_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "order_id": 123,
  "source": "pending",
  "market_id": "<string>",
  "side": "<string>",
  "outcome": "<string>",
  "order_type": "<string>",
  "limit_price": "<string>",
  "quantity": "<string>",
  "time_in_force": "<string>",
  "status": "<string>",
  "parent_order_id": 123,
  "client_order_id": "<string>",
  "magic": 123,
  "magic_label": "<string>",
  "created_at": "<string>",
  "filled_at": "<string>",
  "fill_price": "<string>",
  "cancelled_at": "<string>",
  "cancelled_reason": "<string>",
  "rejected_reason": "<string>",
  "hold_reason": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

Authorizations

X-API-Key

string

header

required

Issue from /v1/keys (or admin-issued for enterprise tier).

Headers

X-API-Key

string | null

Your PolySimulator API key

POLY_API_KEY

string | null

Polymarket-CLOB-compat alias for X-API-Key (underscore form). SDK clients ported from Polymarket can authenticate without changing header names. X-API-Key takes precedence when both are provided.

Poly-API-Key

string | null

PM-CLOB-compat dashed-form alias for X-API-Key. Same value semantics as POLY_API_KEY but with HTTP-conventional dash separators. Both spellings are accepted end-to-end.

authorization

string | null

PM-CLOB-compat: Authorization: Bearer ps_live_... (or ps_test_...) is accepted as an alias for X-API-Key so py-clob-client and other ported SDKs authenticate without header name changes. Bearer JWTs are NOT accepted here — use the dashboard-auth endpoints for those.

Path Parameters

order_id

integer

required

Query Parameters

source

string | null

Disambiguate the table lookup: pending forces the PendingOrder table (limit orders), filled forces the Order table (fills). Use the row's response source to fetch that exact row. Default None tries PendingOrder first, falls back to Order on miss.

wallet_id

integer | null

Optional wallet scope — when supplied, only returns the row if it belongs to this wallet. Mirrors the list_orders wallet_id pattern so per-wallet pollers stay consistent.

Response

Successful Response

Compact order representation for list and single-order endpoints.

order_id

integer

required

ID in the table identified by source. Fetch this exact row with GET /v1/orders/{order_id}?source={source}.

source

enum<string>

required

Table containing order_id: pending = PendingOrder, filled = Order. Pass this value as ?source= when fetching the row by ID. This identifies the table, regardless of the row's status.

Available options:

pending,

filled

market_id

string

required

side

string

required

outcome

string

required

order_type

string

required

limit_price

string

required

quantity

string

required

time_in_force

string

required

status

string

required

parent_order_id

integer | null

Verified parent PendingOrder ID for a partial fill. The parent must match the user, requested wallet scope, market_id, and client_order_id prefix before the :p_ suffix. Fetch the parent with ?source=pending. Null for pending rows or when no matching parent exists.

client_order_id

string | null

magic

integer | null

magic_label

string | null

created_at

string | null

filled_at

string | null

fill_price

string | null

cancelled_at

string | null

cancelled_reason

string | null

rejected_reason

string | null

Why the order was rejected, as a stable machine tag — for example INSUFFICIENT_BALANCE, SLIPPAGE_EXCEEDED, BOOK_WALK_FAILED, MARKET_PRICE_UNAVAILABLE or STALE_OR_MISMATCHED_BOOK. Set only on a rejected order; null on every other status.

hold_reason

string | null

Get a single order by ID (polysim-shape row).

curl --request GET \
  --url https://api.polysimulator.com/v1/orders/{order_id} \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.polysimulator.com/v1/orders/{order_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.polysimulator.com/v1/orders/{order_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.polysimulator.com/v1/orders/{order_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.polysimulator.com/v1/orders/{order_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "order_id": 123,
  "source": "pending",
  "market_id": "<string>",
  "side": "<string>",
  "outcome": "<string>",
  "order_type": "<string>",
  "limit_price": "<string>",
  "quantity": "<string>",
  "time_in_force": "<string>",
  "status": "<string>",
  "parent_order_id": 123,
  "client_order_id": "<string>",
  "magic": 123,
  "magic_label": "<string>",
  "created_at": "<string>",
  "filled_at": "<string>",
  "fill_price": "<string>",
  "cancelled_at": "<string>",
  "cancelled_reason": "<string>",
  "rejected_reason": "<string>",
  "hold_reason": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

Overview

Endpoints

Get a single order by ID (polysim-shape row).

Authorizations

Headers

Path Parameters

Query Parameters

Response