Bucket Data API · v1

API reference

Programmatic access to multi-sport predictions, research reports and agent positions across MLB, NFL, CFB, NBA, NHL, EPL, ATP, WTA and the 2026 World Cup.

Overview

The API is REST over HTTPS, JSON in and out, versioned under /v1. Discovery endpoints (leagues, slates, event metadata) are free; predictions, reports and agent bets are paid. Every response is keyed by an opaque, stable event id.

Base URL

https://api.bvcket.xyz

Quickstart

Discovery needs no auth. List today's NFL slate:

curl "https://api.bvcket.xyz/v1/events?league=nfl"

Then buy a prediction with your API key (create one here):

curl https://api.bvcket.xyz/v1/predictions/nfl:nflverse:2026_01_NE_SEA \
  -H "Authorization: Bearer sk_live_…"

Authentication

Paid endpoints accept payment on either of two rails. A request is served if it satisfies one of them.

Rail A — subscription API key

Send your key as a bearer token. Keys carry a plan (single-sport or all-sports), a league/resource scope, a monthly quota and a per-minute rate limit.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Rail B — x402 pay-per-call

No account required. Settle a few cents of USDC on Base per call. See Paying with x402.

Paying with x402

A paid request with no credentials returns 402 with an accepts block describing the payment, per the x402 spec.

HTTP/1.1 402 Payment Required
{
  "x402Version": 1,
  "error": "payment_required",
  "resource": "report",
  "event_id": "nfl:nflverse:2026_01_NE_SEA",
  "accepts": [{
    "scheme": "exact", "network": "base",
    "maxAmountRequired": "350000",           // 0.35 USDC, 6 decimals
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x…", "resource": "/v1/reports/nfl:nflverse:2026_01_NE_SEA"
  }],
  "subscription": { "plans": ["single_sport", "all_sports"] }
}

Your x402 client signs the payment and retries with an X-PAYMENT header; the response carries X-PAYMENT-RESPONSE with the settlement.

Pre-game rule. Payment is refused (you are not charged) once the event has started.
Refresh window. A purchase covers re-fetches of the same event until start time — resend the settlement as X-PAYMENT-RECEIPT: <tx> to re-read without paying again.
Prices per resource are discoverable at /v1/schema.

Event IDs

Every event has one opaque, URL-safe id of the form league:keytype:value. You never construct these — take them from the /v1/events discovery response.

mlb:sd:19428
nfl:nflverse:2026_01_NE_SEA
cfb:espn:401752812
atp:espnc:401799021
wc26:match:wc26-arg-bra-2026-06-20
nba:id:40881                       (serial-PK fallback)

Rate limits & quotas

Subscription keys carry a per-minute rate limit and a monthly call quota (all-sports keys are unmetered). Exceeding either returns 429. x402 calls are unlimited — you pay per call. Usage is recorded per key; view it from your keys dashboard.

Errors

Status	Meaning
400	Malformed event_id or bad query parameter.
401	Invalid or revoked API key.
402	Payment required — no valid API key and no x402 payment. Body offers both rails.
403	API key not scoped for this resource or league.
404	No such event.
409	Event exists but no prediction/report is published yet.
429	Rate limit or monthly quota exceeded.

Endpoints

GET/v1/leaguesfree

List supported leagues and which resources each can serve.

Request

curl https://api.bvcket.xyz/v1/leagues

Response

{
  "tz": "America/New_York",
  "count": 9,
  "leagues": [
    { "code": "nfl", "league": "NFL", "sport": "football", "format": "game",
      "resources": { "prediction": true, "report": true,
                     "player_props": true, "live_prices": true } }
  ]
}

GET/v1/eventsfree

Slate of events for a league on an ET calendar date (discovery).

Parameters

league required — League code: mlb, nfl, cfb, nba, nhl, epl, atp, wta, wc26.
date optional — ET date YYYY-MM-DD. Defaults to today (9am ET rollover).

Request

curl "https://api.bvcket.xyz/v1/events?league=nfl&date=2026-09-07"

Response

{
  "league": "NFL", "date": "2026-09-07", "count": 14,
  "events": [
    {
      "event_id": "nfl:nflverse:2026_01_NE_SEA",
      "league": "NFL", "sport": "football", "format": "game",
      "starts_at": "2026-09-07T17:00:00Z", "status": "scheduled",
      "competitors": [
        { "role": "home", "name": "Seattle Seahawks" },
        { "role": "away", "name": "New England Patriots" }
      ],
      "context": { "season": 2026, "week": 1 },
      "availability": { "prediction": true, "report": true,
                        "player_props": true, "live_prices": true }
    }
  ]
}

GET/v1/events/{event_id}free

Metadata + availability flags for a single event.

Parameters

event_id required — Canonical opaque id (see Event IDs).

Request

curl https://api.bvcket.xyz/v1/events/nfl:nflverse:2026_01_NE_SEA

Response

