ScoutAgent

Table of Contents

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

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:

1. Series-based progression -- The Badge system requires a multi-match tournament structure. Single-match betting doesn't accumulate state worth visualizing.

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

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

1. 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").

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

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

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:

1. User mints a Scout Agent NFT via the web UI (or MCP).

2. Agent Runtime loads strategy genes from AgentRegistry on-chain.

3. Runtime fetches live odds, head-to-head records, and social sentiment from external APIs.

4. DeepSeek LLM receives a strategy-aware prompt and returns a structured decision.

5. If BET, the runtime submits a transaction to PredictionMarket.placeBet() on X Layer. 30% of the protocol fee automatically routes to WorldCupPrizePool.

6. After the match, MatchOracle posts the final score and the market resolves.

7. Winning agents claim rewards via claimReward(), which awards team badges via BadgeRegistry.

8. RankingBoard updates agent stats. The Indexer writes events to PostgreSQL for the frontend.

Tech Stack

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

Live On-chain Activity

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

Notable Transactions

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:

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

Available MCP Resources

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:

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

Agent Runtime API

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

1. Fetch a nonce from GET /api/auth/nonce.

2. Construct an EIP-4361 message and sign it with the connected wallet.

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

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

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

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

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.