PolySimulator

https://github.com/bavariance/polysimulator-docs
Admin
PolySimulator is a virtual prediction market trading API that allows developers to practice building...
Tokens:411,489
Snippets:2,184
Trust Score:7.5
Update:1 week ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- PolySimulator is a prediction market trading simulator, NOT a polynomial math library.
- All API endpoints are under /v1/ prefix and require X-API-Key header authentication.
- Price and balance values are always strings to avoid floating-point precision loss.
- Virtual trading uses real Polymarket CLOB order book data with simulated balances.
- To switch from paper to live trading, change only the API credentials — no code changes.

================
CODE SNIPPETS
================
### Python SDK quick start

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/quickstart.md

Complete and runnable Python SDK snippet that picks a live market and places a trade without needing to fill in IDs. Requires installing the polysimulator package.

```python
# pip install polysimulator
from polysim_sdk import PolySimClient
```

--------------------------------

### Run the trading bot with environment variables

Source: https://github.com/bavariance/polysimulator-docs/blob/main/bots/example-trading-bot.mdx

Sets POLYSIM_API_KEY and POLYSIM_BASE_URL, installs the requests dependency, and runs trading_bot.py.

```bash
# Set environment variables
export POLYSIM_API_KEY="ps_live_..."
export POLYSIM_BASE_URL="https://api.polysimulator.com"

# Install dependencies
pip install requests

# Run
python trading_bot.py
```

--------------------------------

### GET /v1/account/portfolio

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/quickstart.md

Retrieves the account portfolio. All numeric values are returned as strings to prevent floating-point precision loss.

```APIDOC
## GET /v1/account/portfolio

### Description
Retrieves the account portfolio. All numeric values are returned as strings to prevent floating-point precision loss.

### Method
GET

### Endpoint
/v1/account/portfolio

### Response
#### Success Response (200)
- **portfolio** (object) - Portfolio details (fields not specified in source).

#### Response Example
```json
{
  "portfolio": {}
}
```
```

--------------------------------

### Example order response JSON

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/quickstart.md

Sample response from placing a market order. Shows FILLED status, price 0.65, quantity 10, notional 6.50, fee 0.09, slippage_bps 15, and account_balance 9993.41. account_balance is the API wallet balance after the fill, not the dashboard MAIN wallet.

```json
{
  "order_id": 42,
  "status": "FILLED",
  "order_type": "market",
  "side": "BUY",
  "outcome": "Yes",
  "price": "0.65",
  "quantity": "10",
  "notional": "6.50",
  "fee": "0.09",
  "slippage_bps": 15,
  "account_balance": "9993.41"
}
```

--------------------------------

### PolySimClient quickstart: list markets and place order

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/sdk.md

Use the native client for sync and async operations, WebSocket + SSE streaming, pagination iterators, and typed exceptions. Requires the POLYSIM_API_KEY environment variable. The example lists an open market and places a market order, printing the fill status.

```python
from polysim_sdk import PolySimClient   # pip install polysimulator

with PolySimClient() as client:                              # POLYSIM_API_KEY from env
    market = client.list_markets(limit=20, active_only=True)[0]  # an open market
    fill = client.place_order(market_id=market["condition_id"], side="BUY",
                              outcome="Yes", quantity=10, order_type="market", price="0.99")
    print(fill["status"])                                    # FILLED
```

--------------------------------

### Python SDK: Place a market order with PolySimClient

Source: https://github.com/bavariance/polysimulator-docs/blob/main/quickstart.mdx

Complete, runnable Python SDK example that resolves a live market and places a market order. Reads POLYSIM_API_KEY from the environment. Uses active_only=True to skip closed markets, and price as a worst-price limit for slippage protection.

```python
# pip install polysimulator
from polysim_sdk import PolySimClient

with PolySimClient() as client:                 # reads POLYSIM_API_KEY from env
    # active_only=True skips closed markets: an order on one is cancelled, not filled
    market = client.list_markets(limit=20, active_only=True)[0]
    fill = client.place_order(
        market_id=market["condition_id"],
        side="BUY",
        outcome="Yes",
        quantity=10,
        order_type="market",
        price="0.99",            # worst-price cap; "0.99" on a YES = accept any fill
    )
    print(f"filled {fill['status']} @ {fill.get('price')} — order {fill['order_id']}")
```

--------------------------------

### GET /v1/markets

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/quickstart.md

Lists markets available for trading. Use active_only=true to skip closed markets, as orders on closed markets are cancelled rather than filled.

```APIDOC
## GET /v1/markets

### Description
Lists markets available for trading. Use active_only=true to skip closed markets, as orders on closed markets are cancelled rather than filled.

### Method
GET

### Endpoint
/v1/markets

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of markets to return.
- **active_only** (boolean) - Optional - When true, only returns active (non-closed) markets.

### Response
#### Success Response (200)
- **condition_id** (string) - Unique identifier for the market.
- **closed** (boolean) - Indicates whether the market is closed.

#### Response Example
```json
[
  {
    "condition_id": "0x...",
    "closed": false
  }
]
```
```

--------------------------------

### Quickstart with native polysim_sdk client

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/sdk.md

