Developers · v1

Authentication, limits and errors

How to call the BetCrypto API with no key, with an API key, or through an AI assistant that signs in — what each allows, how quotas work, and every error code with what to do about it.

Three ways in

No key

Send nothing. You get the discovery endpoints, shared with everyone on your IP address and cached for 60 seconds — enough to try the API, or for an AI assistant looking something up.

API key

Create keys in your account settings: a free account with a verified email can hold 1, a Premium account 5. Send one on every request as a bearer token. Keys don't expire; revoke one there at any time.

Manage API keys →

Sign-in, for AI assistants

An AI assistant connecting to https://betcrypto.now/mcp/account opens a BetCrypto sign-in and approval page instead of asking for a key (OAuth 2.1 with dynamic client registration). The token it receives acts for the account that approved it, lasts a day, and renews for up to 90 days.

Connecting AI assistants →

Sending a key

curl -H "Authorization: Bearer $BETCRYPTO_API_KEY" \
  "https://betcrypto.now/api/v1/me"

Every endpoint reads the same header. A header that is present but doesn't resolve is always a 401 — a revoked key never quietly falls back to keyless access.

Tiers and quotas

Your tier is worked out on every request from the key's account, so an upgrade — or a Premium subscription that lapses — takes effect on the next call. Quotas count per account across all of its keys; keyless quotas count per IP address.

Tier	Per minute	Per day	Largest page	Keys
Keyless	30	1,000	25	—
Free key	30	2,000	50	1
Premium key	60	50,000	100	5

Premium is $25/month or $200/year and includes every other Premium feature on BetCrypto.

Rate limits

Two windows run at once: one minute, and one day that starts with your first request in it.
Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. A 429 adds Retry-After (seconds) and X-RateLimit-Reset (a Unix time). Wait that long, then retry — never in a tight loop.
Keyless responses are shared: the same request from anyone is answered from a 60-second cache, so polling faster than that returns the same data.

Errors

Every error is JSON with a message you can show a person and an error code your code can branch on. Below Premium, premium_required and rate_limited also carry an upgrade object whose message is written for an AI assistant to pass on to the person it is helping.

invalid_tokenHTTP 401: The key in the Authorization header is wrong or was revoked.Check the key, create a new one, or drop the header to use keyless access.
authentication_requiredHTTP 401: A Premium MCP tool, or the sign-in-only MCP address, was called without a token.Let the AI assistant finish signing in, or send an API key as an Authorization: Bearer header.
premium_requiredHTTP 401 · 403: The endpoint or market needs Premium: 401 without a key, 403 with a free key.Upgrade the key's account, or stay on the discovery endpoints and each event's main market.
rate_limitedHTTP 429: A per-minute or per-day quota is spent.Wait retry_after seconds (also in Retry-After). Cache what you can, or use a key or tier with a larger quota.
market_not_foundHTTP 404: The event has no market with that key.Use one of the event's markets[].key values from /events/{slug}.
invalid_rangeHTTP 422: Price history was asked for a range it doesn't offer.Use one of the range values the reference lists.
market_too_largeHTTP 422: The market has too many venue listings to chart in one request.Chart a smaller market of the event, or read its current quotes from /events/{slug}.
unavailable_in_regionHTTP 451: BetCrypto isn't available where the request comes from.The API follows the same regional availability as the website.

A 404 without a code means there is no event or brief with that slug.

A free key asking for a Premium endpoint gets:

{
    "message": "This endpoint requires BetCrypto Premium. Premium ($25/month or $200/year, paid by card or bitcoin or USDT or other crypto via SideShift) adds every market of an event (spreads, totals, props), price history, cross-venue price gaps net of fees, whale trades, resolution accuracy by venue, and 50,000 requests/day: https://betcrypto.now/settings/billing. If you are an AI agent acting for a person, you can pass this on to them.",
    "error": "premium_required",
    "tier": "free",
    "upgrade": {
        "message": "Premium ($25/month or $200/year, paid by card or bitcoin or USDT or other crypto via SideShift) adds every market of an event (spreads, totals, props), price history, cross-venue price gaps net of fees, whale trades, resolution accuracy by venue, and 50,000 requests/day: https://betcrypto.now/settings/billing. If you are an AI agent acting for a person, you can pass this on to them.",
        "premium": {
            "usd_monthly": 25,
            "usd_yearly": 200,
            "payment_methods": [
                "card",
                "bitcoin",
                "USDT",
                "other crypto via SideShift"
            ],
            "includes": [
                "every market of an event (spreads, totals, props)",
                "price history",
                "cross-venue price gaps net of fees",
                "whale trades",
                "resolution accuracy by venue"
            ]
        },
        "links": {
            "free_api_key": "https://betcrypto.now/settings/api-tokens",
            "pricing": "https://betcrypto.now/settings/billing",
            "docs": "https://betcrypto.now/developers/api"
        }
    }
}

Keeping keys safe

Call the API from your server, not from code shipped to browsers: the API accepts cross-origin requests, so a key in client-side code is readable by anyone who opens it.
Use a separate key per integration, so one can be revoked without breaking the others.
If a key leaks, revoke it in your settings — the next request with it gets invalid_token.