PhotonOdds API Authentication and Limits

Send your API key safely

PhotonOdds API requests use the X-API-Key header. Create a key in the Developer portal, keep it out of source control, and load it from a secret manager or environment variable at runtime.

curl -H "X-API-Key: $PHOTONODDS_API_KEY" \
  https://api.photonodds.com/api/v1/odds

Give each application its own key where the portal allows it. If a key is exposed, revoke or rotate it through the portal and update the affected deployment. Never put an API key in a client-side bundle, public issue, webhook URL, or screenshot.

Read the documented capacity headers

Authenticated responses report API-key capacity with:

• X-RateLimit-Limit: the key's hourly request cap, or unlimited;
• X-RateLimit-Remaining: requests left in the current sliding one-hour window, when applicable; and
• Retry-After: seconds to wait when a request is rate-limited.

The public contract intentionally does not require a reset timestamp. Build your client around the headers that are actually present, rather than assuming a per-minute window or a X-RateLimit-Reset value.

Recover from a 429

When the API returns HTTP 429, stop issuing further requests for that key and wait for Retry-After before retrying. If a response does not include a usable wait value, use a bounded fallback delay with jitter.

import random
import time
import requests

def get_with_retry(url, headers):
    response = requests.get(url, headers=headers, timeout=15)
    if response.status_code != 429:
        response.raise_for_status()
        return response

    retry_after = response.headers.get("Retry-After")
    wait = int(retry_after) if retry_after and retry_after.isdigit() else 30
    time.sleep(wait + random.uniform(0, 1))
    return get_with_retry(url, headers)

In production, add a retry limit and structured logging. Coordinate concurrent workers around the same key so they do not immediately exhaust the capacity released after a wait.

Design within your plan

The exact request and bookmaker capacity depends on the API key's tier and selected bookmaker set. Inspect the response headers and your portal rather than relying on examples from another account. The API documentation also describes which routes bind a bookmaker and which only operate on bookmakers already selected for the key.

API response shapes explains the available odds routes. Polling, changes, and WebSockets helps you choose a transport without assuming unavailable features.

Configure this in PhotonOdds

Create credentials in the Developer portal, store them as a secret, and test your retry behaviour against a development integration before you depend on it.

18+ only. Betting carries risk. PhotonOdds provides analytical and educational tools, not a promise of profit or a recommendation to place a bet. If gambling is causing harm, see Responsible Gambling.