Guides

Best Practices

Recommended patterns and common mistakes to avoid when building with Prediction Markets API.

Patterns to Follow

Sync data server-side into your own database

Set up a server-side cron job to pull market data on a schedule and store it locally. This keeps your API usage predictable — even if your app traffic spikes 10x, your API call rate stays constant.

Calculate your expected usage before upgrading

Estimate how many markets you'll track, how often you refresh, and which platforms. Open markets on Kalshi alone can number in the thousands — factor that into your plan selection.

Filter at the API level, not in your code

Use query parameters — platforms, category, status, marketIDs — to return only what you need. Filtering in your code wastes bandwidth and counts against your entity quota.

Use marketIDs for direct lookups

When you already know which markets you want, pass marketIDs directly — this is the fastest query path and skips all other filtering logic.

Implement retry logic on 5xx errors

Wait a short interval then retry once on any 500-level error. You'll almost always get a successful response on the second attempt. If you don't, log the error and stop retrying.

Vary your polling interval based on market timing

Prices on markets that close in weeks rarely move. Markets closing in hours can move frequently. Poll distant markets less often (every 5–15 min) and near-term markets more often (every 30–60 sec) to use your quota efficiently.

Keep your API key secure

Never expose your key in frontend code. Never commit it to version control. Use environment variables.

Monitor your usage

Check the /account/usage endpoint to track your entity and request consumption before you hit limits.

Handle missing fields defensively

Some fields may not always be present across all platforms. Use fallbacks like market.title ?? market.shortTitle ?? market.marketID rather than assuming a field is always populated.

Anti-Patterns to Avoid

Making API requests from the browser / frontend

Never call the API directly from client-side code — this exposes your API key publicly. Use a server-side proxy or sync data into your own database and serve it from there.

Polling on the Free plan at high frequency

On the Free plan, data updates every 5 minutes. Polling faster than your plan's refresh rate wastes your request quota with no benefit.

Not handling 429 rate-limit errors

When you receive a 429, back off and wait before retrying. Immediately retrying burns through your quota even faster. Check /account/usage to understand which limit you hit.

Ignoring error messages in the response body

Every error response includes an error field explaining what went wrong. Log it — it's the fastest way to debug integration issues.

Using too many query parameters at once

Queries perform best with 1–3 filters (excluding limit, cursor, apiKey). Combining many filters can slow response times significantly.

Always fetching all open markets on every poll

Cache market data for longer when markets are far from closing. Focus fresh polling on markets that are close to resolution or actively trading.