Polymarket Trading API - Usage Guide

What This API Does

Provides HTTP endpoints to trade Polymarket prediction markets:

Query markets with filters
Place buy/sell orders
Manage positions and portfolio
Create price alerts
Webhook integration for automated trading

Base URL

http://YOUR_SERVER:8000/api/v1

Key Rules

| Rule | Value | |------|-------| | Minimum order | $5.00 USD | | Price range | 0.01 - 0.99 | | Token ID source | market["tokens"][0]["token_id"] |

Quick Examples

Get Active Markets

import httpx

BASE_URL = "http://localhost:8000/api/v1"

markets = httpx.get(f"{BASE_URL}/markets/active", params={
    "limit": 10,
    "volume_num_min": 5000
}).json()

# Get token_id
token_id = markets["markets"][0]["tokens"][0]["token_id"]
price = markets["markets"][0]["tokens"][0]["price"]

Place Order

order = httpx.post(f"{BASE_URL}/orders", json={
    "token_id": token_id,
    "side": "BUY",
    "amount": 5.0,  # Minimum $5!
    "price": price,
    "order_type": "GTC"
}).json()

Check Order

status = httpx.get(f"{BASE_URL}/orders/{order_id}").json()

Cancel Order

httpx.delete(f"{BASE_URL}/orders/{order_id}")

Endpoints

Markets

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /markets | List markets with filters | | GET | /markets/active | Active markets only | | GET | /markets/trending | High volume markets | | GET | /markets/ending-soon | Markets ending soon | | GET | /markets/sports | Sports markets | | GET | /markets/{token_id} | Market details | | GET | /markets/{token_id}/price | Current price | | GET | /markets/{token_id}/orderbook | Order book | | GET | /markets/{token_id}/price-history | Price history | | GET | /markets/{token_id}/context | Market context |

Orders

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /orders | Place order | | GET | /orders | List orders | | GET | /orders/{id} | Order details | | GET | /orders/{id}/status | Order status from Polymarket | | DELETE | /orders/{id} | Cancel order | | DELETE | /orders/cancel-all | Cancel all |

Wallet

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /wallet/address | Your address | | GET | /wallet/balance | USDC balance | | GET | /wallet/allowances | Token allowances | | POST | /wallet/approve | Approve tokens |

Portfolio

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /positions | Current positions | | GET | /portfolio | Portfolio summary | | GET | /portfolio/summary | Detailed summary | | GET | /trading/limits | Trading limits | | GET | /trading/daily-stats | Daily trading stats | | POST | /trading/can-trade | Check if can trade |

Events

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /events | List events | | GET | /events/active | Active events | | GET | /events/{id} | Event details |

Alerts

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /alerts | Create alert | | GET | /alerts | List alerts | | DELETE | /alerts/{id} | Delete alert |

Market Import

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /markets/importable | Available markets | | POST | /markets/import | Import market | | GET | /markets/imported | Imported markets | | GET | /markets/imported/{id} | Import details | | POST | /markets/imported/{id}/sync | Sync market |

Webhooks

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /webhook/claw | OpenClaw trade signal | | POST | /webhook/order-status | Order status webhook | | GET | /webhook/health | Webhook health |

Security

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /security/whitelist | IP whitelist | | POST | /security/whitelist/ip | Add IP | | DELETE | /security/whitelist/ip | Remove IP | | GET | /security/whitelist/check/{ip} | Check IP | | POST | /security/api-keys | Add API key | | DELETE | /security/api-keys | Delete API key | | GET | /security/my-ip | Your IP |

Health

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /health | Health check | | GET | /status | API status |

Market Filters

# Filter by volume, dates, status
markets = httpx.get(f"{BASE_URL}/markets", params={
    "active": True,
    "volume_num_min": 10000,
    "end_date_max": "2026-12-31T23:59:59Z",
    "order": "volumeNum",
    "ascending": False,
    "limit": 20
}).json()

Common Errors

| Error | Solution | |-------|----------| | "Size lower than minimum: 5" | Increase amount to $5+ | | "market not found" | Use token_id from market["tokens"] | | "Access restricted" | Use VPN (region blocked) | | "Invalid api key" | Restart server to regenerate credentials |

Required Headers

None required by default. Enable IP whitelist or API key auth in .env if needed.

Notes

Always use market["tokens"][i]["token_id"] for orders
Minimum order amount is $5.00
Prices are 0.01 to 0.99
Restart server after changing .env