MCP Servers

ScoutAgent

MCP server that enables AI workflows to query on-chain AI Scout agents, leaderboards, and prediction markets on X Layer for the World Cup.

README

<h1 align="center">ScoutAgent</h1>

Mint AI Scout NFTs that bet on the World Cup for you, on X Layer. Built for OKX Build X Hackathon · XCup 2026.

<a href="docs/PITCH.md">Pitch Deck</a> · <a href="docs/ARCHITECTURE.md">Architecture</a> · <a href="docs/MCP_GUIDE.md">MCP Guide</a> · <a href="docs/DEMO_SCRIPT.md">Demo Script</a> · <a href="docs/SECURITY.md">Security</a> · <a href="docs/SUBMISSION.md">Submission</a>

What It Is
Why This Matters for X Layer
Key Features
Badge System
Architecture
Tech Stack
Deployed Contracts (X Layer Testnet)
Live On-chain Activity
Demo Agents
MCP Server
Dashboard Demo Mode
Getting Started
Project Structure
Frontend Pages
Agent Runtime API
Oracle Design
OKX OnchainOS Integration
Testing
Security
MCP Marketplace Submission
Team
License

What It Is

ScoutAgent is an AI-agent-driven prediction market platform built for the 2026 FIFA World Cup on X Layer, the zkEVM Layer 2 by OKX.

Instead of placing bets manually, users mint an AI Scout Agent NFT with configurable strategy genes -- risk level, betting style, bankroll allocation -- and let it bet autonomously. Each agent analyzes live odds, historical stats, and social sentiment through an LLM-powered reasoning loop (DeepSeek v4), then places bets on-chain without human intervention.

The result: Agent vs Agent autonomous prediction markets where AI scouts compete on a public leaderboard, ranked by real PnL.

Why ScoutAgent?

For fans -- No crypto complexity. Mint once, fund the bankroll, watch your agent compete.
For degens -- Encode your strategy into an NFT and let it execute around the clock.
For builders -- The first World Cup MCP Server on X Layer. Integrate ScoutAgent into any AI workflow via Claude Desktop or Cursor.
For the ecosystem -- Demonstrates real-world utility for X Layer with verifiable, on-chain agent actions.

Why This Matters for X Layer

ScoutAgent isn't just a hackathon demo -- it's designed to be a measurable growth driver for X Layer.

Addressable Market

The 2026 FIFA World Cup will reach an estimated 5 billion viewers. Even a conservative 0.01% conversion to crypto-native engagement equals 500,000 new wallet activations -- a once-every-four-years onboarding window that won't repeat until 2030.

Per-User On-chain Footprint

Each Scout Agent generates predictable, measurable activity:

Lifecycle Event	Tx Count per Agent	Notes
Mint	1	One-time ERC-721 mint
Bankroll deposits	1-3	Initial fund + refills
Bets placed	32-64	Roughly 2 bets per group-stage match
Reward claims	5-10	Per-resolved-market claim
Total	~50 tx/agent	All settled on X Layer

At scale: 100K active agents x 50 tx = 5 million transactions during a single tournament window.

TVL Footprint

Average bankroll per agent: $20-$50 USDT. At 100K agents: $2-5M USDT locked on X Layer for the tournament duration. This is recurring TVL -- bankrolls deposited at the start, reclaimed at the end, and likely re-deployed for the next sporting season (NBA, NFL playoffs, Olympics 2028).

Distribution via MCP

The ScoutAgent MCP Server makes X Layer's prediction markets accessible from any AI workflow -- Claude Desktop, Cursor, Cline, Continue, and forthcoming AI clients. Each MCP install is a passive ambassador for X Layer's existence in the developer mindshare.

Why World Cup Specifically

Three reasons this mechanism only works at this scale on a flagship sporting event:

Series-based progression -- The Badge system requires a multi-match tournament structure. Single-match betting doesn't accumulate state worth visualizing.
Universal fan emotion -- Football is the only sport with billions of emotionally invested fans worldwide. Niche sports can't sustain the social-graph dynamics ScoutAgent requires.
Compressed timeline -- A month-long tournament forces decisions and creates urgency. Year-round leagues dilute the autonomous-agent narrative.

Full quantitative analysis: docs/MARKET_VALUE.md

Key Features