Use PolySimClient as a context manager. It reads POLYSIM_API_KEY from the environment. The example fetches the trading balance, lists active markets, and places a market BUY order on a Yes outcome with a slippage cap price of 0.99. The comment notes that for a Yes market BUY, 0.99 means 'fill at any price' because a Yes share can never cost more than $1.

```python
from polysim_sdk import PolySimClient

with PolySimClient() as client:            # POLYSIM_API_KEY from env
    me = client.me()
    print(me["balance"])                   # your trading balance

    market = client.list_markets(limit=20, active_only=True)[0]  # skip closed markets
    cid = market["condition_id"]

    fill = client.place_order(
        market_id=cid,
        side="BUY",
        outcome="Yes",                     # match the market's own `outcomes` label
        quantity=10,
        order_type="market",
        price="0.99",                      # slippage cap: the worst price you'll accept.
                                           #   For a Yes market BUY, 0.99 is "fill at any price"
                                           #   (a Yes share can never cost more than $1).
    )
    print(f"filled {fill['status']} @ {fill.get('price')}")
```

--------------------------------

### Install PolySimulator Python client

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/introduction.md

Install the official PolySimClient via pip. Required before using the Python trading bot examples.

```bash
pip install polysimulator
```

--------------------------------

### Resolve market_id and place order via JavaScript fetch

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/quickstart.md

JavaScript script using fetch to get an active market and POST an order. Requires POLYSIM_BASE_URL and POLYSIM_API_KEY environment variables. active_only=true skips closed markets; the client-side check is a second guard.

```javascript
const base = process.env.POLYSIM_BASE_URL, key = process.env.POLYSIM_API_KEY;
const h = { "X-API-Key": key, "Content-Type": "application/json" };

// active_only=true skips closed markets (an order on one is cancelled);
// the client-side check below is a second guard.
const markets = await (await fetch(`${base}/v1/markets?limit=20&active_only=true`, { headers: h })).json();
const market = markets.find((m) => !m.closed);
const resp = await fetch(`${base}/v1/orders`, {
  method: "POST", headers: h,
  body: JSON.stringify({
    market_id: market.condition_id, side: "BUY", outcome: "Yes",
    quantity: "10", order_type: "market",
    price: "0.99",  // worst-price limit (slippage cap)
  }),
});
console.log(await resp.json());
```

--------------------------------

### Verbose body opt-in example

Source: https://github.com/bavariance/polysimulator-docs/blob/main/authentication.mdx

Example JSON body when X-Polysim-Verbose: true is sent, adding details and request_id fields.

```json
{"error": "INVALID_KEY", "message": "Invalid API key",
   "details": null, "request_id": "a1b2c3d4-..."}
```

--------------------------------

### Install py-clob-client SDK (pip)

Source: https://github.com/bavariance/polysimulator-docs/blob/main/llms.txt

One-time install of Polymarket's official Python SDK required before deriving API credentials or placing orders.

```bash
pip install py-clob-client
```

--------------------------------

### Batch prices response example

Source: https://github.com/bavariance/polysimulator-docs/blob/main/market-data/batch-prices.mdx

Example JSON response from the batch prices endpoint. Markets with unavailable prices return only the condition_id field.

```json
[
  {
    "condition_id": "0x1a2b3c...",
    "buy": "0.65",
    "sell": "0.35",
    "outcomes": [
      {"label": "Yes", "price": "0.65", "token_id": "71321..."},
      {"label": "No", "price": "0.35", "token_id": "71322..."}
    ]
  },
  {
    "condition_id": "0x4d5e6f..."
  }
]
```

--------------------------------

### Python example: fetch prices for open positions

Source: https://github.com/bavariance/polysimulator-docs/blob/main/market-data/batch-prices.mdx

Python script that fetches all open positions and retrieves their batch prices. Demonstrates checking for the presence of 'buy' before using it.

```python
import requests

API_KEY = "ps_live_..."
BASE = "https://api.polysimulator.com"
headers = {"X-API-Key": API_KEY}

# Fetch prices for all open positions
positions = requests.get(
    f"{BASE}/v1/account/positions",
    headers=headers,
    params={"status": "OPEN"},
).json()

market_ids = [p["market_id"] for p in positions]

prices = requests.post(
    f"{BASE}/v1/prices/batch",
    headers=headers,
    json={"market_ids": market_ids},
).json()

for p in prices:
    if p.get("buy") is not None:
        print(f"{p['condition_id'][:16]}: Yes={p['buy']}, No={p['sell']}")
    else:
        print(f"{p['condition_id'][:16]}: price unavailable")
```

--------------------------------

### 503 DEADLINE_OVERSHOT_BUT_PERSISTED response example

Source: https://github.com/bavariance/polysimulator-docs/blob/main/bots/example-trading-bot.mdx

Shows the HTTP 503 response with Retry-After header and JSON body containing error DEADLINE_OVERSHOT_BUT_PERSISTED and order_id. Do NOT retry; instead read X-Polysim-Order-Id or body.order_id and poll GET /v1/orders/{id} until terminal status.

```http
HTTP/1.1 503 Service Unavailable
Retry-After: 1
X-Polysim-Order-Id: 42
Content-Type: application/json

{
  "error": "DEADLINE_OVERSHOT_BUT_PERSISTED",
  "error_code": "PERSISTED_DO_NOT_RETRY",
  "message": "...",
  "order_id": 42
}
```

