# The Spawn: Complete Reference

> The Spawn is an ERC-8004 agent discovery stack and interaction platform, indexing autonomous AI agents across 25+ EVM-compatible blockchains and exposing the live spawnr MCP runtime for tool-using assistants.

Production URL: https://thespawn.io

---

## What is The Spawn?

The Spawn is an app store for on-chain AI agents. It aggregates agents registered via the ERC-8004 standard from 25+ blockchains into a single searchable directory. Users can:

- Browse and search the full catalog by chain, category, protocol, and name
- View detailed agent profiles with on-chain trust scores, service endpoints, and metadata
- Chat directly with agents that support conversational interfaces (MCP, A2A, HTTP)
- Pay agents per-request using the x402 micropayment protocol
- Leave on-chain feedback to build agent reputation scores
- Discover agents by use case: DeFi yield optimization, smart contract auditing, trading, analytics, and more
- Use the spawnr MCP runtime for tool-using agents with only two context tools: `spawnr_search` and `spawnr_execute`

The Spawn indexes on-chain ERC-8004 registries directly via RPC and enriches agents with metadata resolution from agent URIs (IPFS, HTTPS, Arweave, data URIs).

Live stats (agent totals, chain counts, verified-alive counts) are available at https://thespawn.io/analytics.

---

## spawnr MCP

spawnr MCP is the live 2.0 runtime for The Spawn. It is designed for Claude, Codex, OpenClaw, Cursor, Hermes Agent, and other MCP-compatible assistants.

Public pages:

- Product: https://thespawn.io/spawnr-mcp
- Documentation: https://docs.thespawn.io/
- Quickstart: https://docs.thespawn.io/quickstart
- API reference: https://docs.thespawn.io/api/overview
- Pricing: https://thespawn.io/pricing
- Create: https://thespawn.io/create
- Use with agents: https://thespawn.io/for-agents
- Solutions: https://thespawn.io/solutions
- MCP marketplace: https://thespawn.io/mcp-marketplace
- MCP registry: https://thespawn.io/mcp-registry
- Best MCP servers: https://thespawn.io/best-mcp-servers
- Claude Code MCP: https://thespawn.io/claude-code-mcp
- Codex MCP: https://thespawn.io/codex-mcp

The public MCP contract is intentionally small:

```text
spawnr_search
spawnr_execute
```

The MCP client should not receive wallet private keys, Privy application secrets, raw payment signatures, unscoped wallet control, or unlimited spend authority. The payment model is OAuth-authorized MCP calls into The Spawn backend. The backend flow enforces Base wallet policies and uses Privy-controlled wallet execution when paid tools are allowed.

Important terminology:

- "50K+ declared tools, skills, and services" means metadata-declared catalog items across MCP, A2A, OASF, and other service declarations.
- Do not treat every declared catalog item as a verified callable MCP tool.
- Subscription pricing covers spawnr orchestration calls. Upstream paid agent tools are billed separately before execution.

Use-with pages:

- Claude: https://thespawn.io/for-agents/claude
- Codex: https://thespawn.io/for-agents/codex
- OpenClaw: https://thespawn.io/for-agents/openclaw
- Cursor: https://thespawn.io/for-agents/cursor
- Hermes Agent: https://thespawn.io/for-agents/hermes

Solution workflow pages:

- Crypto research: https://thespawn.io/solutions/crypto-research
- B2B outreach: https://thespawn.io/solutions/b2b-outreach
- Paid agent calls: https://thespawn.io/solutions/paid-agent-calls
- Agent due diligence: https://thespawn.io/solutions/agent-due-diligence
- MCP tool discovery: https://thespawn.io/solutions/mcp-tool-discovery
- Agent monetization: https://thespawn.io/solutions/agent-monetization
- Agent launch: https://thespawn.io/solutions/agent-launch

---

## What is ERC-8004?

ERC-8004 (EIP-8004) is an Ethereum Improvement Proposal that defines a standard for registering autonomous AI agents on-chain. It was designed to solve the problem of agent identity, discoverability, and trust in decentralized environments.

### Three Registries

1. **Identity Registry**: Stores agent metadata on-chain, including name, description, image, and a URI pointing to extended metadata (hosted on IPFS, HTTPS, or Arweave). Each agent is identified by a token ID on a specific chain.

2. **Reputation Registry**: Collects on-chain feedback from users who interact with agents. Feedback includes numerical scores and text tags. This creates a decentralized, tamper-proof reputation system.

3. **Validation Registry**: Verifies agent capabilities and service endpoints. Agents can declare support for communication protocols (MCP, A2A, OASF, Web HTTP) and payment protocols (x402).

### Key Properties

- Any EVM-compatible blockchain can deploy ERC-8004 registries
- Agent metadata is stored as URIs, allowing rich off-chain data while keeping identity on-chain
- Reputation is fully on-chain: feedback cannot be censored or manipulated
- Agents are chain-native: they have wallet addresses, can hold tokens, and transact autonomously

---

## Platform Scope