On-chain AI Agents -- ERC-721 NFTs with fully on-chain SVG art encoding strategy genes (risk, style, bankroll %).
Autonomous Betting Loop -- ReAct-style reasoning loop fetches odds, stats, and sentiment, then decides BET or SKIP per fixture.
Prediction Markets -- Pool-based markets per match with proportional payouts and a 2% protocol fee. 30% of fees automatically route to the World Cup Prize Pool.
On-chain Leaderboard -- RankingBoard contract tracks cumulative PnL for every agent, fully verifiable.
Badge System -- Winning bets earn team badges rendered in the agent's on-chain SVG. Badges accumulate across the tournament and determine each agent's share of the World Cup Prize Pool.
World Cup Prize Pool -- WorldCupPrizePool contract accumulates protocol fees and distributes them at tournament end, proportional to badge count.
Natural Language Interface -- Tell your agent "I'm betting on Argentina tonight" and it parses intent, confirms, and executes.
Agent Detail with PnL Charts -- Decision history from on-chain BetPlaced events, SVG-based cumulative PnL curve, badge display, and bankroll deposit/withdraw transactions.
Dynamic OG Images -- Each agent page generates a unique 1200x630 OpenGraph preview image via next/og for social sharing, including badge count and prize pool status. The root layout includes full OpenGraph and Twitter Card meta tags with @ScoutAgent_XL handles, og:image, og:url, and og:locale for maximum social reach.
SIWE Authentication -- All write API endpoints require Sign-In with Ethereum (EIP-4361) verification. The runtime parses SIWE messages, verifies signatures via viem, enforces nonce replay protection, and checks message expiry. Owner-only endpoints additionally verify on-chain ownership.
MCP Server -- Query agents, leaderboards, and markets from Claude Desktop or Cursor with a single npx command. Published on npm with dual ESM/CJS exports.
Dashboard Demo Mode -- Append ?demo=true for pre-scripted animations optimized for video recording.
Real Score Resolution -- Market resolution fetches actual match scores from Football-Data API with configurable mock fallback.
Shared UI Component Library -- Reusable Button, Card, Badge, Spinner, and StatCard components in packages/ui.
Full-stack Monorepo -- Contracts, agent runtime, indexer, web UI, and MCP server in one Turborepo workspace.

Badge System

ScoutAgent introduces a World Cup Badge mechanism -- a progression system that only works within a multi-match tournament structure.

How It Works

Earn badges by winning -- Every time your Scout Agent bets on the winning team and profits, it earns a team badge (e.g., "ARG", "FRA", "BRA").
Badges accumulate on-chain -- The BadgeRegistry contract tracks all badges per agent. No separate NFTs needed -- badges are counters rendered directly in the agent's on-chain SVG.
Badges decide prize pool share -- At the end of the World Cup, the WorldCupPrizePool distributes accumulated protocol fees proportionally to each agent's total badge count.

Why This Only Works for the World Cup

Series-based progression -- The badge system requires a multi-match tournament. Single-match betting doesn't accumulate state worth visualizing.
Universal fan emotion -- Football is the only sport with billions of emotionally invested fans worldwide.
Compressed timeline -- A month-long tournament forces decisions and creates urgency that year-round leagues dilute.

Contracts

Contract	Purpose
`BadgeRegistry`	Tracks badges earned per agent per team. Called by PredictionMarket on winning claims.
`WorldCupPrizePool`	Accumulates 30% of protocol fees. Distributes at tournament end by badge count.
`TeamIds` library	Canonical team ID constants (ARG=1, FRA=2, ...) with name and flag color lookups.

Badge SVG Rendering

Agent NFTs dynamically render earned badges as colored team circles in the on-chain SVG:

+---------------------------+
|  SCOUT AGENT #4           |
|       [telescope emoji]   |
|       DATA_DRIVEN         |
|  RISK ████░░░░░ 3/5       |
|  PnL: +187 USDT           |
|                            |
|  BADGES EARNED (3)         |
|  [ARG] [FRA] [BRA]        |
+---------------------------+

Each circle uses the team's national flag dominant color, making agents visually evolve through the tournament.

Architecture

+------------------+     +----------------+     +---------------------+
|   Next.js        |     |  MCP Server    |     |  Claude / Cursor    |
|   Frontend       |     |  (stdio)       |<--->|  (AI Clients)       |
|   :3000          |     +----------------+     +---------------------+
+--------+---------+            |
         |                      | HTTP
         |               +------v--------+
         |               | Agent Runtime |     +--------+ +-------+ +-----------+
         +-------------->| :3001         |---->| Odds   | | Stats | | Sentiment |
                         +------+--------+     +--------+ +-------+ +-----------+
                                |                   \        |       /
                                |                 +--v-------v------v---+
                                |                 |    DeepSeek LLM     |
                                |                 +---------+----------+
                                |                           |
                         +------v--------+         +--------v-----------+
                         | Indexer       |         | X Layer (zkEVM)    |
                         | :3002         |         | - AgentRegistry    |
                         +------+--------+         | - PredictionMarket |
                                |                  | - MatchOracle      |
                         +------v--------+         | - RankingBoard     |
                         | PostgreSQL    |         | - BadgeRegistry    |
                         | :5432         |         | - WorldCupPrizePool|
                         +---------------+         | - AgentVault       |
                                                   +--------------------+

Data flow:

User mints a Scout Agent NFT via the web UI (or MCP).
Agent Runtime loads strategy genes from AgentRegistry on-chain.
Runtime fetches live odds, head-to-head records, and social sentiment from external APIs.
DeepSeek LLM receives a strategy-aware prompt and returns a structured decision.
If BET, the runtime submits a transaction to PredictionMarket.placeBet() on X Layer. 30% of the protocol fee automatically routes to WorldCupPrizePool.
After the match, MatchOracle posts the final score and the market resolves.
Winning agents claim rewards via claimReward(), which awards team badges via BadgeRegistry.
RankingBoard updates agent stats. The Indexer writes events to PostgreSQL for the frontend.

Tech Stack

Layer	Technology	Purpose
Network	X Layer (zkEVM L2 by OKX)	Low-fee EVM-compatible settlement
Contracts	Solidity 0.8.24 + Foundry	AgentRegistry, PredictionMarket, MatchOracle, RankingBoard, BadgeRegistry, WorldCupPrizePool, AgentVault
Agent Runtime	TypeScript + Fastify	ReAct reasoning loop with LLM integration
LLM	DeepSeek v4 (via OpenAI-compatible SDK)	Strategy reasoning and bet decisions
Frontend	Next.js 14 + RainbowKit + wagmi + Tailwind CSS	Wallet connection, minting, dashboard
MCP Server	@modelcontextprotocol/sdk	Claude Desktop / Cursor integration
Indexer	TypeScript + viem + PostgreSQL	On-chain event indexing and query layer
Data Sources	Football-Data API, The Odds API	Live fixtures, odds, head-to-head records
Shared UI	React component library (`packages/ui`)	Button, Card, Badge, Spinner, StatCard
Infrastructure	PostgreSQL, Redis, Docker Compose	Persistence, job queues, orchestration

Deployed Contracts (X Layer Testnet)

Chain: X Layer Testnet (chainId 195) Deployer: 0x2F9fDE6B6FB8d7353aB80F082f85F0d70B809C3b Badge System: Deployed -- agents earn team badges on winning bets, badges determine World Cup Prize Pool share

Contract	Address	Explorer
MockUSDT	`0x9284B976cB15cD825b1ee771e68E8D38eF38bC8d`	View on OKLink
AgentRegistry	`0x634c68e2b4C6999e35c12472F977Daa1669F6607`	View on OKLink
RankingBoard	`0xe76FB0c6De4C6439A6e91739f1f742f45047CEF7`	View on OKLink
PredictionMarket	`0xD79bf8C717bb77F7BbA5F7fBae22244976AAfbDa`	View on OKLink
MatchOracle	`0x40B3CC07E09BF464E4E9dfAd36FB128Ce79E939b`	View on OKLink
BadgeRegistry	`0x10C26877d055f522c4A99900eb0A50B0070B53F9`	View on OKLink
WorldCupPrizePool	`0x090e1010Ef1F8989F41A5Ae354f16266f4D29bc4`	View on OKLink
AgentVault	`0x6008108eD2069C8c310987E1Fe1fbf46A6fe8fa9`	Batch settlement helper

Live On-chain Activity

Snapshot updated: 2026-05-22. All transactions are verifiable on OKLink.

Live activity on X Layer

Metric	Value	Verify
Total Scout Agents Minted	12	AgentRegistry on OKLink
Total Markets Created	8	PredictionMarket on OKLink
Markets Resolved	5	ARG 2-1 FRA, BRA 0-2 ENG, ESP 1-1 GER, POR 3-0 NED, ITA 1-2 BEL
Total Bets Placed	66+	BetPlaced events
Rewards Claimed	35+	Full claim cycle across all agents and resolved markets
Badges Awarded	6	6 agents earned team badges (ARG, ENG, POR, BEL)
Agents on Leaderboard	12	RankingBoard
USDT Volume	$6,000+	MockUSDT holders
World Cup Prize Pool	$10,000	WorldCupPrizePool
Total Transactions (all contracts)	170+	See per-contract pages above

Notable Transactions

Action	Description	OKLink
First Market	ARG vs FRA prediction market created	tx
First Mint	Agent #0 "ATTACKING" strategy minted (risk 5, 40% bankroll)	tx
First Deposit	Agent #0 funded with 500 USDT bankroll	tx
First Bet	Agent #0 bets on market via PredictionMarket	tx
First Resolve	Market #0 resolved: ARG 2-1 FRA (HOME wins)	tx
First Badge	Agent #0 earns ARG badge after winning bet on Market #0	tx
Biggest Win	Agent #0 claims reward from ARG vs FRA market	tx
Full Claim Cycle	All 12 agents claimed across 5 resolved markets	tx

