NullBall Public API [BETA]

// AI football predictions for developers and AI agents — derived data only, privacy-first, no tracking.

Get started in 30 seconds

« curl -H "X-API-Key: np_live_..." \
    https://nullball.xyz/api/v1/predictions?league=world-cup

No key yet? In the current beta, keys are issued manually — get in touch to request one. A self-service dashboard ships with the accounts system.

Tiers

	Free	Pro	Elite
Quota / day (UTC)	100	5,000	50,000
Burst / minute	10	60	300
Predictions	winner	full + result	full + result
Value bets (edge %)	—	yes	yes
Bulk NDJSON export	—	yes	yes

Endpoints

GET /api/v1/meta                          # freshness — check before crawling (anon)
GET /api/v1/leagues
GET /api/v1/fixtures?league={slug}
GET /api/v1/predictions?league=&date=&limit=
GET /api/v1/accuracy                      # public track record
GET /api/v1/standings/{league}            # world-cup: 12 groups A-L
GET /api/v1/value-bets                    # pro+
GET /api/v1/export/predictions.ndjson     # pro+, bulk 1 call
GET /api/v1/export/results.ndjson         # pro+, settled matches only

For AI agents

/llms.txt — API description for LLMs (llmstxt.org)
/llms-full.txt — per-field schema, generated from Pydantic
/api/v1/openapi.json — OpenAPI 3.1
ETag on every GET — poll with If-None-Match for a 304
MCP server: python -m mcp_server.server (stdio) — 7 tools

Rules

Schema is additive-only in v1 — fields are never renamed or removed (contract-tested).
Errors: {"error": {"code", "message"}} + Retry-After on 429/503.
Cold cache returns 503 (zero-upstream policy) — never fans out to the data source.
Datetime: ISO-8601 UTC + an *_ict field (Asia/Ho_Chi_Minh).

For AI agents — get started

// Two ways to connect: native MCP tools, or plain HTTP with the self-describing llms.txt.

1 · MCP server — Claude Code/Desktop, Cursor, any MCP client. Seven typed tools (meta, leagues, fixtures, predictions, accuracy, standings, value-bets):

claude mcp add nullball \
  -e NULLPREDICT_API_KEY=np_live_... \
  -e NULLPREDICT_BASE_URL=https://nullball.xyz \
  -- python -m mcp_server.server

2 · Plain HTTP — any language. Point the agent at /llms.txt first; it self-describes auth, endpoints and tiers:

curl -H "X-API-Key: np_live_..." \
  "https://nullball.xyz/api/v1/predictions?league=world-cup&limit=5"

// Need a key? Free tier, no card — ask the operator or see the tiers above. Discovery files: /llms.txt · /llms-full.txt · /api/v1/openapi.json