--------------------------------

### GET /v1/orders/{id}

Source: https://github.com/bavariance/polysimulator-docs/blob/main/bots/example-trading-bot.mdx

Retrieve the status of an order by its ID. Used to poll after a 503 response to confirm the order's final state.

```APIDOC
## GET /v1/orders/{id}

### Description
Retrieve the status of an order by its ID. Used to poll after a 503 response to confirm the order's final state.

### Method
GET

### Endpoint
/v1/orders/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The order ID.

### Response
#### Success Response (200)
- **status** (string) - Order status: `FILLED`, `CANCELLED`, `REJECTED`, `EXPIRED`, or `PENDING`.

### Notes
- Poll until status is terminal (`FILLED`, `CANCELLED`, `REJECTED`, `EXPIRED`). `PENDING` means the order is still resting.
```

--------------------------------

### Place a market order with PolySimClient

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/quickstart.md

Uses the Python client to list active markets and place a market order. Reads POLYSIM_API_KEY from the environment. active_only=True skips closed markets; an order on one is cancelled, not filled. price is a worst-price cap; "0.99" on a YES accepts any fill.

```python
with PolySimClient() as client:                 # reads POLYSIM_API_KEY from env
    # active_only=True skips closed markets: an order on one is cancelled, not filled
    market = client.list_markets(limit=20, active_only=True)[0]
    fill = client.place_order(
        market_id=market["condition_id"],
        side="BUY",
        outcome="Yes",
        quantity=10,
        order_type="market",
        price="0.99",            # worst-price cap; "0.99" on a YES = accept any fill
    )
    print(f"filled {fill['status']} @ {fill.get('price')} — order {fill['order_id']}")
```

--------------------------------

### GET /v1/account/balance

Source: https://github.com/bavariance/polysimulator-docs/blob/main/account/wallets.mdx

Retrieves the current API wallet balance for the authenticated API key. The balance reflects the tier's starting balance minus any order debits.

```APIDOC
## GET /v1/account/balance

### Description
Retrieves the current API wallet balance for the authenticated API key. The balance reflects the tier's starting balance minus any order debits.

### Method
GET

### Endpoint
/v1/account/balance

### Parameters
#### Headers
- **X-API-Key** (string) - Required - API key for authentication

### Request Example
```bash
curl -H "X-API-Key: $POLYSIM_API_KEY" \
  https://api.polysimulator.com/v1/account/balance
```

### Response
#### Success Response (200)
- **balance** (string) - Current API wallet balance
- **starting_balance** (string) - Tier's starting balance

#### Response Example
```json
{"balance": "94.10", "starting_balance": "100.00"}
```
```

--------------------------------

### GET /v1/account/balance

Source: https://github.com/bavariance/polysimulator-docs/blob/main/account/balance.mdx

Endpoint to check your API wallet balance, P&L, and starting capital. Returns JSON with balance, currency, starting_balance, unrealized_pnl, and total_value.

```http
GET /v1/account/balance
```

--------------------------------

### Resolve market_id and place order via Python requests

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/quickstart.md

Python script using requests to fetch an active market and POST an order. Requires POLYSIM_BASE_URL and POLYSIM_API_KEY environment variables. active_only=true skips closed markets; the client-side check is a second guard.

```python
import requests, os

base, key = os.environ["POLYSIM_BASE_URL"], os.environ["POLYSIM_API_KEY"]
h = {"X-API-Key": key, "Content-Type": "application/json"}

# resolve a live market, then trade
# active_only=true skips closed markets (an order on one is cancelled);
# the client-side check below is a second guard.
markets = requests.get(f"{base}/v1/markets?limit=20&active_only=true", headers=h).json()
market_id = next(m for m in markets if not m["closed"])["condition_id"]
resp = requests.post(f"{base}/v1/orders", headers=h, json={
    "market_id": market_id, "side": "BUY", "outcome": "Yes",
    "quantity": "10", "order_type": "market",
    "price": "0.99",  # worst-price limit (slippage cap)
})
print(resp.json())
```

--------------------------------

### GET /v1/account/balance

Source: https://github.com/bavariance/polysimulator-docs/blob/main/llms-full.txt

Returns the current API wallet balance, P&L metrics, and starting capital. API-authenticated requests always read from the API wallet.

```APIDOC
## [GET] /v1/account/balance

### Description
Returns the current API wallet balance, P&L metrics, and starting capital. API-authenticated requests always read from the API wallet.

### Method
GET

### Endpoint
/v1/account/balance

### Authentication
Accepts either an API key (`X-API-Key: `, or the PM-compat `POLY_API_KEY` / `Authorization: Bearer ps_live_...` aliases) or a Supabase Bearer JWT (`Authorization: Bearer `). The balance returned is always the API wallet regardless of which scheme you use.

### Request Example
```bash
curl -H "X-API-Key: $API_KEY" \
  https://api.polysimulator.com/v1/account/balance