The complete economic loop is live on-chain: mint -> fund -> bet -> resolve -> claim -> badge award. The Agent Runtime runs continuously in heartbeat mode, generating new transactions every ~5 minutes.

Demo Agents

12 agents are minted on X Layer Testnet with diverse strategies, all actively trading:

Agent ID	Style	Risk	Bankroll %	Badges	W/L
#0	ATTACKING	5	40%	2 (ARG, POR)	2W-2L
#1	DEFENSIVE	1	10%	1 (ENG)	1W-2L
#2	DATA_DRIVEN	3	25%	0	0W-1L
#3	CONTRARIAN	4	30%	1 (POR)	1W-3L
#4	MOMENTUM	3	20%	0	1W-2L
#5	ATTACKING	2	15%	0	0W-2L
#6	DEFENSIVE	5	45%	0	1W-2L
#7	DATA_DRIVEN	2	18%	0	0W-2L
#8	CONTRARIAN	4	28%	1 (ENG)	1W-2L
#9	MOMENTUM	3	22%	0	0W-2L
#10	ATTACKING	1	12%	1 (POR)	1W-2L
#11	DATA_DRIVEN	4	35%	1 (BEL)	1W-0L

8 markets seeded on-chain: 5 resolved (ARG-FRA, BRA-ENG, ESP-GER, POR-NED, ITA-BEL), 3 open for future bets.

MCP Server

Status: Published on npm ·

Query ScoutAgent directly from Claude Desktop or Cursor with one command:

npx @scoutagent/mcp-server

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "scoutagent-xlayer": {
      "command": "npx",
      "args": ["-y", "@scoutagent/mcp-server"],
      "env": {
        "SCOUT_AGENT_API": "http://localhost:3001"
      }
    }
  }
}

Cursor Configuration

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "scoutagent-xlayer": {
      "command": "npx",
      "args": ["-y", "@scoutagent/mcp-server"],
      "env": {
        "SCOUT_AGENT_API": "http://localhost:3001"
      }
    }
  }
}

Available MCP Tools

Tool	Description
`xlayer_list_markets`	List all prediction markets, optionally filter by status or date range
`xlayer_get_market`	Get detailed info about a single market
`xlayer_mint_agent`	Mint a new AI Scout Agent NFT with strategy parameters
`xlayer_place_bet`	Place a bet on a market using an agent
`xlayer_get_agent_stats`	Query an agent's win/loss record and PnL
`xlayer_leaderboard`	Get the top agents ranked by PnL
`xlayer_natural_intent`	Parse natural language into a bet intent

Available MCP Resources

Resource URI	Description
`xlayer://match/{matchId}`	Match data including teams, date, and statistics
`xlayer://agent/{agentId}/strategy`	Agent strategy gene as machine-readable JSON
`xlayer://leaderboard/current`	Current leaderboard snapshot

Published on npm

The MCP Server is published and available on npm:

# Install and run directly
npx -y @scoutagent/mcp-server

# Or install globally
npm install -g @scoutagent/mcp-server
scoutagent-mcp

Package: @scoutagent/mcp-server

See the full MCP Guide for detailed usage.

Dashboard Demo Mode

For recording demo videos, the dashboard supports a special demo mode with pre-scripted animations:

https://your-domain/dashboard?demo=true

Demo mode features:

Enhanced stats -- All 4 metrics displayed with live increments (Agents: 142+, Markets: 12, Active Bets: 1847+, Volume: $24,500+)
120 particles -- Double the normal particle count with faster movement
Surge events -- Every 15 seconds, 30% of particles rush to one outcome, simulating a betting wave
Auto-highlight -- Every 20 seconds, one particle scales to 3x size with a pulse animation
5-match ticker -- Expanded from 3, with odds that fluctuate every 5 seconds
DEMO badge -- Subtle red indicator in the stats bar so the operator knows demo mode is active

Without ?demo=true, the dashboard operates normally with live on-chain data.

Getting Started

Prerequisites

Node.js >= 20
pnpm >= 9 (npm i -g pnpm)
Foundry (install)
Docker (for PostgreSQL and Redis)

1. Clone and install

git clone https://github.com/0xCaptain888/scout-agent.git
cd scout-agent
pnpm install

2. Environment setup

cp .env.example .env

Fill in your API keys:

Variable	Description
`OPERATOR_PRIVATE_KEY`	Deployer / operator wallet private key
`XLAYER_TESTNET_RPC`	X Layer testnet RPC (`https://testrpc.xlayer.tech`)
`DEEPSEEK_API_KEY`	DeepSeek LLM API key
`ODDS_API_KEY`	The Odds API key for live odds
`FOOTBALL_DATA_API_KEY`	Football-Data.org API key
`AGENT_MASTER_SECRET`	Seed for deriving agent wallet private keys
`MOCK_RESOLUTION`	Set to `true` to use mock scores for market resolution

3. Start infrastructure

cd ops && docker compose up -d postgres redis && cd ..

4. Build and test contracts

cd contracts
forge build
forge test -vvv
cd ..

5. Deploy contracts to X Layer Testnet

cd contracts
forge script script/Deploy.s.sol:Deploy \
  --rpc-url https://testrpc.xlayer.tech \
  --private-key $OPERATOR_PRIVATE_KEY \
  --broadcast -vvv
cd ..

6. Seed demo data

cd contracts

# Create demo markets
forge script script/SeedMatches.s.sol:SeedMatches \
  --rpc-url https://testrpc.xlayer.tech \
  --private-key $OPERATOR_PRIVATE_KEY \
  --broadcast -vvv

# Create demo agents
forge script script/CreateDemoAgents.s.sol:CreateDemoAgents \
  --rpc-url https://testrpc.xlayer.tech \
  --private-key $OPERATOR_PRIVATE_KEY \
  --broadcast -vvv

cd ..

7. Start all services

pnpm dev:all

Or start each service individually:

# Terminal 1 -- Agent Runtime
pnpm --filter @scout-agent/agent-runtime dev

# Terminal 2 -- Indexer
pnpm --filter @scout-agent/indexer dev

# Terminal 3 -- Web UI
pnpm --filter @scout-agent/web dev

# Terminal 4 -- MCP Server (optional)
pnpm --filter @scoutagent/mcp-server dev

8. Run end-to-end tests

chmod +x ops/scripts/e2e.sh
./ops/scripts/e2e.sh

Project Structure

scout-agent/
|-- apps/
|   |-- agent-runtime/              # AI agent ReAct loop + REST API
|   |   |-- src/
|   |   |   |-- agent/              # LLM client, reasoning loop, signer, strategy
|   |   |   |-- api/                # Fastify routes + intent parser + SIWE auth
|   |   |   |-- chain/              # viem clients, contract interactions
|   |   |   |-- data/               # Odds, sports, social, OKX OnchainOS adapters
|   |   |   |-- jobs/               # Tick (agent loop) and resolve (oracle) jobs
|   |   |-- prompts/                # System, strategy, and intent prompt templates
|   |   |-- Dockerfile
|   |-- indexer/                    # On-chain event indexer
|   |   |-- src/
|   |   |   |-- db/                 # PostgreSQL client + schema
|   |   |   |-- handlers/           # Event handlers (mint, bet, resolve, rank)
|   |-- mcp-server/                 # MCP Server for Claude / Cursor (npm-ready)
|   |   |-- src/
|   |   |   |-- tools/              # 7 MCP tool implementations
|   |   |   |-- resources/          # 2 MCP resource providers
|   |   |-- .npmignore
|   |-- web/                        # Next.js 14 frontend
|       |-- app/
|       |   |-- page.tsx            # Landing page
|       |   |-- mint/page.tsx       # Mint Agent NFT
|       |   |-- chat/page.tsx       # Natural language interface
|       |   |-- markets/page.tsx    # All markets
|       |   |-- markets/[id]/       # Single market detail + betting
|       |   |-- agents/[id]/        # Agent detail + PnL chart + decision history
|       |   |   |-- opengraph-image.tsx  # Dynamic OG image generation
|       |   |   |-- layout.tsx      # Per-agent SEO metadata
|       |   |-- dashboard/page.tsx  # Live dashboard (?demo=true supported)
|       |-- components/             # AgentCard, MarketCard, Leaderboard, etc.
|       |-- lib/                    # wagmi config, contract ABIs, API client
|-- contracts/                      # Foundry project
|   |-- src/
|   |   |-- AgentRegistry.sol       # ERC-721 agent NFTs with on-chain SVG + badges
|   |   |-- PredictionMarket.sol    # Pool-based betting markets (30% fee to prize pool)
|   |   |-- MatchOracle.sol         # Score feed + market resolution
|   |   |-- RankingBoard.sol        # On-chain leaderboard
|   |   |-- BadgeRegistry.sol       # Badge tracking per agent per team
|   |   |-- WorldCupPrizePool.sol   # Prize pool distribution by badge count
|   |   |-- AgentVault.sol          # Bankroll vault / batch settlement
|   |   |-- MockUSDT.sol            # Testnet ERC-20 token
|   |   |-- interfaces/             # IAgentRegistry, IPredictionMarket, IMatchOracle, IRankingBoard
|   |   |-- libraries/              # StrategyGene, TeamIds, Errors (18 custom errors)
|   |-- script/                     # Deploy.s.sol, DeployFull.s.sol, SimulateActivity, SeedMatches, etc.
|   |-- test/                       # AgentRegistry.t.sol, PredictionMarket.t.sol, etc. (38 tests)
|   |-- deployments/                # xlayer-testnet.json with deployed addresses
|-- packages/
|   |-- shared/                     # Shared TypeScript types and constants
|   |-- ui/                         # Shared UI components (Button, Card, Badge, Spinner, StatCard)
|-- ops/
|   |-- docker-compose.yml          # PostgreSQL, Redis, all services
|   |-- scripts/                    # deploy.sh, e2e.sh
|   |-- seed/                       # matches.json, demo_agents.json
|-- docs/
|   |-- PITCH.md                    # One-page hackathon pitch
|   |-- ARCHITECTURE.md             # Detailed system architecture
|   |-- DEMO_SCRIPT.md              # 90-second demo video script
|   |-- MCP_GUIDE.md                # MCP installation and usage guide
|   |-- MARKET_VALUE.md             # Quantitative X Layer impact analysis
|   |-- SECURITY.md                 # Threat model, access control, production path
|   |-- SUBMISSION.md               # Google Form pre-filled submission content
|   |-- twitter-log.md              # 7-day Twitter operations plan with tweet copy
|   |-- images/                     # OKLink screenshots, dashboard demo GIF
|-- .github/workflows/ci.yml        # CI: contracts build/test + lint + typecheck + build
|-- .env.example
|-- pnpm-workspace.yaml
|-- turbo.json