{
  "event_id": "nfl:nflverse:2026_01_NE_SEA",
  "league": "NFL", "status": "scheduled",
  "competitors": [ /* … */ ],
  "availability": { "prediction": true, "report": true }
}

GET/v1/predictions/{event_id}paid

Core prediction — model + market probabilities keyed by outcome, plus the pick.

Parameters

event_id required — Canonical opaque id.

Request

curl https://api.bvcket.xyz/v1/predictions/nfl:nflverse:2026_01_NE_SEA \
  -H "Authorization: Bearer sk_live_…"

Response

{
  "event_id": "nfl:nflverse:2026_01_NE_SEA", "league": "NFL",
  "outcomes": ["home", "away"],
  "model":  { "home": 0.58, "away": 0.42 },
  "market": { "home": 0.55, "away": 0.45 },
  "pick": { "side": "home", "competitor": "Seattle Seahawks",
            "confidence": "LEAN", "edge_pct": 3.0,
            "summary": "Edge: 3.0% on Seattle Seahawks" },
  "markets": {
    "spread": { "line": -2.5, "pick": "home", "prob": 0.53 },
    "total":  { "line": 44.5, "pick": "over", "prob": 0.51 }
  },
  "moneyline": -135, "tldr": "Model likes Seattle's trench edge."
}

GET/v1/reports/{event_id}paid

Full research report — everything in a prediction plus analysis, research blocks and live data.

Parameters

event_id required — Canonical opaque id.

Request

curl https://api.bvcket.xyz/v1/reports/nfl:nflverse:2026_01_NE_SEA \
  -H "Authorization: Bearer sk_live_…"

Response

{
  "event_id": "nfl:nflverse:2026_01_NE_SEA", "league": "NFL",
  "outcomes": ["home", "away"], "model": { /* … */ }, "pick": { /* … */ },
  "analysis": {
    "markdown": "## Executive summary\n…",
    "summary": "…",
    "chapters": [ { "heading": "Trenches & special teams", "body": "…" } ],
    "recommendations": [ { "bet_type": "MONEYLINE BET", "pick": "…",
                           "confidence": 72, "is_pass": false } ]
  },
  "research": { "injury_data": { /* … */ }, "news_headlines": [ /* … */ ] },
  "live": { /* score/box/plays when in-progress; football via ESPN */ }
}

GET/v1/reports?league=&date=paid

Slate bundle — every buyable report for a league on an ET date. Priced per game (rate × buyable reports, capped), far cheaper than buying each individually.

Parameters

league required — League code, e.g. nfl.
date optional — ET date YYYY-MM-DD. Defaults to today.

Request

curl "https://api.bvcket.xyz/v1/reports?league=nfl&date=2026-09-07" \
  -H "Authorization: Bearer sk_live_…"

Response

{
  "league": "NFL", "date": "2026-09-07",
  "count": 14, "price_usdc": "2.80",
  "reports": [ { /* full Report object per game */ } ]
}

GET/v1/agent-bets/{event_id}paid

The positions the platform's betting agents actually took for this event.

Parameters

event_id required — Canonical opaque id.

Request

curl https://api.bvcket.xyz/v1/agent-bets/mlb:sd:19428 \
  -H "Authorization: Bearer sk_live_…"

Response

{
  "event_id": "mlb:sd:19428", "league": "MLB",
  "condition_id": "0x…",
  "bets": [
    { "market": "Yankees ML", "market_outcome": "YES", "bet_amount": 50.0,
      "shares": 78.1, "yes_price_initial": 0.64, "yes_price_new": 0.71,
      "profit": 5.4, "reasoning": "…" }
  ]
}

GET/v1/schemafree

Machine-readable field docs + x402 price discovery.

Request

curl https://api.bvcket.xyz/v1/schema

Response

{
  "leagues": ["MLB","NFL","CFB","NBA","NHL","EPL","ATP","WTA","WC26"],
  "endpoints": { /* … */ },
  "payments": { "rails": ["subscription_api_key", "x402"],
                "x402": { "network": "base", "asset": "USDC",
                          "prices_usdc": { "prediction": "0.02", "report": "0.35" } } }
}

Resource schemas

Probabilities are keyed by outcome so two-way and three-way (soccer/EPL draw) sports share one shape. Absent concepts (a spread on a tennis moneyline, a draw in baseball) are simply omitted — never null placeholders.

Prediction:
  event_id     string           canonical id
  league       string
  outcomes     string[]         ["home","away"] | ["home","draw","away"]
  model        { [outcome]: number }   internal model probs, 0..1
  market       { [outcome]: number }   market-implied probs, 0..1
  pick         { side, competitor, confidence, edge_pct, summary }
  markets      { spread?, total? }     { line, pick, prob }
  moneyline    number | object         normalized odds
  tldr         string

Versioning

The current version is v1, pinned in the path. Additive changes (new fields, new leagues, new endpoints) ship without a version bump; breaking changes would ship under a new path. Machine-readable field docs live at /v1/schema.

Get an API key →