```

### Response
#### Success Response (200)
- **balance** (string) - Current API wallet cash balance (available for trading)
- **currency** (string) - Always `USD`
- **starting_balance** (string) - Initial API wallet capital — your tier baseline (Pro: `10000.00`; Pro+: `25000.00`). Falls back to `10000.00` when no API wallet baseline is set.
- **unrealized_pnl** (string) - Total account P&L: `total_value − starting_balance`. Despite the name, this is total equity vs starting capital (cash + open-position mark-to-market), not the open-position MTM delta alone — it equals true unrealized P&L only when `balance == starting_balance`.
- **total_value** (string) - Cash balance + market value of open API positions

#### Response Example
```json
{
  "balance": "9745.20",
  "currency": "USD",
  "starting_balance": "10000.00",
  "unrealized_pnl": "-242.50000000000000000",
  "total_value": "9757.50000000000000000"
}
```

### Errors
All errors return a JSON body of the shape `{"error": "<CODE>", "message": ""}`.

| Status | `error` code | When |
|--------|--------------|------|
| 401 | `MISSING_AUTH` | No `X-API-Key` and no `Authorization` header supplied |
| 401 | `INVALID_KEY` | API key (or Bearer-wrapped key) is unknown, deactivated, or expired |
| 404 | `ACCOUNT_NOT_FOUND` | Authenticated user has no account record |
```

--------------------------------

### Check market data coverage with curl

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/quickstart.md

Verifies that book coverage for the requested window meets the minimum (80% by default) before submitting a backtest. A backtest is refused outright if coverage is below the minimum, and the refusal names the percentage. The response includes `confidence` and `missing_periods` to identify thin hours.

```bash
curl -H "X-API-Key: $POLYSIM_API_KEY" \
  "$POLYSIM_BASE_URL/v1/simulation/coverage?condition_id=$MARKET_ID&start=2026-09-07T12:00:00Z&end=2026-09-07T18:00:00Z"
```

--------------------------------

### GET /v1/account/balance

Source: https://github.com/bavariance/polysimulator-docs/blob/main/account/balance.mdx

Retrieves the current API wallet balance, P&L metrics, and starting capital. This endpoint accepts either an API key or a Supabase Bearer JWT for authentication.

```APIDOC
## [GET] /v1/account/balance

### Description
Returns your current API wallet balance, P&L metrics, and starting capital. API-authenticated requests always read from the API wallet.

### Method
GET

### Endpoint
/v1/account/balance

### Authentication
Accepts either an API key (`X-API-Key: <key>`, or the PM-compat `POLY_API_KEY` / `Authorization: Bearer ps_live_...` aliases) or a Supabase Bearer JWT (`Authorization: Bearer <jwt>`). The balance returned is always the API wallet regardless of which scheme you use.

### Request Example
```bash
curl -H "X-API-Key: $API_KEY" \
  https://api.polysimulator.com/v1/account/balance
```

### Response
#### Success Response (200)
- **balance** (string) - Current API wallet cash balance (available for trading)
- **currency** (string) - Always `USD`
- **starting_balance** (string) - Initial API wallet capital — your tier baseline (Pro: `10000.00`; Pro+: `25000.00`). Falls back to `10000.00` when no API wallet baseline is set.
- **unrealized_pnl** (string) - Total account P&L: `total_value − starting_balance`. Despite the name, this is total equity vs starting capital (cash + open-position mark-to-market), not the open-position MTM delta alone — it equals true unrealized P&L only when `balance == starting_balance`.
- **total_value** (string) - Cash balance + market value of open API positions

#### Response Example
```json
{
  "balance": "9745.20",
  "currency": "USD",
  "starting_balance": "10000.00",
  "unrealized_pnl": "-242.50000000000000000",
  "total_value": "9757.50000000000000000"
}
```

### Errors
All errors return a JSON body of the shape `{"error": "<CODE>", "message": "<human-readable>"}`.

| Status | `error` code | When |
|--------|--------------|------|
| 401 | `MISSING_AUTH` | No `X-API-Key` and no `Authorization` header supplied |
| 401 | `INVALID_KEY` | API key (or Bearer-wrapped key) is unknown, deactivated, or expired |
| 404 | `ACCOUNT_NOT_FOUND` | Authenticated user has no account record |
```

--------------------------------

### Submit a backtest run with curl and parse job_id

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/quickstart.md

Creates a backtest request body in `backtest.json` and POSTs it to the backtests endpoint, extracting the `job_id` with Python. The window 12:00→18:00 is 7 market-hours (not 6) because both endpoints count. Each successful POST charges the window's market-hours and one job against the monthly count; re-running this block starts a second backtest. The run is charged at submission and refunded if it fails.

```bash
cat > backtest.json <<JSON
{
    "condition_ids": ["$MARKET_ID"],
    "start": "2026-09-07T12:00:00Z",
    "end":   "2026-09-07T18:00:00Z",
    "initial_bankroll": "1000",
    "strategy": {
      "spec_version": "1",
      "side": "BUY",
      "outcome": "Yes",
      "size": "10",
      "fill_model": "depth_walk",
      "entry": [{"field": "price", "op": "lte", "value": "0.40"}],
      "exit":  [{"field": "price", "op": "gte", "value": "0.60"}]
    }
}
JSON

JOB_ID=$(curl -s -X POST $POLYSIM_BASE_URL/v1/simulation/backtests \
  -H "X-API-Key: $POLYSIM_API_KEY" -H "Content-Type: application/json" \
  -d @backtest.json | python3 -c 'import sys,json;print(json.load(sys.stdin)["job_id"])')
echo "$JOB_ID"
```

--------------------------------

### Check API health with curl

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/quickstart.md

Sends a GET request to the /v1/health endpoint using the API key and base URL environment variables. The expected response is a JSON object with status, timestamp, and version.

```bash
curl -H "X-API-Key: $POLYSIM_API_KEY" \
     $POLYSIM_BASE_URL/v1/health
```

```json
{"status": "ok", "timestamp": "2026-03-02T12:00:00Z", "version": "1.0.0"}
```

--------------------------------

### Authenticate with X-API-Key header

Source: https://github.com/bavariance/polysimulator-docs/blob/main/api-reference/overview.mdx

Use this curl command to call an endpoint that requires an X-API-Key header. Replace the placeholder key with your actual API key. The example shows a GET request to the account balance endpoint.

```bash
curl https://api.polysimulator.com/v1/account/balance \
  -H "X-API-Key: ps_live_..."
```

--------------------------------

### Configure POLYSIM_DATALAKE_ROOT or POLYSIM_DATALAKE_URI

Source: https://github.com/bavariance/polysimulator-docs/blob/main/market-data/datalake-schema.mdx

Sets up the local mount or object-store endpoint required by the reader recipes. The archive is private; never commit BACKTEST_RO_*, INGEST_RW_*, or R2 access keys. Leave the URI line commented unless you already hold an endpoint configuration.

```bash
# Local mount you created (recommended)
export POLYSIM_DATALAKE_ROOT="$HOME/data/polysim-datalake"

# Or an endpoint you already have — never a committed secret
# export POLYSIM_DATALAKE_URI="s3://your-bucket/v3/orderbook/polymarket/"
# Point your S3-compatible client at an endpoint you already hold.
```

--------------------------------

### POST /v1/orders

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/quickstart.md

Places a new order on a market. Requires a market_id, side, outcome, quantity, order_type, and price (as a worst-price limit for market orders).

```APIDOC
## POST /v1/orders

### Description
Places a new order on a market. Requires a market_id, side, outcome, quantity, order_type, and price (as a worst-price limit for market orders).

### Method
POST

### Endpoint
/v1/orders

### Parameters
#### Request Body
- **market_id** (string) - Required - The condition_id of the market.
- **side** (string) - Required - Order side: "BUY" or "SELL".
- **outcome** (string) - Required - Human-readable outcome label (e.g., "Yes", "No", or custom label).
- **quantity** (string) - Required - Quantity as a string (e.g., "10").
- **order_type** (string) - Required - Order type: "market" or "limit".
- **price** (string) - Required - Worst-price limit for market orders (e.g., "0.99" for a BUY on YES).

### Request Example
```json
{
  "market_id": "0x...",
  "side": "BUY",
  "outcome": "Yes",
  "quantity": "10",
  "order_type": "market",
  "price": "0.99"
}
```

### Response
#### Success Response (200)
- **order_id** (integer) - Unique order identifier.
- **status** (string) - Order status (e.g., "FILLED").
- **order_type** (string) - Order type.
- **side** (string) - Order side.
- **outcome** (string) - Outcome label.
- **price** (string) - Fill price.
- **quantity** (string) - Filled quantity.
- **notional** (string) - Notional value.
- **fee** (string) - Trading fee.
- **slippage_bps** (integer) - Slippage in basis points.
- **account_balance** (string) - API wallet balance after fill.

#### Response Example
```json
{
  "order_id": 42,
  "status": "FILLED",
  "order_type": "market",
  "side": "BUY",
  "outcome": "Yes",
  "price": "0.65",
  "quantity": "10",
  "notional": "6.50",
  "fee": "0.09",
  "slippage_bps": 15,
  "account_balance": "9993.41"
}
```
```

--------------------------------

### Python charting example for equity curve

Source: https://github.com/bavariance/polysimulator-docs/blob/main/account/equity-curve.mdx

Plot the equity curve using matplotlib. Handles Python < 3.11 datetime parsing by replacing 'Z' with '+00:00'. The baseline is the API wallet starting balance, not the UI MAIN wallet.

```python
import requests, os
import matplotlib.pyplot as plt
from datetime import datetime

BASE_URL = os.environ["POLYSIM_BASE_URL"]
headers = {"X-API-Key": os.environ["POLYSIM_API_KEY"]}

equity = requests.get(
    f"{BASE_URL}/v1/account/equity",
    headers=headers,
    params={"days": 30},  # 30 days
).json()

# On Python < 3.11, datetime.fromisoformat() rejects the trailing "Z" —
# swap it for "+00:00" so this parses on 3.10+ (the SDK's floor).
times = [
    datetime.fromisoformat(e["timestamp"].replace("Z", "+00:00"))
    for e in equity
]
values = [float(e["total_value"]) for e in equity]

plt.figure(figsize=(12, 6))
plt.plot(times, values)
# Starting balance = your API-wallet baseline, NOT the $1,000 UI MAIN
# wallet: Free = 100 (keys issued on/after 2026-09-05), Pro = 10_000,
# Pro+ = 25_000. Set it to your tier's baseline so the reference line
# is meaningful.
API_WALLET_BASELINE = 10_000  # Pro; use 25_000 on Pro+
plt.axhline(y=API_WALLET_BASELINE, color="gray", linestyle="--", label="Starting balance")
plt.title("Portfolio Equity Curve")
plt.ylabel("Portfolio Value ($)")
plt.legend()
plt.show()
```

