<div align="center">

<img src="assets/readme-hero-animated.svg" alt="CupOracle — the missing World Cup MCP server: an agent asks, the tools fire, x402 pays, and the receipt lands on Injective" width="100%" />

cuporacle-mcp

Your AI assistant is football-blind during the biggest event on earth — it can't see tonight's World Cup match, has no odds, and has no way to pay for premium data itself.<br/> CupOracle is a published MCP server that fixes that: live FIFA World Cup 2026 fixtures, scores, consensus odds and the knockout bracket as free tools — plus wc_edge, an agent that pays 0.05 USDC via Injective x402 by itself (under a spend cap) and cites the on-chain receipt.<br/> Shipped: 8 tools · 2 resources · 1 prompt over stdio · 63 vitest · MCP-Inspector-conformant in CI · publish-ready npm package.

</div>

📊 Pitch deck (PDF) · interactive HTML — the 10-slide story (arrow keys · press P to print).

# Claude Code — the 4 free data tools work with just two free API keys
claude mcp add cuporacle -- npx -y cuporacle-mcp

cuporacle-mcp is a standalone Model Context Protocol server that runs side by side with the Injective MCP server: 8 tools + 2 resources + 1 prompt over stdio. Free data tools work out of the box; wc_edge is a reference implementation of an agent buying and proving its own alpha keylessly via Injective's x402.

🧑‍⚖️ Notes for judges — reproduce in < 5 min

• Zero-cost path. The four free tools (wc_fixtures, wc_live, wc_odds, wc_bracket) return real live World Cup 2026 data with just the two free API keys — no wallet, no funds.
• The x402 buyer path runs with zero funds. wc_edge(matchId, dry_run: true) (or npm run paid-call-smoke) parses the recorded 402 quote, enforces the spend cap, and signs the EIP-3009 authorization locally — a deterministic proof of the payment client with no money moved and no fabricated receipt.
• < 5-minute reproduce:

  npm install
  npm run smoke      # cold-start over stdio → lists 8 tools/2 resources/1 prompt + a live free call
  npm test           # 63 vitest (schemas · spend cap · 402-parse · EIP-3009 sign · receipts · degrade)
  npm run inspector  # official MCP Inspector conformance against the built dist/
  

• Honestly gated (not faked): a real settled wc_edge payment needs a few cents of USDC on Injective (funding is user-gated) plus the live EdgeLedger upstream. Until then wc_edge degrades to free odds and never invents an edge or a receipt — full honest state in STATUS.md.

---

Why this exists

Agents have no first-class sports capability. Injective's own MCP server covers wallets, markets, CCTP and trading — but an agent asked "is tonight's match worth a bet?" has to hallucinate or scrape, and there's no pattern for an agent paying for premium data itself. CupOracle is that missing layer, built as a composable server that runs side by side with the Injective MCP server.

Tools

Tool	Gate	Returns
wc_fixtures(date?)	free	fixtures for a day or the next upcoming window
wc_live(matchId)	free	live score, minute, status
wc_odds(matchId)	free	consensus h2h odds + de-vigged implied probabilities
wc_bracket()	free	knockout bracket state (R16 → Final)
wc_edge(matchId, maxSpend?, dry_run?)	pays x402	CLV-audited edge + conviction ladder + receipt tx
receipt_verify(txHash)	free	verifies a receipt on Injective EVM (block time, amount, payee)
wallet_fund_guide(chain?)	free	CCTP runbook to fund the agent wallet
wc_spend_ledger()	free	the agent's own purchase history: entries + receipts + session total vs cap

Resources: wc://bracket, wc://ledger · Prompt: analyze-match(matchId).

Quickstart

1. Get keys

• football-data.org free tier → FOOTBALL_DATA_KEY
• the-odds-api.com free tier → ODDS_API_KEY

The four free data tools work with just these two keys. wc_edge additionally needs a payer wallet (see Funding).

2. Add to your harness

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "cuporacle": {
      "command": "npx",
      "args": ["-y", "cuporacle-mcp"],
      "env": {
        "FOOTBALL_DATA_KEY": "…",
        "ODDS_API_KEY": "…",
        "CUPORACLE_PRIVATE_KEY": "0x…",
        "CUPORACLE_MAX_SPEND": "0.50"
      }
    }
  }
}

Claude Code:

claude mcp add cuporacle \
  -e FOOTBALL_DATA_KEY=… -e ODDS_API_KEY=… \
  -e CUPORACLE_PRIVATE_KEY=0x… -e CUPORACLE_MAX_SPEND=0.50 \
  -- npx -y cuporacle-mcp

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "cuporacle": { "command": "npx", "args": ["-y", "cuporacle-mcp"],
      "env": { "FOOTBALL_DATA_KEY": "…", "ODDS_API_KEY": "…" } }
  }
}

3. Ask

"What's tonight's Semi-Final, and is it worth a bet?"

The assistant lists the fixture (wc_fixtures), pulls odds (wc_odds), buys a vetted edge for ~5¢ (wc_edge) paying via x402 itself, and cites the receipt. Paste that hash into receipt_verify to confirm the payment on Injective.

