polymarket-api1

Provides REST API endpoints to query markets, place/cancel orders, manage portfolio, create alerts, and automate Polymarket trading.

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

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