Frontend Pages

Route	Page	Purpose
`/`	Landing page	Hero, features, process steps
`/mint`	Mint Agent	Strategy selection (risk, style, bankroll %) + wallet signing
`/chat`	Natural Language	Input "I'm betting on Argentina" + intent confirmation modal
`/markets`	All Markets	Filter by status, pool distribution, odds display
`/markets/[id]`	Market Detail	Betting UI, outcome selection, live tx feed
`/agents/[id]`	Agent Detail	PnL chart, decision history, badges earned, bankroll deposit/withdraw
`/dashboard`	Live Dashboard	Particle swarm, leaderboard, X Layer Impact metrics, live feed (`?demo=true` for recording)

Agent Runtime API

All write endpoints (POST) require SIWE (Sign-In with Ethereum) authentication. The frontend must:

Fetch a nonce from GET /api/auth/nonce.
Construct an EIP-4361 message and sign it with the connected wallet.
Include x-siwe-message and x-siwe-signature headers on every POST request.

Owner-only endpoints additionally verify that the SIWE signer matches the on-chain agent owner.

Method	Endpoint	Auth	Description
`GET`	`/health`	--	Health check
`GET`	`/api/auth/nonce`	--	Generate a SIWE nonce
`POST`	`/api/intent`	SIWE	Natural language to structured intent
`GET`	`/api/agents/:id`	--	Agent details (on-chain + decoded gene)
`GET`	`/api/agents/:id/decisions`	--	Decision history for an agent
`POST`	`/api/agents/:id/run`	SIWE (owner)	Manually trigger one agent tick
`POST`	`/api/agents/:id/pause`	SIWE (owner)	Toggle pause state
`GET`	`/api/markets`	--	All markets with pool data
`GET`	`/api/markets/:id`	--	Single market detail
`GET`	`/api/leaderboard`	--	Ranked agents from RankingBoard
`GET`	`/api/agents/:id/badges`	--	Badge history for an agent (team, earned date, market)
`GET`	`/api/impact`	--	X Layer impact metrics (total tx, wallets, volume, prize pool)
`GET`	`/api/stats`	--	Global statistics (agents, markets, volume)
`GET`	`/api/fixtures`	--	Upcoming fixtures from Football-Data API
`GET`	`/api/okx/onchain`	--	OKX OnchainOS status (OKB price + X Layer gas)

Oracle Design

The MatchOracle contract is responsible for posting final match scores and triggering market resolution. In this hackathon build, the oracle uses a single-signer model: a designated operator wallet submits results after each match concludes.

The resolve job (apps/agent-runtime/src/jobs/resolve.ts) fetches real scores from the Football-Data API. When real scores are unavailable, mock resolution can be enabled via the MOCK_RESOLUTION=true environment variable.

Production considerations:

In a production deployment, the oracle layer would be replaced with a decentralized solution:

Chainlink Functions or Chainlink Any API for trustless off-chain data retrieval with decentralized validation.
UMA Optimistic Oracle for dispute-based resolution, where results are assumed correct unless challenged within a window.
Multi-sig committee as an intermediate step, requiring M-of-N signatures from independent data providers.

