Skip to content

API.md

Latest commit

 

History

History
151 lines (118 loc) · 6.34 KB

API.md

File metadata and controls

151 lines (118 loc) · 6.34 KB
Raw

MatchMesh API Reference — RC1

The public developer surface is MCP at /mcp. /v1/platform/* is the DTO API used by the bundled Next.js platform. RC1 does not expose a general-purpose REST football API.

All JSON errors outside the MCP transport use:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": {},
    "requestId": "..."
  }
}

The API accepts or generates x-request-id and echoes it in the response. Unexpected errors are logged server-side and returned as a generic 500 message.

Health

Method Path Meaning
GET /health Process liveness only
GET /ready Runs live PostgreSQL and Redis checks; returns non-2xx on failure

MCP transport

POST, GET, and DELETE /mcp implement the MCP Streamable HTTP transport. Clients must initialize with POST; the response supplies mcp-session-id, which subsequent requests send back. Browser origins are checked against MCP_ALLOWED_ORIGINS.

Premium tools/call requests may use:

Header Direction Purpose
PAYMENT-SIGNATURE Request Signed x402 payment proof
PAYMENT-REQUIRED Response Base64 x402 challenge for HTTP 402
PAYMENT-RESPONSE Response Base64 payment receipt
x-matchmesh-user Request RC1 user reference used by mock verification
x-wallet-address Request Wallet reference used by mock verification

Header names are case-insensitive. Use an MCP SDK/client rather than hand-rolling transport sessions.

MCP tools

The live manifest is available through MCP tools/list and the platform GET /v1/platform/tools. Schemas below are summarized; registry schemas are authoritative.

Tool Access Price Required input
get_live_matches Free 0 none
get_live_score Free 0 matchId UUID
get_match Free 0 matchId UUID
get_match_events Premium TOOL_DEFAULT_PRICE matchId UUID
get_team Free 0 teamId UUID
get_team_stats Premium 0.002 USDC teamId UUID, season
get_player Free 0 playerId UUID
get_player_stats Premium 0.002 USDC playerId UUID, season
get_standings Free 0 leagueId UUID
search_matches Free 0 search filters defined by registry
search_players Free 0 search query
search_teams Free 0 search query

Every tool calls FootballQueryService; no tool accesses a repository or upstream provider directly.

Agent Skills

Skills are executed by the platform API in RC1 and internally compose MCP tools plus MockLLMProvider.

Skill slug Category Required tools Estimated cost
match-summary Journalism get_match, get_match_events 0.030 USDC
fantasy-assistant Fantasy get_player_stats, get_team_stats 0.040 USDC
player-comparison Statistics get_player, get_player_stats 0.040 USDC
team-comparison Statistics get_team, get_team_stats 0.040 USDC
tactical-analysis Coaching get_match, get_match_events 0.050 USDC
var-explainer Journalism get_match_events 0.025 USDC
commentary-generator Commentary get_live_score, get_match_events 0.035 USDC
stats-explainer Analytics get_standings, get_player_stats, get_team_stats 0.050 USDC

GET /v1/platform/skills returns authoritative input/output JSON Schemas, examples, model support, required tools, visibility, and latency estimates.

Developer platform DTO API

These routes support the bundled frontend. Wallet fields must be 20-byte EVM addresses. Account-scoped routes verify that the supplied wallet is attached to the developer account.

Method Path Purpose
POST /v1/platform/session Find or create a test developer account for { wallet }
GET /v1/platform/tools Registry and pricing-derived tool catalog
GET /v1/platform/skills Skill registry catalog and schemas
GET /v1/platform/docs Generated tool and skill reference
GET /v1/platform/status Live DB/cache status plus configured/in-process states
POST /v1/platform/tools/:tool/execute Execute a tool; may return 402
POST /v1/platform/skills/:skill/execute Execute a skill; may return 402
POST /v1/platform/payments/mock Create a mock proof; forbidden outside mock mode
POST /v1/platform/funding Run the configured funding flow
GET /v1/platform/wallet Balance, funding history, and networks
GET /v1/platform/billing Current-month costs, payments, and receipts
GET /v1/platform/history Latest 100 tool and skill executions
GET /v1/platform/dashboard Aggregated developer dashboard DTO

Account queries use ?accountId=<uuid>&wallet=0x....

Execution request

{
  "accountId": "11111111-1111-4111-8111-111111111111",
  "wallet": "0x1111111111111111111111111111111111111111",
  "requestId": "optional-client-request-id",
  "arguments": {},
  "paymentSignature": "optional-x402-proof"
}

Successful execution

{
  "requestId": "...",
  "durationMs": 12,
  "cost": "0.002",
  "currency": "USDC",
  "cacheStatus": "bypass",
  "receipt": null,
  "response": {}
}

The current execution facade cannot observe inner football cache hits and reports bypass. This is a known observability limitation, not a claim that Redis is unused.

Funding request

{
  "accountId": "11111111-1111-4111-8111-111111111111",
  "wallet": "0x1111111111111111111111111111111111111111",
  "chain": "base",
  "amount": "50.000000"
}

Supported configured chain identifiers are ethereum, base, arbitrum, polygon, and injective. RC1 uses MockCCTPProvider; no real cross-chain funds move.

Limits and headers

  • Default body limit: 1 MiB (API_BODY_LIMIT_BYTES)
  • Default request timeout: 15 seconds (API_REQUEST_TIMEOUT_MS)
  • Default API rate limit: 120 requests/minute/IP (API_RATE_LIMIT_PER_MINUTE)
  • Provider requests have separate timeout, retry, rate-limit, and circuit-breaker configuration
  • Platform proxy default timeout: 15 seconds (MATCHMESH_API_TIMEOUT_MS)
  • Defensive API headers include cache-control: no-store, x-content-type-options: nosniff, x-frame-options: DENY, and referrer-policy: no-referrer