--------------------------------

### setup_gasless_wallet

Source: https://github.com/bavariance/polysimulator-docs/blob/main/concepts/py-sdk-compatibility.mdx

Sets up a gasless wallet in paper mode. The call is accepted and validated but does not settle on-chain or mutate any paper state.

```APIDOC
## setup_gasless_wallet

### Description
Sets up a gasless wallet in paper mode. The call is accepted and validated but does not settle on-chain or mutate any paper state.

### Method
SDK Method

### Signature
`setup_gasless_wallet(*args, **kwargs)`

### Parameters
- Accepts py-sdk's exact signatures.

### Returns
- A paper transaction handle whose `.wait()` returns instantly with a valid-format placeholder `TransactionOutcome` (`0x` + 64 hex hash, `transaction_id=None`).

### Notes
- No on-chain settlement or paper state mutation occurs.
```

--------------------------------

### List markets with curl

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/quickstart.md

Fetches actively traded markets with live prices from Polymarket by calling /v1/markets with a limit of 5. Uses the API key and base URL environment variables.

```bash
curl -H "X-API-Key: $POLYSIM_API_KEY" \
     "$POLYSIM_BASE_URL/v1/markets?limit=5"
```

--------------------------------

### Fetch account portfolio via cURL

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/quickstart.md

cURL command to retrieve the account portfolio. Requires POLYSIM_API_KEY and POLYSIM_BASE_URL environment variables. All numeric values in the response are strings to prevent floating-point precision loss.

```bash
curl -H "X-API-Key: $POLYSIM_API_KEY" \
     $POLYSIM_BASE_URL/v1/account/portfolio
```

--------------------------------

### Generate stable idempotency key with uuid5 and second bucket

Source: https://github.com/bavariance/polysimulator-docs/blob/main/bots/example-trading-bot.mdx

Creates a deterministic idempotency key using uuid5 over the order tuple plus a second bucket, so retries within the same second collapse to the same key while independent orders a second apart get different keys. The key is sent in the Idempotency-Key header.

```python
# Stable across retries: uuid5 over the order tuple + a SECOND
# bucket. Two calls within the same second with the same
# parameters get the SAME key → server dedups → no double-fill.
# Two genuinely independent orders >= 1 second apart get DIFFERENT
# keys (a coarser minute-bucket would wrongly collapse rapid-fire
# orders into one).
second_bucket = int(time.time())
seed = f"{market_id}|{side}|{outcome}|{quantity}|{price}|{second_bucket}"
idempotency_key = f"bot-{uuid.uuid5(uuid.NAMESPACE_OID, seed)}"
"Idempotency-Key": idempotency_key
```

--------------------------------

### Resolve market_id and place order via cURL

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/quickstart.md

Bash script using cURL and jq to fetch an active market and POST an order. Requires POLYSIM_API_KEY and POLYSIM_BASE_URL environment variables. active_only=true skips closed markets; the jq select is a second guard.

```bash
# 1. grab a TRADEABLE market_id (jq)
#    Without active_only=true, /v1/markets also returns closed markets,
#    and an order against one is cancelled rather than filled. The jq
#    select is a second guard.
MARKET_ID=$(curl -s -H "X-API-Key: $POLYSIM_API_KEY" \
  "$POLYSIM_BASE_URL/v1/markets?limit=20&active_only=true" \
  | jq -r '[.[] | select(.closed == false)][0].condition_id')

# 2. place the trade
curl -X POST $POLYSIM_BASE_URL/v1/orders \
  -H "X-API-Key: $POLYSIM_API_KEY" -H "Content-Type: application/json" \
  -d "{\"market_id\":\"$MARKET_ID\",\"side\":\"BUY\",\"outcome\":\"Yes\",\"quantity\":\"10\",\"order_type\":\"market\",\"price\":\"0.99\"}"
```

--------------------------------

### GET /v1/account/portfolio

Source: https://github.com/bavariance/polysimulator-docs/blob/main/llms.txt

Get aggregate portfolio snapshot. Supports wallet_id parameter.

```APIDOC
## [GET] /v1/account/portfolio

### Description
Get aggregate portfolio snapshot. Supports wallet_id parameter.

### Method
GET

### Endpoint
/v1/account/portfolio

### Parameters
#### Query Parameters
- **wallet_id** (string) - Optional - Wallet ID, 'all', or 'api'.

### Request Example
GET /v1/account/portfolio?wallet_id=api

### Response
#### Success Response (200)
- **data** (object) - Portfolio snapshot.

#### Response Example
{
  "data": {}
}
```

--------------------------------

### Check simulation quota with curl

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/quickstart.md

Checks remaining backtest quota before running a large backtest. Requires the plan's `analytics.backtesting` entitlement and an `X-API-Key` header. Backtests are metered in market-hours (window length × number of markets), so check here first to avoid hitting the cap mid-request.

```bash
curl -H "X-API-Key: $POLYSIM_API_KEY" \
  $POLYSIM_BASE_URL/v1/simulation/quota
```

--------------------------------

### Bootstrap API key with curl

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/quickstart.md