Injective technologies used

CupOracle is Injective-native by construction — remove any layer and it's just a scraper or a hosted API with a billing page.

#	Technology	Exact surface	Where
1	MCP Server	Publishes a complete server (stdio): 8 tools + 2 resources + 1 prompt, Inspector-conformance-checked. Extends the InjectiveLabs/mcp-server pattern and runs beside it.	the whole package
2	x402	Autonomous client: parses the 402 quote (accepts / PAYMENT-REQUIRED), signs an EIP-3009 transfer authorization, retries with PAYMENT-SIGNATURE, reads the receipt from PAYMENT-RESPONSE. Uses @injectivelabs/x402 ./client + ./eip3009.	src/x402/, wc_edge
3	Agent Skills	Ships the cuporacle Skill: tool-selection table, spend policy, fund-if-broke runbook.	skills/cuporacle/SKILL.md
4	USDC + CCTP	Native USDC 0xa00C…235a (Circle FiatTokenV2_2, EIP-3009). Funding path routes to the Injective MCP server's cctp_supported_chains → cctp_attestation_status → cctp_mint.	wallet_fund_guide, Skill
5	Injective EVM	Mainnet eip155:1776 (Blockscout + sentry.evm-rpc.injective.network), testnet eip155:1439. receipt_verify reads the tx over the EVM RPC.	src/networks.ts, receipt_verify

Interop, not wrap. CupOracle does not reimplement chain ops or wrap the Injective MCP tools as its own — both servers run in the same harness and the Skill routes funding to Injective's tools. Honesty over land-grab.

The autonomous-payment loop (wc_edge)

POST /api/edge  ──▶  402 { accepts: [{ network: eip155:1776, amount: 50000, asset: USDC, payTo }] }
      │
      ├─ spend-cap gate  (per-call max · per-session cap · "ask human above cap")
      ├─ sign EIP-3009 authorization  (local viem signTypedData — no broadcast)
      ├─ retry with PAYMENT-SIGNATURE header
      ▼
200 { edge, ladder, pick_hash }  +  PAYMENT-RESPONSE { transaction: 0x… }
      │
      ▼   agent cites receipt_tx  ──▶  receipt_verify(0x…)  ──▶  block time + amount on Injective

Spending is auditable in-conversation via wc_spend_ledger (and wc://ledger). Failures teach: INSUFFICIENT_USDC carries the CCTP runbook; SPEND_CAP_HIT carries the cap and how to raise it (ask the human — the agent never raises its own).

Funding the agent wallet

wc_edge needs a few cents of USDC on Injective. Generate a throwaway payer wallet and fund it via CCTP:

npx cuporacle-mcp init          # prints a fresh wallet address + key

Then call wallet_fund_guide (or ask your agent to) for the CCTP steps, executed with the Injective MCP server: account_balances → cctp_supported_chains → burn on Base (domain 6) → cctp_attestation_status → cctp_mint. Fund only cents; the default cap is 0.50 USDC.

Development

npm install
npm run smoke      # cold-start over stdio, list 8 tools/2 resources/1 prompt, one live call
npm test           # 63 vitest (schemas, spend cap, 402-parse, EIP-3009 sign, receipts, degrade)
npm run bench      # cache hit/miss + wc_edge dry_run (parse+sign) p50/p95
npm run build      # tsup → dist (publish-ready)
SMOKE_BIN=dist npm run smoke   # smoke the built artifact

npm run paid-call-smoke runs a real paid wc_edge end-to-end — it is funds-gated behind CUPORACLE_ALLOW_PAID=1 and a funded key, and otherwise falls back to a dry run.

Configuration

Env	Default	Meaning
FOOTBALL_DATA_KEY	—	football-data.org key (free data tools)
ODDS_API_KEY	—	the-odds-api.com key (odds)
CUPORACLE_PRIVATE_KEY	—	payer wallet key for wc_edge (fund cents only)
CUPORACLE_MAX_SPEND	0.50	per-session USDC spend cap
CUPORACLE_NETWORK	eip155:1776	eip155:1776 mainnet · eip155:1439 testnet
EDGELEDGER_URL	https://edgeledger.edycu.dev	upstream edge provider

Extend it (add your own sport)

Each tool is { name, config, handler } (src/tools/). To add, say, a cricket server: copy a free tool, swap the data client in src/data/, register it in src/tools/index.ts. The x402 client (src/x402/) is sport-agnostic — reuse it to sell any premium signal. PRs welcome.

Honest limitations

1. wc_edge depends on EdgeLedger's /api/edge (a disclosed sibling project). If it's down, wc_edge degrades to free odds — it never fabricates an edge.
2. Free-tier data APIs cap request rates → 60s cache + committed snapshots (always labeled [snapshot]).
3. The payer keystore holds a real (tiny) balance. Spend caps default low; fund only cents. Windows keystore paths are documented, not hardened.

License

MIT. "Football data provided by the Football-Data.org API."