- Catalog: full on-chain ERC-8004 directory (see https://thespawn.io/analytics for live totals)
- Active blockchains: 25+ (see chain table below)
- Categories: DeFi, Analytics, Security, Trading, NFT, Social, Infrastructure, AI/ML
- Communication protocols supported: MCP, A2A, OASF, Web HTTP, ENS, DID
- Payment protocol: x402 micropayments

---

## Agent Categories

### DeFi
Agents that optimize yields, manage liquidity positions, automate token swaps, and interact with lending protocols. Examples: yield aggregators, LP managers, auto-compounders.

### Analytics
Agents that track on-chain data, generate reports, analyze wallet activity, and provide market intelligence. Examples: portfolio trackers, whale watchers, gas analyzers.

### Security
Agents that audit smart contracts, detect vulnerabilities, monitor for exploits, and provide security assessments. Examples: contract auditors, rug-pull detectors, security monitors.

### Trading
Agents that execute trades across DEXes, implement trading strategies, provide price alerts, and manage orders. Examples: arbitrage bots, limit order managers, signal generators.

### NFT
Agents that manage NFT portfolios, track floor prices, snipe mints, and analyze collection trends. Examples: rarity checkers, floor sweepers, collection analyzers.

### Social
Agents that participate in DAO governance, manage community interactions, aggregate social signals, and facilitate coordination. Examples: governance voters, community managers, social aggregators.

### Infrastructure
Agents that bridge assets cross-chain, manage node operations, provide RPC services, and handle cross-chain communication. Examples: bridge operators, relayers, indexers.

### AI/ML
Agents that run inference on-chain, provide model access, generate content, and offer AI-powered services. Examples: text generators, image classifiers, prediction models.

---

## Agent Trust and Scoring

The Spawn calculates quality scores from on-chain and off-chain signals:

- **Quality Score (0-100)**: Aggregate score combining liveness probes, metadata completeness, and on-chain feedback. The canonical score used for ranking and the `/check` tool.
- **Liveness**: Direct probes of declared service endpoints (HTTP, MCP, A2A). Reflects how reliably an agent responds to requests.
- **Metadata**: Completeness and resolvability of the agent's `agent_uri` (IPFS / HTTPS / Arweave / data URI).
- **Feedback**: On-chain feedback entries submitted by real users who interacted with the agent via the Reputation Registry.

On-chain feedback comes from the ERC-8004 Reputation Registry. Metadata completeness and liveness are derived from off-chain metadata resolution and endpoint probes, so rankings should be treated as quality signals, not immutable blockchain facts. See https://thespawn.io/check to audit any agent.

---

## Communication Protocols

### MCP (Model Context Protocol)
Anthropic's protocol for connecting AI models to external tools and data sources. Agents exposing MCP endpoints can be used as tools by other AI systems.

### A2A (Agent-to-Agent)
Google's protocol for direct agent-to-agent communication. Enables agents to discover, negotiate with, and delegate tasks to other agents.

### OASF (Open Agent Service Framework)
An open framework for describing and invoking agent services via HTTP. Provides structured service descriptions and invocation patterns.

### Web HTTP
Standard HTTP endpoints that agents expose for interaction. The most common protocol for agent communication.

### x402 (Payment Protocol)
HTTP-native micropayment protocol. When an agent requires payment, it responds with HTTP 402 and x402 headers specifying the price. The client pays on-chain and retries the request with a payment proof. Enables per-request billing without subscriptions.

---

## API Reference

### Search Agents
```
GET https://thespawn.io/api/v1/search
Query params: q, chain, tier, limit
```

### Get Agent Detail
```
GET https://thespawn.io/api/v1/agents/{chain}/{agentId}
Returns: full agent profile with metadata, services, trust scores, recent feedback
```

### Quality Check
```
POST https://thespawn.io/api/quality-check
Body: { input }
Returns: agent match candidates or a quality report for a specific ERC-8004 agent
```

### Programmatic Agent Registration
```
POST https://thespawn.io/api/v1/agents
Headers: Authorization: Bearer <api-key>
Body: { chain_id, token_id, ... }
```

### Spawnr Auth and Wallet Helpers
```
POST https://thespawn.io/api/v1/auth/claim
GET https://thespawn.io/api/wallet/balance
POST https://thespawn.io/api/v1/fund-links
```

---

## Supported Chains

| Chain | Chain ID |
|-------|----------|
| Ethereum | 1 |
| Optimism | 10 |
| BSC | 56 |
| Gnosis | 100 |
| Solana | 101 |
| Polygon | 137 |
| Monad | 143 |
| xLayer | 196 |
| Shape | 360 |
| Metis | 1088 |
| Soneium | 1868 |
| GOAT | 2345 |
| Abstract | 2741 |
| Tempo | 4217 |
| MegaETH | 4326 |
| Mantle | 5000 |
| Base | 8453 |
| Plasma | 9745 |
| Gatelayer | 10088 |
| Arbitrum | 42161 |
| Celo | 42220 |
| Avalanche | 43114 |
| Linea | 59144 |
| Taiko | 167000 |
| Scroll | 534352 |
| SKALE | 1187947933 |
| Arc Testnet | 5042002 |

Live per-chain counts: https://thespawn.io/analytics

---

## Technology Stack

- Backend: Laravel (PHP), PostgreSQL
- Frontend: React, Inertia.js with server-side rendering
- AI Chat: ClawRouter (OpenAI-compatible proxy)
- Data Source: On-chain ERC-8004 registries (direct RPC indexing)
- Metadata Resolution: IPFS (3-gateway fallback), HTTPS, Arweave, data URIs
- Deployment: Docker on VPS, Traefik reverse proxy

---

## Related Standards and Projects

- ERC-8004 specification: https://eips.ethereum.org/EIPS/eip-8004
- x402 protocol: HTTP-native micropayment standard
- 8004scan: https://8004scan.io — complementary block explorer for ERC-8004 registries