Creates the first API key via POST /v1/keys/bootstrap when a browser is unavailable, using a Supabase JWT. The response includes the raw key shown only once; save it immediately. A free key issued on or after 2026-09-05 has read and trade permissions, while earlier keys are read-only.

```bash
# SUPABASE_JWT comes from a programmatic Supabase sign-in.
# Most users skip this step entirely — the /api-keys dashboard
# is the recommended path.
curl -X POST https://api.polysimulator.com/v1/keys/bootstrap \
  -H "Authorization: Bearer $SUPABASE_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-first-bot"}'
```

```json
{
  "id": 1,
  "raw_key": "ps_live_kJ9mNx2pQrStUvWxYz01Ab3CdEfGhI4j...",
  "key_prefix": "ps_live_kJ9mNx2p",
  "name": "my-first-bot",
  "rate_limit_tier": "free",
  "permissions": ["read", "trade"],
  "created_at": "2026-09-12T12:00:00Z"
}
```

--------------------------------

### SSE tick_size_change frame example

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/websockets/price-feed.md

Shown for reference only — this is the SSE /prices/stream shape, not a /v1/ws/prices frame. The backend broadcasts tick_size_change frames only to SSE subscribers; the JWT /v1/ws/prices feed emits type:"price" frames only and has no tick-change path. For tick changes on a WS bot, poll GET /v1/tick-size/{token_id} or consume the SSE feed alongside your WS price feed.

```json
{
  "event": "tick_size_change",
  "data": {
    "type": "tick_size_change",
    "market": "0xabc123...",
    "asset_id": "71321...",
    "tick_size": 0.001,
    "old_tick_size": 0.01,
    "side": "BUY",
    "ts_ms": 1715518800123
  }
}
```

--------------------------------

### GET /v1/account/equity

Source: https://github.com/bavariance/polysimulator-docs/blob/main/llms.txt

Get hourly equity snapshots. Supports days and wallet_id parameters.

```APIDOC
## [GET] /v1/account/equity

### Description
Get hourly equity snapshots. Supports days and wallet_id parameters.

### Method
GET

### Endpoint
/v1/account/equity

### Parameters
#### Query Parameters
- **days** (integer) - Optional - Number of days of equity data.
- **wallet_id** (string) - Optional - Wallet ID, 'all', or 'api'.

### Request Example
GET /v1/account/equity?days=7

### Response
#### Success Response (200)
- **data** (array) - Array of equity snapshots.

#### Response Example
{
  "data": []
}
```

--------------------------------

### setup_trading_approvals

Source: https://github.com/bavariance/polysimulator-docs/blob/main/concepts/py-sdk-compatibility.mdx

Sets up trading approvals in paper mode. The call is accepted and validated but does not settle on-chain or mutate any paper state.

```APIDOC
## setup_trading_approvals

### Description
Sets up trading approvals in paper mode. The call is accepted and validated but does not settle on-chain or mutate any paper state.

### Method
SDK Method

### Signature
`setup_trading_approvals(*args, **kwargs)`

### Parameters
- Accepts py-sdk's exact signatures.

### Returns
- A paper transaction handle whose `.wait()` returns instantly with a valid-format placeholder `TransactionOutcome` (`0x` + 64 hex hash, `transaction_id=None`).

### Notes
- No on-chain settlement or paper state mutation occurs.
```

--------------------------------

### Fetch hot markets with /v1/markets

Source: https://github.com/bavariance/polysimulator-docs/blob/main/quickstart.mdx

Retrieves up to five actively traded markets with live prices from Polymarket. Uses the API key and base URL environment variables.

```bash
curl -H "X-API-Key: $POLYSIM_API_KEY" \
         "$POLYSIM_BASE_URL/v1/markets?limit=5"
```

--------------------------------

### GET /v1/account/balance

Source: https://github.com/bavariance/polysimulator-docs/blob/main/llms.txt

Get account balance, PnL, and unrealized PnL for the API wallet.

```APIDOC
## [GET] /v1/account/balance

### Description
Get account balance, PnL, and unrealized PnL for the API wallet.

### Method
GET

### Endpoint
/v1/account/balance

### Parameters
None

### Request Example
GET /v1/account/balance

### Response
#### Success Response (200)
- **balance** (number) - Account balance.
- **pnl** (number) - Realized PnL.
- **unrealized_pnl** (number) - Unrealized PnL.

#### Response Example
{
  "balance": 1000,
  "pnl": 50,
  "unrealized_pnl": 10
}
```

--------------------------------

### GET /v1/account/positions

Source: https://github.com/bavariance/polysimulator-docs/blob/main/llms.txt

Get open or closed positions. Supports filtering by status, wallet_id, and envelope.

```APIDOC
## [GET] /v1/account/positions

### Description
Get open or closed positions. Supports filtering by status, wallet_id, and envelope.

### Method
GET

### Endpoint
/v1/account/positions

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter by position status (open/closed).
- **wallet_id** (string) - Optional - Wallet ID, 'all', or 'api'.
- **envelope** (boolean) - Optional - Whether to wrap response in envelope.

### Request Example
GET /v1/account/positions?status=open

### Response
#### Success Response (200)
- **data** (array) - Array of positions.

#### Response Example
{
  "data": []
}
```