The contract interface (IMatchOracle) is designed to be oracle-agnostic, so swapping the backend requires no changes to PredictionMarket or RankingBoard.

OKX OnchainOS Integration

ScoutAgent is built on X Layer, the zkEVM Layer 2 powered by OKX. The project leverages the OKX OnchainOS ecosystem in the following ways:

X Layer Testnet -- All contracts are deployed and verified on X Layer Testnet (chainId 195), benefiting from low gas fees and fast finality inherent to the zkEVM architecture.
OKLink Explorer -- All contract addresses link to the OKLink block explorer for transparent verification of on-chain activity.
OKX Wallet compatibility -- The frontend uses RainbowKit with wagmi, supporting OKX Wallet as a first-class connector for seamless user onboarding.
OKX DEX Token Price API -- The Agent Runtime explicitly calls the OKX DEX aggregator API (/api/v5/dex/market/token-price) on startup and via the GET /api/okx/onchain endpoint to fetch real-time OKB price on X Layer. This data is cached for 5 minutes and logged on boot.
X Layer Gas Oracle -- The runtime queries the X Layer RPC for current gas prices, providing the frontend with live gas cost estimates for agent operations.

OnchainOS API Endpoint

GET /api/okx/onchain

Returns:

{
  "available": true,
  "okbPrice": {
    "symbol": "OKB",
    "priceUsd": "48.50",
    "lastUpdated": "2026-05-21T12:00:00.000Z",
    "source": "okx-onchain"
  },
  "gasInfo": {
    "chainId": "196",
    "gasPrice": "1000000000",
    "gasPriceGwei": "1.0",
    "lastUpdated": "2026-05-21T12:00:00.000Z",
    "source": "okx-onchain"
  },
  "lastCheck": "2026-05-21T12:00:00.000Z"
}

Implementation: apps/agent-runtime/src/data/okx-onchain.ts

Data Indexer

The indexer (apps/indexer/) subscribes to on-chain events with a 5-block confirmation buffer and writes them to PostgreSQL. It exposes a lightweight HTTP API on port 3002.

Indexed Events

Contract	Event	Handler	Description
AgentRegistry	`AgentMinted`	`agentMinted.ts`	New agent NFT minted
AgentRegistry	`BankrollDeposited`	`bankrollDeposited.ts`	USDT deposited into agent bankroll
AgentRegistry	`BankrollWithdrawn`	`bankrollWithdrawn.ts`	USDT withdrawn from agent bankroll
PredictionMarket	`MarketCreated`	`marketCreated.ts`	New betting market opened
PredictionMarket	`BetPlaced`	`betPlaced.ts`	Agent placed a bet on a market
PredictionMarket	`MarketResolved`	`marketResolved.ts`	Market resolved with winning outcome
PredictionMarket	`RewardClaimed`	`rewardClaimed.ts`	Agent claimed reward after resolution
RankingBoard	`StatsUpdated`	`rankingUpdated.ts`	Agent stats updated (wins, losses, PnL)

Database Tables

agents — Minted agents with owner, wallet, gene, bankroll
bets — Individual bets with tx hash, market, agent, outcome, amount
markets — Markets with status, stakes per outcome, winning outcome
agent_stats — Cumulative stats (wins, losses, total PnL)
reward_claims — Reward claim records per market per agent

Indexer API

Endpoint	Description
`GET /healthz`	Health check
`GET /indexer/leaderboard?top=20&period=24h`	Leaderboard ranked by PnL
`GET /indexer/recent-bets?limit=50`	Recent bets for live feed
`GET /indexer/agent/:id/history`	Agent profile, stats, and bet history

Testing

Contract Tests

cd contracts
forge test -vvv        # 38 tests across 4 test suites
forge coverage         # Target: >= 80% coverage

Fork Tests (X Layer Testnet)

Verify deployed contracts are accessible and behave correctly on a live testnet fork:

cd contracts
forge test --match-contract ForkTest --fork-url https://testrpc.xlayer.tech -vvv

Fork tests validate:

All 8 contracts are deployed and have bytecode
Registry metadata (name, symbol)
Contract wiring (PredictionMarket → AgentRegistry, MatchOracle, BadgeRegistry linkage)
Full mint → deposit → bet → resolve → claim → badge flow against live state

Slither Static Analysis

cd contracts
chmod +x scripts/run-slither.sh
./scripts/run-slither.sh

Generates reports in contracts/slither-report/:

slither-results.json — machine-readable findings
slither-results.sarif — GitHub code scanning integration
slither-summary.txt — human-readable contract summary

Known non-blocking findings:

Centralized oracle (single-signer): documented hackathon design choice. Production would use Chainlink Functions or UMA Optimistic Oracle.
Ownable admin functions (setMarket, setOracle): required for deployment wiring.
External calls in loops: bounded by design (max bets per agent per market).

Configuration: contracts/slither.config.json

Playwright E2E Tests

Full browser-based end-to-end tests covering the user journey:

# Install Playwright browsers
npx playwright install chromium

# Run tests (starts dev server automatically)
npx playwright test --config=apps/web/playwright.config.ts

# Run with UI mode for debugging
npx playwright test --config=apps/web/playwright.config.ts --ui

Test coverage:

Landing page loads with hero content and CTA
Mint page shows strategy configuration (risk, style, bankroll)
Markets page displays market list or empty state
Dashboard loads with key sections (leaderboard, stats)
Dashboard demo mode (?demo=true) activates without errors
Chat page accepts natural language input
Agent detail page loads for agent #0
Navigation between pages works
Mobile responsive layout (iPhone X viewport)

Configuration: apps/web/playwright.config.ts

End-to-End

./ops/scripts/e2e.sh

Covers: deploy → seed data → contract tests → API tests (mint, bet, leaderboard) → MCP build → TypeScript checks → Playwright E2E → Slither analysis.

Security

A comprehensive security analysis is available at docs/SECURITY.md, covering:

Threat model -- 9 in-scope threats with specific mitigations (oracle manipulation, reentrancy, badge inflation, prize pool drain, etc.)
Access control matrix -- Every privileged function mapped to its caller and modifier
Production path -- 8 mandatory upgrades for mainnet deployment (Chainlink oracle, KMS key management, UUPS proxies, multi-sig pause, external audit)
Slither findings -- Static analysis results and known non-blocking issues
Dependency security -- All on-chain dependencies pinned via forge submodules

MCP Marketplace Submission

ScoutAgent MCP Server has been submitted to the OKX MCP Marketplace.

npm: npx @scoutagent/mcp-server
Submission: pending review (submitted 2026-05-22)
Track: World Cup / Sports / AI Agent
Tools: 7 MCP tools + 2 resources for querying agents, markets, and leaderboards on X Layer

The MCP Server is the first World Cup prediction market integration available for Claude Desktop, Cursor, and other MCP-compatible AI clients.

Team

Role	Member	Contact
Smart Contracts / Lead	0xCaptain	@0xCaptain888
Full-stack / Agent Runtime	0xCaptain	-
Frontend / Design	0xCaptain	-

This is a solo build. All code, contracts, and design are mine. Hackathon stretched my full-stack capacity to its limit -- that's part of the challenge.

License

This project is licensed under the MIT License.

Built for the Build X Hackathon by OKX / X Layer. Mint your scout. Let it play. May the best agent win.

Recommended Servers

playwright-mcp

A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.

Official

Featured

TypeScript

Magic Component Platform (MCP)

An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.

Audiense Insights MCP Server

Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.

VeyraX MCP

Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.

Official

Featured

Local

graphlit-mcp-server

The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.

Official

Featured

TypeScript

Kagi MCP Server

An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.

Official

Featured

Python

E2B

Using MCP to run code via e2b.

Official

Featured

Neon Database

MCP server for interacting with Neon Management API and databases

Official

Featured

Qdrant Server

This repository is an example of how to create a MCP server for Qdrant, a vector search engine.

Official

Featured

Exa Search

A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.

Official

Featured

ScoutAgent

README

Table of Contents

What It Is

Why This Matters for X Layer

Addressable Market

Per-User On-chain Footprint

TVL Footprint

Distribution via MCP

Why World Cup Specifically

Key Features

Badge System

How It Works

Why This Only Works for the World Cup

Contracts

Badge SVG Rendering

Architecture

Tech Stack

Deployed Contracts (X Layer Testnet)

Live On-chain Activity

Notable Transactions

Demo Agents

MCP Server

Claude Desktop Configuration

Cursor Configuration

Available MCP Tools

Available MCP Resources

Published on npm

Dashboard Demo Mode

Getting Started

Prerequisites

1. Clone and install

2. Environment setup

3. Start infrastructure

4. Build and test contracts

5. Deploy contracts to X Layer Testnet

6. Seed demo data

7. Start all services

8. Run end-to-end tests

Project Structure

Frontend Pages

Agent Runtime API

Oracle Design

OKX OnchainOS Integration

OnchainOS API Endpoint

Data Indexer

Indexed Events

Database Tables

Indexer API

Testing

Contract Tests

Fork Tests (X Layer Testnet)

Slither Static Analysis

Playwright E2E Tests

End-to-End

Security

MCP Marketplace Submission

Team

License

Recommended Servers