AI Infrastructure & Pay-Per-Use Data Protocols for World Cup Agents
Features β’ Architecture β’ SDK Reference β’ Tech Stack β’ Injective Synergy β’ API Reference β’ Quick Start β’ Contributing
Built Natively on Injective β Keplr Verification Β· x402 Micropayments Β· Circle CCTP Settlement
Important
Hackathon Release Note (RC1): MatchMesh is configured for development/hackathon environments. Blockchain components (Circle CCTP, x402 challenge signatures) and the LLM engine run in validated mock modes. Wallet connection resolves EVM signatures on Injective but does not perform production-level state validation. Review the Security Policy and Architecture overview before public hosting.
MatchMesh is an MCP-native, pay-per-use football data and AI workflow platform. It normalizes messy third-party provider data into a single clean domain model, exposes standard Model Context Protocol (MCP) tools, composes them into high-level Agent Skills, and secures premium database requests using the cryptographic x402 protocol.
- What it solves: Instead of dealing with expensive Web2 subscription models, complex API key negotiations, or rigid CORS limits, AI agents and frontend developers query real-time football statistics, lineups, and match data on a pay-per-use basis.
- How AI is used: MatchMesh exposes a registry of 12 MCP tools and 8 Agent Skills (using Zod structured schema outputs). Agents run complex workflowsβlike match audits, team comparison, and predictionsβwithout managing raw data parsers.
- Payment Settlement: Users fund their internal ledger balance through a mock Circle Cross-Chain Transfer Protocol (CCTP) pipeline on Injective and authorize premium query execution using HMAC-SHA256 x402 challenge-response tokens.
This project is built specifically to highlight the synergy of decentralized micropayments, model context interoperability, and cross-chain settlement on Injective:
- Integration: Users log in natively using the Keplr Wallet configured for the Injective network (
injective-1mainnet orinjective-888testnet). - Execution: The platform extracts the walletβs EVM-compatible hex address representation (
0x...equivalent) via Keplr'sethereumHexAddressproperty. This serves as the unified database account identifier for cross-chain transactions and ledger states.
- Integration: Premium API endpoints and registry tools are metered on a pay-per-use basis in USDC.
- Execution: When an agent or app calls a premium endpoint, the server responds with an
HTTP 402 Payment Requiredcarrying a base64-encoded challenge. The client signs this challenge using their private key (HMAC-SHA256), and retries the request. The server verifies the signature, validates the receipt, and debits the user's ledger balance.
- Integration: Users can deposit funds into their ledger balance using Circleβs Cross-Chain Transfer Protocol (CCTP).
- Execution: The system tracks cross-chain USDC burns and mints. Users submit their transaction hashes on-chain, which are processed by the worker to credit the internal ledger balance. The backend includes double-deposit protection and replay-attack checks.
- Integration: Standardized Model Context Protocol (MCP) server endpoints allow immediate connection of any LLM-powered agent.
- Execution: The server hosts 12 registry-backed MCP tools covering live scores, referee cards, player performance, and table standings. It handles JSON-RPC requests natively, ensuring instant agent integration.
- Integration: Multi-step sports reasoning capabilities wrapped in Zod schema contracts.
- Execution: Instead of raw data queries, agents can invoke 8 preset Agent Skills (e.g. VAR Explainer, Fantasy Assistant, Match Summaries). The skill engine runs underlying MCP tools in parallel, builds grounded prompt context, and queries the LLM provider to get validated outputs.
- Integration: Easy-to-use TypeScript/JavaScript library to build agents.
- Execution: Integrates directly with Vercel AI SDK and LangChain. It features built-in, transparent x402 challenge signing and retrying, allowing developers to call metered tools seamlessly as if they were free local functions.
Traditional football and sports APIs are built for web browsers, not for autonomous AI agents. They require subscription plans, lack machine-readable API definitions, and impose high barriers to entry.
MatchMesh transforms raw sports data into an agent-ready cognitive layer.
| Problem (Legacy APIs) | Solution (MatchMesh) |
|---|---|
| Subscription Lock-in: High monthly costs regardless of usage volume. | x402 Micropayments: Crypographically metered pay-per-use query pricing. |
| No Machine Interface: Complex JSON formats require custom parsing code. | MCP-Native: Standardized Model Context Protocol schemas for instant LLM integration. |
| Centralized Funding: Traditional bank integrations or credit card setup. | CCTP Settlement: Decentralized wallet funding across supported networks (Injective). |
| No Reasoning Layer: Raw transaction tables without analysis. | Agent Skills: Built-in multi-turn reasoning schemas for match reports and predictions. |
| CORS Limitations: APIs cannot be called safely from browser-side dApps. | Proxy API Gateway: Serverless proxy layer handles secure data caching and rate limiting. |
- π οΈ MCP-Native Data Engine
Exposes 12 registry-backed Model Context Protocol tools for fixtures, live scores, lineups, player statistics, standing tables, and referee assignments. - π§ Registry-Backed Agent Skills
Composes raw data tools into 8 high-level Agent Skills (e.g., Compare teams, Audit match history, Predict match outcomes) backed by Zod structured outputs. - π Cryptographic x402 Challenges
Protects premium API endpoints with HMAC-SHA256 challenge tokens, replay-attack protection, cryptographic receipts, and audit ledgers. - πΈ Cross-Chain CCTP Funding
Settles balances using mock Circle CCTP integrations, featuring duplicate-deposit prevention and automated ledger updates. - πͺͺ Keplr Wallet Verification
Authenticates and verifies Injective EVM-compatible addresses (0x...hex equivalent) via Keplr extension sessions. - π Glassmorphic Developer Platform
Premium Next.js dashboard featuring a interactive playground, catalog explorer, billing history, analytics charts, and real-time dependency status tracking.
MatchMesh provides 8 pre-built Agent Skills that compose raw database/MCP actions into semantic reasoning workflows.
| Skill | Category | Underlying Tools | Cost | Target Latency |
|---|---|---|---|---|
| Match Summary | Journalism | get_match, get_match_events |
0.03 USDC | 1200ms |
| Fantasy Assistant | Fantasy | get_player_stats, get_team_stats |
0.04 USDC | 1600ms |
| Player Comparison | Statistics | get_player, get_player_stats |
0.04 USDC | 1400ms |
| Team Comparison | Analytics | get_team, get_team_stats |
0.04 USDC | 1400ms |
| Tactical Analysis | Coaching | get_match, get_match_events |
0.05 USDC | 1700ms |
| VAR Explainer | Journalism | get_match_events |
0.025 USDC | 1000ms |
| Commentary Generator | Commentary | get_live_score, get_match_events |
0.035 USDC | 900ms |
| Stats Explainer | Statistics | get_standings, get_player_stats, get_team_stats |
0.05 USDC | 1500ms |
graph LR
MS["Match Summary"] --> Match["get_match"]
MS --> Events["get_match_events"]
FA["Fantasy Assistant"] --> PlayerStats["get_player_stats"]
FA --> TeamStats["get_team_stats"]
PC["Player Comparison"] --> Player["get_player"]
PC --> PlayerStats
TC["Team Comparison"] --> Team["get_team"]
TC --> TeamStats
TA["Tactical Analysis"] --> Match
TA --> Events
VAR["VAR Explainer"] --> Events
CG["Commentary Generator"] --> Score["get_live_score"]
CG --> Events
SE["Stats Explainer"] --> Standings["get_standings"]
SE --> PlayerStats
SE --> TeamStats
MatchMesh utilizes a modular, decoupled architecture to handle high-frequency data ingestion, caching, and cryptographic billing:
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Client Layer β
β Next.js 16 SPA Β· Keplr Connector Β· Playground UI β
βββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββ
β (HTTP/API Proxy)
βββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββ
β Orchestration Layer β
β Fastify Router Β· TSyringe DI Container Β· Rate Limiter β
βββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββ
β (Internal Services)
βββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββ
β Logic Layer β
β MCP Registry Β· Agent Skills Engine Β· x402 Verifier β
βββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββ
β (Data Mapping / Cache)
βββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββ
β Data & Adapter Layer β
β PostgreSQL (Prisma) Β· Redis Cache Β· API-Football Node β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
| Layer | Component | Description |
|---|---|---|
| Client Layer | Frontend | Next.js App Router, Tanstack Query, and Lucide React. |
| Orchestration | Fastify Server | Serves REST endpoints, handles MCP JSON-RPC protocol, and runs worker processes. |
| Logic Layer | Domain Services | Execution engines for MCP tools, Agent Skills, x402 signature verifications, and CCTP billing. |
| Data & Cache | Persistence | PostgreSQL stores accounts, receipts, ledgers, and audit logs. Redis serves as cache-aside and rate-limiting. |
The platform uses a non-blocking, asynchronous profiling and execution pipeline for all premium actions:
flowchart TD
Input["Skill invocation"] --> Resolve["Resolve Skill Registry entry"]
Resolve --> ValidateInput["Validate input with Zod"]
ValidateInput --> Compose["Resolve declared MCP tool calls"]
Compose --> ExecuteTools["Execute tools in parallel"]
ExecuteTools --> Context["Build grounded Skill Context"]
Context --> Prompt["Render versioned prompt"]
Prompt --> LLM["Invoke LLMProvider"]
LLM --> ValidateOutput["Validate structured JSON output"]
ValidateOutput --> Persist["Persist execution, history, versions and audit"]
Persist --> Complete["Publish SkillCompleted and return output"]
ValidateInput -->|Invalid| Reject["Reject invocation"]
ValidateOutput -->|Invalid| Failed["Persist failure and publish SkillFailed"]
ExecuteTools -->|Failure| Failed
We provide a dedicated, premium MatchMesh Client SDK (matchmesh-sdk) to enable developers and autonomous AI agents to easily query MatchMesh reasoning services and call metered World Cup tools with automatic x402 USDC payment-signature handling.
graph TD
DeveloperApp[Developer App / AI Agent] --> SDK[MatchMeshClient]
SDK --> Auth[x402 Challenge Signer]
SDK --> Tools[Type-Safe Tool Calls]
SDK --> Adaptors[Framework Adaptors]
Adaptors --> Vercel[Vercel AI SDK Tools]
Adaptors --> LangChain[LangChain Dynamic Tools]
SDK --> API[MatchMesh API / MCP Server]
npm install matchmesh-sdk
# or
pnpm add matchmesh-sdkThe SDK automatically registers a developer session and wraps tool execution. When calling a metered premium tool, the SDK handles the x402 payment challenge, signs the challenge, and retries the request seamlessly:
import { MatchMeshClient } from "matchmesh-sdk";
const client = new MatchMeshClient({
walletAddress: "0x...",
privateKey: "your-x402-signing-key", // or custom signProof
baseUrl: "https://api.matchmesh.xyz"
});
// Call a tool. x402 payment challenge is resolved automatically!
const match = await client.tools.getMatch({
matchId: "11111111-1111-4111-8111-111111111111"
});Convert all MatchMesh tools directly into Vercel AI SDK compatible tool() format:
import { toVercelAITools } from "matchmesh-sdk";
import { generateText } from "ai";
const vercelTools = toVercelAITools(client);
const { text } = await generateText({
model: yourLLMModel,
tools: vercelTools,
prompt: "What is the live score for the match between Argentina and France?"
});Inject MatchMesh tools directly into your LangChain agents:
import { toLangChainTools } from "matchmesh-sdk";
import { createOpenAIFunctionsAgent, AgentExecutor } from "langchain/agents";
const langchainTools = toLangChainTools(client);
// Bind tools to agent executor...- Node.js
v22.0.0+& pnpm10.13.1 - Turborepo
v2.6.1β Monorepo pipeline orchestrator - Fastify
v5.6.2β High-performance HTTP server - TSyringe
v4.10.0β Dependency injection container - Prisma ORM
v6.19.0β Database migration and client generation - Zod
v3.25.76β Schema validation and type inference
- Next.js
16.2.10β App Router framework - React
19.2.0β Declarative view rendering - Tailwind CSS
v4.1.9β Modern utility-first CSS styling - Tanstack React Query
5.101.2β Server state synchronization - Lucide React
v0.454.0β Icon design set
- PostgreSQL
16β System of Record Database - Redis
7β High-speed caching and rate-limiting - Docker & Compose β Platform containerization
MatchMesh is built to support the Injective ecosystem:
- Keplr Injective Login: Authenticates developer identities on the
injective-1mainnet orinjective-888testnet. Resolves the Injective address to its EVM hex representation (0x...equivalent) via Keplr'sethereumHexAddressproperty to keep unified database mapping. - Settlement Engine: Tracks mock Circle CCTP deposits using the Injective chain environment parameters (
injectivedefault funding chain).
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| POST | /v1/platform/session |
Create or load developer workspace | Public |
| GET | /v1/platform/status |
Read live PostgreSQL, Redis, and CCTP health | Public |
| GET | /v1/platform/tools |
Get full list of registered MCP tools | Wallet Session |
| GET | /v1/platform/skills |
Get full list of Agent Skills | Wallet Session |
| POST | /v1/platform/tools/:tool/execute |
Execute an MCP tool (Free/Premium) | Wallet Session / x402 |
| POST | /v1/platform/skills/:skill/execute |
Execute an Agent Skill | Wallet Session / x402 |
| POST | /v1/platform/funding |
Deposit mock USDC funds via Circle CCTP | Wallet Session |
| GET | /v1/platform/dashboard |
Fetch current usage stats, balance, and charts | Wallet Session |
{
"services": [
{ "name": "Provider", "status": "configured", "detail": "api-football configured" },
{ "name": "Redis", "status": "operational", "latencyMs": 1, "detail": "cache" },
{ "name": "PostgreSQL", "status": "operational", "latencyMs": 79, "detail": "system of record" },
{ "name": "MCP", "status": "operational", "detail": "12 tools" },
{ "name": "x402", "status": "configured", "detail": "mock / injective" },
{ "name": "CCTP", "status": "configured", "detail": "mock / 1 networks" }
],
"timestamp": "2026-07-16T19:16:45.064Z"
}Here is the complete project structure for MatchMesh:
matchmesh/
βββ apps/
β βββ api/ # Fastify API Server
β β βββ src/
β β β βββ mcp/ # Model Context Protocol (MCP) server & routes
β β β β βββ mcp.controller.ts
β β β β βββ mcp.routes.ts
β β β βββ platform/ # Core developer platform orchestrator
β β β β βββ platform.service.ts
β β β βββ rest/ # REST routes (session, status, billing, wallet)
β β β β βββ platform.routes.ts
β β β βββ server.ts # Fastify main server entry point
β β β βββ validation-runner.ts # Core validator startup script
β β βββ package.json
β β βββ tsconfig.json
β βββ worker/ # Background Worker Process
β βββ src/
β β βββ index.ts # Worker process entry point
β βββ package.json
β βββ tsconfig.json
βββ frontend/ # Next.js Web Application
β βββ app/ # Next.js App Router Page Layouts
β β βββ (platform)/ # Developer Platform Dashboard & Console
β β β βββ analytics/page.tsx
β β β βββ billing/page.tsx
β β β βββ dashboard/page.tsx
β β β βββ docs/page.tsx
β β β βββ history/page.tsx
β β β βββ playground/page.tsx
β β β βββ settings/page.tsx
β β β βββ skills/page.tsx
β β β βββ status/page.tsx
β β β βββ tools/page.tsx
β β β βββ wallet/page.tsx
β β β βββ layout.tsx # Platform sidebar shell wrapper
β β βββ api/ # Serverless Next.js API Routes
β β β βββ platform/
β β β βββ [...path]/
β β β βββ route.ts # Backend API gateway proxy
β β βββ globals.css
β β βββ layout.tsx
β β βββ page.tsx # Landing home screen
β βββ components/ # UI components catalog
β β βββ landing/ # Landing pages (CTA, pricing, hero, navigation)
β β β βββ cta-section.tsx
β β β βββ hero-section.tsx
β β β βββ navigation.tsx
β β β βββ pricing-section.tsx
β β βββ platform/ # Platform dashboard layout elements
β β βββ platform-provider.tsx # Session context & Keplr logic
β β βββ platform-shell.tsx # Dashboard sidebar navigation
β β βββ playground-view.tsx # Live tool sandbox runner
β β βββ dashboard-view.tsx
β βββ lib/ # Frontend HTTP client & types
β β βββ platform-api.ts
β β βββ platform-types.ts
β βββ package.json
β βββ tailwind.config.ts
βββ packages/ # Shared Business Logic Monorepo Packages
β βββ adapters/ # Third-party implementations & adapters
β β βββ src/
β β βββ football-providers/ # API-Football data mapping adapter
β β βββ persistence/ # PostgreSQL Prisma repository mapping
β β βββ index.ts
β βββ agent-skills/ # 8 registry-backed Agent Skills
β β βββ src/
β β βββ skills/ # Outlines, comparisons, analysis skills
β β βββ skill-registry.ts
β β βββ index.ts
β βββ cctp/ # Mock Circle CCTP financial settlement
β β βββ src/
β β βββ cctp.service.ts
β β βββ index.ts
β βββ core/ # Domain models, entities, value objects, & ports
β β βββ src/
β β βββ domain/ # Football models (Fixture, standing, lineup)
β β βββ errors/
β β βββ index.ts
β βββ mcp-tools/ # 12 Model Context Protocol tools
β β βββ src/
β β βββ tools/ # JSON-RPC compliant schemas
β β βββ tool-registry.ts
β β βββ index.ts
β βββ shared/ # Base utility modules
β β βββ src/
β β βββ config/ # Environment schemas & Zod validators
β β βββ logging/
β βββ x402/ # x402 Challenge verification & metering
β βββ src/
β βββ x402.service.ts
β βββ index.ts
βββ prisma/ # Database Schemas & Migrations
β βββ schema.prisma # Relational database models
β βββ migrations/ # Migration history ledger
βββ infra/ # Infrastructure descriptor
β βββ docker-compose.yml # Multi-container orchestration config
βββ docs/ # Architectural details
βββ architecture.md
βββ prd.md
- Node.js:
v22.0.0or higher - pnpm:
10.13.1or higher - Docker Desktop (for containerized startup)
From the repository root:
# Clone environment variables template
cp .env.example .env
# Start database, caching, background worker, API server, and web frontend
docker compose --env-file .env -f infra/docker-compose.yml --profile web up --buildOpen http://localhost:3000 to access the MatchMesh console.
If you prefer to run services natively on your system:
docker compose -f infra/docker-compose.yml up postgres redis -d# Install package manager
corepack enable
# Install project dependencies
pnpm install --frozen-lockfile
# Generate Prisma Client & Run Database migrations
pnpm db:generate
pnpm exec prisma migrate deploy
# Start API server and Frontend in development mode
pnpm devOpen http://localhost:3000 to access the workspace.
Run validation suites to verify code compilation and check standard mock flows:
# Build workspace
pnpm build
# Run linting and TS typecheck
pnpm lint
pnpm typecheck
# Run test suites
pnpm test
pnpm db:validate
# Run core validation runner scripts
pnpm --filter @matchmesh/api exec tsx src/validation-runner.ts
pnpm --filter @matchmesh/api exec tsx src/x402-validation-runner.ts
pnpm --filter @matchmesh/api exec tsx src/cctp-validation-runner.ts
pnpm --filter @matchmesh/api exec tsx src/agent-skills-validation-runner.tsAll core validation tests pass successfully on the local development environment:
MATCHMESH AGENT SKILLS MANUAL VALIDATION
Case 1 β Match Summary
PASS: Match Summary returned structured output
Case 2 β Fantasy Assistant
PASS: Fantasy Assistant returned recommendations
Case 3 β Player Comparison
PASS: Player Comparison returned two structured profiles
Case 4 β Tactical Analysis
PASS: Tactical Analysis returned grounded sections
Case 5 β Invalid Skill
PASS: invalid skill rejected
Case 6 β Invalid Input
PASS: invalid input rejected
Case 7 β Structured Output Validation
PASS: arbitrary text rejected by Zod output schema
Case 8 β Execution History
PASS: 2 immutable execution history entries returned
Case 9 β Audit Log
PASS: 5 skill audit records persisted
ALL 9 AGENT SKILLS VALIDATION CASES PASSED
All environment variables are validated at startup. The complete template is available at .env.example. Key parameters include:
| Variable | Description | Default / Example |
|---|---|---|
DATABASE_URL |
PostgreSQL connection pool URL | postgresql://user:pass@host:5432/db |
REDIS_URL |
Redis connection URL | redis://localhost:6379 |
API_FOOTBALL_API_KEY |
RapidAPI API-Football credential | your-api-key |
X402_SIGNING_SECRET |
32+ char HMAC secret for challenge tokens | development_signing_secret_key |
X402_RECEIVER_ADDRESS |
Recipient wallet address for challenge fees | 0x7e5f4552091a69125d5dfcb7b8c265902939bd6 |
DEFAULT_FUNDING_CHAIN |
Primary network for CCTP balance mock | injective |
MATCHMESH_API_URL |
Upstream Fastify API URL for Next.js proxy | http://localhost:3001 |
- Backend Service (API/Worker): Deployed to Render (using the combined start command
pnpm exec prisma migrate deploy && node apps/worker/dist/index.js & node apps/api/dist/server.json a Free Web Service tier). - Frontend Console: Deployed to Vercel with the root directory set to
frontend, building via overridden commandsnpm installandnpm run build.
We welcome contributions to expand our football adapters, add new MCP tools, and integrate additional chains.
- Fork the Repository
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'feat: add amazing feature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE for more details.
MatchMesh β Empowering AI Agents with Sports Data
