Skip to content

iamomm-hack/MatchMesh

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

100 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

MatchMesh

MatchMesh Logo

MatchMesh

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.


πŸ“– Overview

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.

πŸš€ Injective Integration Details

This project is built specifically to highlight the synergy of decentralized micropayments, model context interoperability, and cross-chain settlement on Injective:

1. πŸͺͺ Injective Authentication & Keplr Integration

  • Integration: Users log in natively using the Keplr Wallet configured for the Injective network (injective-1 mainnet or injective-888 testnet).
  • Execution: The platform extracts the wallet’s EVM-compatible hex address representation (0x... equivalent) via Keplr's ethereumHexAddress property. This serves as the unified database account identifier for cross-chain transactions and ledger states.

2. πŸ”’ x402 Micropayments Protocol

  • 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 Required carrying 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.

3. πŸ’Έ Circle CCTP Settlement

  • 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.

4. πŸ› οΈ Model Context Protocol (MCP) Server

  • 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.

5. 🧠 Agent Skills Registry

  • 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.

6. πŸ“¦ Client SDK (matchmesh-sdk)

  • 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.

🎯 Philosophy: Why MatchMesh?

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.

✨ Features

  • πŸ› οΈ 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.

🧠 Agent Skills Registry

MatchMesh provides 8 pre-built Agent Skills that compose raw database/MCP actions into semantic reasoning workflows.

Skill Overview & Cost Metrics

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

Skill Dependency Graph

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
Loading

πŸ—οΈ Architecture

Layered System Design

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.

Execution Flow & Processing Pipeline

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
Loading

πŸ“¦ MatchMesh Client SDK

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.

SDK Architecture

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]
Loading

Installation

npm install matchmesh-sdk
# or
pnpm add matchmesh-sdk

Basic Initialization & Tool Execution

The 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"
});

AI Framework Integrations

Vercel AI SDK

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?"
});

LangChain

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...

πŸ’» Tech Stack

Backend & Core

  • Node.js v22.0.0+ & pnpm 10.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

Frontend & UI

  • 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

Infrastructure

  • PostgreSQL 16 β€” System of Record Database
  • Redis 7 β€” High-speed caching and rate-limiting
  • Docker & Compose β€” Platform containerization

⚑ Injective Synergy: On-Chain Integration

MatchMesh is built to support the Injective ecosystem:

  • Keplr Injective Login: Authenticates developer identities on the injective-1 mainnet or injective-888 testnet. Resolves the Injective address to its EVM hex representation (0x... equivalent) via Keplr's ethereumHexAddress property to keep unified database mapping.
  • Settlement Engine: Tracks mock Circle CCTP deposits using the Injective chain environment parameters (injective default funding chain).

🌐 API & MCP Reference

Core HTTP Endpoints

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

Sample Response: /v1/platform/status

{
  "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"
}

πŸ“ Repository Layout & Project Structure

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

πŸš€ Quick Start

1. Prerequisites

  • Node.js: v22.0.0 or higher
  • pnpm: 10.13.1 or higher
  • Docker Desktop (for containerized startup)

2. Run Containerized (Recommended)

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 --build

Open http://localhost:3000 to access the MatchMesh console.


3. Local Development (Manual Setup)

If you prefer to run services natively on your system:

A. Launch Data Services

docker compose -f infra/docker-compose.yml up postgres redis -d

B. Build & Run Application

# 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 dev

Open http://localhost:3000 to access the workspace.


4. Verification & Testing

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.ts

Manual Validation Reports

All 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

πŸ”§ Configuration Reference

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

🚒 Production Deployment

  • 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.js on a Free Web Service tier).
  • Frontend Console: Deployed to Vercel with the root directory set to frontend, building via overridden commands npm install and npm run build.

🀝 Contributing

We welcome contributions to expand our football adapters, add new MCP tools, and integrate additional chains.

  1. Fork the Repository
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'feat: add amazing feature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

πŸ“„ License

Distributed under the MIT License. See LICENSE for more details.


MatchMesh β€” Empowering AI Agents with Sports Data

About

MatchMesh is an MCP-native, pay-per-use football data and AI orchestration platform. Built on Injective with Circle CCTP settlement and x402 cryptographic micropayments, it exposes structured sports reasoning skills and real-time tools for autonomous AI agents, backed by a dedicated TypeScript SDK (matchmesh-sdk).

Resources

License

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages