Engineering patterns we recommend when shipping a Predexon integration. None of this is required to make your first call work — it’s what separates a working prototype from a production system.Documentation Index
Fetch the complete documentation index at: https://docs.predexon.com/llms.txt
Use this file to discover all available pages before exploring further.
Authentication
Store the key as an env var, not in code
Store the key as an env var, not in code
Use one key per environment (dev / staging / prod)
Use one key per environment (dev / staging / prod)
Per-end-user keys (account-per-user platforms)
Per-end-user keys (account-per-user platforms)
Pagination
Most list endpoints support one of two patterns. Use the right one for your scale.| Pattern | Endpoints | When to use |
|---|---|---|
| Offset-based | Default on markets, trades, wallet, most analytics | One-off queries, small/medium result sets, when you need a known total |
| Cursor-based (keyset) | markets/keyset, events/keyset and a few others | Large backfills, real-time tailing, when you need consistent ordering across pages |
Retries and exponential backoff
Retry 5xx errors with exponential backoff. Never retry 4xx — those are your bug, not ours.| Status | Retry? | Notes |
|---|---|---|
429 | Yes — with backoff | We send Retry-After; the example above respects it via respect_retry_after_header=True |
500/502/503/504 | Yes — with backoff | Transient. Usually self-heals in <30s |
409 | Maybe — once | Concurrent modification (fee policy). Single retry, then surface to user |
400/401/403/404 | No | Fix your request |
Rate limit handling
You’ll hit429 long before any other failure mode. Cheap defenses, in order of effort:
Cache aggressively
Batch where the API supports it
/v2/polymarket/wallets/profiles accepts up to 20 wallets per call. /v2/polymarket/wallets/filter lets you filter server-side instead of pulling everything and filtering locally. Use them.Stream instead of poll for live data
/v2/polymarket/trades every second, switch to the WebSocket trades channel. Streaming consumes WebSocket subs (cheap) instead of REST quota (expensive).Upgrade tier or talk to us
WebSocket: reconnect and state rebuild
WebSockets disconnect. Your client must handle it cleanly without losing state.- Re-pull REST state on every reconnect — bridges any events you missed during the disconnect.
- Handle
resyncevents from the server — it tells you “rebuild state, more snapshots coming.” Same recovery as a hard reconnect. - Exponential backoff on reconnect attempts, capped at 60s. Don’t hammer the server during an outage.
Idempotency
Trading API order placements aren’t idempotent by default — calling Place Order twice with the same body creates two orders. For at-most-once semantics:clientId, it returns the existing order instead of creating a duplicate. Critical for any retry logic on the Trading API.
Testing strategy
Don't mock Predexon endpoints in unit tests
Don't mock Predexon endpoints in unit tests
Use low-volume markets for trading integration tests
Use low-volume markets for trading integration tests
Replay historical WebSocket events for handler tests
Replay historical WebSocket events for handler tests
Snapshot endpoint responses
Snapshot endpoint responses
Observability
Things you’ll want to instrument from day one:| Metric | Why |
|---|---|
| Request latency p50/p95/p99 per endpoint | Catches degradation before users do |
| Error rate per endpoint | Pinpoints which endpoint broke, not “the API broke” |
429 count per minute | Tells you when to upgrade tier |
| WebSocket disconnect frequency + reconnect duration | If reconnect takes >5s, that’s user-visible |
| Trade placement → confirmation latency | The Trading API number that matters most |
clientId collision rate (should be 0) | Indicates retry storms |
GET /health on every base URL returns {"status": "healthy"} — use it as a synthetic check.
Common gotchas
Timestamp units differ by endpoint
Timestamp units differ by endpoint
Cents vs decimals
Cents vs decimals
condition_id vs token_id
condition_id vs token_id
condition_id and N token_ids (one per outcome). Candles by condition give you market-level OHLCV; candles by token give you per-outcome.Aggregated vs per-venue positions
Aggregated vs per-venue positions
GET /api/accounts/{id}/positions returns per-venue rows by default. Pass ?aggregated=true to collapse cross-venue positions into one row per canonical outcome.WebSocket plan gating
WebSocket plan gating
403. Test early.