polymarket-agent-api

SKILL.md

# 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
```python
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
```python
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
```python
status = httpx.get(f"{BASE_URL}/orders/{order_id}").json()
```

### Cancel Order
```python
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

```python
# 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`