--------------------------------

### Set API key and base URL environment variables

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/quickstart.md

Exports the API key and base URL as environment variables for use in subsequent curl commands. The key is the ps_live_ value copied from the dashboard.

```bash
export POLYSIM_API_KEY="ps_live_abc123..."
export POLYSIM_BASE_URL="https://api.polysimulator.com"
```

--------------------------------

### AsyncSecureClient constructor and lifecycle

Source: https://github.com/bavariance/polysimulator-docs/blob/main/sdk-polymarket.mdx

Construct the async client with AsyncSecureClient(api_key=…) or await AsyncSecureClient.create(api_key=…), and use async with for lifecycle management.

```APIDOC
## [CONSTRUCTOR] AsyncSecureClient

### Description
Construct the async client with AsyncSecureClient(api_key=…) or await AsyncSecureClient.create(api_key=…), and use async with for lifecycle management.

### Method
CONSTRUCTOR

### Endpoint
`AsyncSecureClient(api_key=..., host=...)` or `await AsyncSecureClient.create(api_key=...)`

### Parameters
#### Query Parameters
- **api_key** (string) - Required - API key for authentication.
- **host** (string) - Optional - Base URL for the API. Defaults to `https://api.polysimulator.com`.

### Request Example
```python
async with AsyncSecureClient(api_key="ps_live_…", host="https://api.polysimulator.com") as client:
    # use client
```

### Response
#### Success Response (200)
- **client** (AsyncSecureClient) - The async client instance.
```

--------------------------------

### Async client usage with await

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/sdk.md

Async is the same API with await. Use AsyncPolySimClient as an async context manager and call client.me() with await. The example prints the trading balance.

```python
import asyncio
from polysim_sdk import AsyncPolySimClient

async def main():
    async with AsyncPolySimClient() as client:
        print((await client.me())["balance"])

asyncio.run(main())
```

--------------------------------

### GET /v1/account/history

Source: https://github.com/bavariance/polysimulator-docs/blob/main/llms.txt

Get filled order history. Supports filtering by market_id, side, limit, offset, wallet_id, and envelope.

```APIDOC
## [GET] /v1/account/history

### Description
Get filled order history. Supports filtering by market_id, side, limit, offset, wallet_id, and envelope.

### Method
GET

### Endpoint
/v1/account/history

### Parameters
#### Query Parameters
- **market_id** (string) - Optional - Filter by market ID.
- **side** (string) - Optional - Filter by side.
- **limit** (integer) - Optional - Maximum number of records.
- **offset** (integer) - Optional - Number of records to skip.
- **wallet_id** (string) - Optional - Wallet ID, 'all', or 'api'.
- **envelope** (boolean) - Optional - Whether to wrap response in envelope.

### Request Example
GET /v1/account/history?limit=10

### Response
#### Success Response (200)
- **data** (array) - Array of filled orders.

#### Response Example
{
  "data": []
}
```

--------------------------------

### POST /v1/keys/bootstrap

Source: https://github.com/bavariance/polysimulator-docs/blob/main/llms.txt

Creates a new API key during first-time setup. Requires a Supabase access token in the Authorization header. Returns a raw key that is shown only once.

```APIDOC
## [POST] /v1/keys/bootstrap

### Description
Creates a new API key during first-time setup. Requires a Supabase access token in the Authorization header. Returns a raw key that is shown only once.

### Method
POST

### Endpoint
/v1/keys/bootstrap

### Parameters
#### Request Body
- **name** (string) - Optional - Name for the key. Send `{}` for defaults.

### Request Example
{
  "name": "my-bot"
}

### Response
#### Success Response (200)
- **id** (integer) - Key ID
- **raw_key** (string) - The raw API key, shown only once
- **key_prefix** (string) - Prefix of the key
- **rate_limit_tier** (string) - Rate limit tier (e.g., "free")
- **permissions** (array of strings) - Permissions granted (e.g., ["read","trade"])
- **created_at** (string) - Creation timestamp
- **name** (string) - Key name

#### Response Example
{
  "id": 1,
  "raw_key": "ps_live_abc123...",
  "key_prefix": "ps_live_abc1",
  "rate_limit_tier": "free",
  "permissions": ["read"],
  "created_at": "2025-01-01T00:00:00Z",
  "name": "my-bot"
}
```

--------------------------------

### Worked fee example

Source: https://github.com/bavariance/polysimulator-docs/blob/main/md/trading/fees.md

Worked example of the fee formula for a 10-share BUY at $0.65 on a crypto market, yielding a fee of 0.15925 USD.

```text
fee = 10 × 0.07 × 0.65 × 0.35 = 0.15925 USD
```

--------------------------------

### GET /v1/midpoint?token_id=

Source: https://github.com/bavariance/polysimulator-docs/blob/main/llms-full.txt

Returns the midpoint price for a given token. Mirrors Polymarket's GET /midpoint endpoint.

```APIDOC
## GET /v1/midpoint?token_id=

### Description
Returns the midpoint price for a given token. Mirrors Polymarket's GET /midpoint endpoint.

### Method
GET

### Endpoint
/v1/midpoint?token_id=

### Parameters
#### Query Parameters
- **token_id** (string) - Required - The token identifier.

```
Tokens:
Raw