Base Swarm Documentation

Base Swarm is an infrastructure protocol that empowers autonomous AI agent swarms on Base. It connects reasoning models to a self-sustaining Machine-to-Machine (M2M) economy where agents can think, purchase data, and execute onchain actions — without ever holding private keys.

Base Swarm is built for teams shipping agentic products that need:

• Secure, user-approved transaction flows via Base Accounts
• Instant USDC micro-payments for data, APIs, and compute
• Composable multi-agent consensus before capital moves onchain

Base Swarm is a three-layer stack. Agents reason offchain, settle value with x402, and only touch the network after a human (or designated policy signer) approves a Base MCP intent.

1. Perception — Scout agents buy real-time feeds and signals via x402.
2. Policy — Risk Officers score Morpho, Moonwell, Aerodrome, and related venues against swarm rules.
3. Execution — Executor agents construct local Base MCP transactions and emit approval links for Base Account review.

flowchart LR
  Scout -->|x402 USDC| Feeds
  Feeds --> Risk
  Risk -->|consensus 3/3| Executor
  Executor -->|Base MCP intent| BaseAccount
  BaseAccount -->|approve| Base

No agent in the loop receives custody of keys. The Base Account remains the sole signing surface; MCP only builds and packages intents for review.

Base MCP connects AI clients — Claude, ChatGPT, Cursor, and custom runtimes — to Base Accounts. Agents can construct transactions locally without ever holding private keys.

Every MCP intent produces a secure web link that lets the user:

• Review expected asset changes (balances in / out, fees, gas)
• Approve or cancel with one click inside their Base Account
• Keep scoped permissions for swarm spend limits and plugins

Supported ecosystem plugins

Example MCP intent

{
  "protocol": "base-mcp",
  "chainId": 8453,
  "action": "morpho.deposit",
  "params": {
    "asset": "USDC",
    "amount": "100.00",
    "vault": "MorphoBlue USDC",
    "slippageBps": 30
  },
  "preview": {
    "assetDelta": [
      { "asset": "USDC", "delta": "-100.00" },
      { "asset": "Morpho shares", "delta": "+99.20" }
    ],
    "estGasEth": "0.00014"
  },
  "approvalUrl": "https://account.base.org/approve/0x9d3f…"
}

Clients should treat approvalUrl as the only path to signing. Never request raw private keys, seed phrases, or unrestricted wallet RPC methods from the agent runtime.

The x402 protocol implements HTTP-native micro-payments using the 402 Payment Required status. Agents can autonomously pay for real-time data feeds, APIs, and compute with USDC on Base — at micro-cent scale — without human subscription friction.

• Per-request metering instead of monthly seats
• Settlement in USDC on Base within seconds
• Composable with any HTTP endpoint that speaks 402

GET /v1/feeds/morpho-apy HTTP/1.1
Host: data.swarm.base
Accept: application/json

HTTP/1.1 402 Payment Required
X-Payment-Network: base
X-Payment-Asset: USDC
X-Payment-Amount: 0.002
X-Payment-Recipient: 0xPay…Facilitator
X-Payment-Expires: 30s

import { createX402Client } from "@base-swarm/x402";

const client = createX402Client({ chainId: 8453, account });

const feed = await client.fetch("https://data.swarm.base/v1/feeds/morpho-apy", {
  maxPaymentUsdc: "0.01",
});

console.log(feed.json()); // APY table after USDC settlement

Pair x402 purchases with swarm policy caps (daily spend, allowlisted hosts, max unit price) so Scout agents can operate continuously without unbounded treasury drain.

Swarms are modular teams that reach consensus before capital moves. A minimal production loop uses three roles:

const votes = await Promise.all([
  scout.propose(instruction),
  risk.evaluate(instruction),
  executor.simulate(instruction),
]);

if (votes.every((v) => v.approve)) {
  const intent = await executor.buildMcpIntent(instruction);
  return intent.approvalUrl; // user reviews in Base Account
}

Spin up a local swarm client, connect a Base Account (or injected wallet for development), and run your first MCP + x402 loop.

1. Install

npm create base-swarm@latest my-swarm
cd my-swarm
npm install
npm run dev

2. Configure environment

BASE_CHAIN_ID=8453
BASE_MCP_ENDPOINT=https://mcp.base.org
X402_FACILITATOR=https://x402.base.org
SWARM_POLICY=./policy.json

3. Issue a swarm instruction

import { Swarm } from "@base-swarm/sdk";

const swarm = await Swarm.create({
  agents: ["scout", "risk", "executor"],
  plugins: ["morpho", "moonwell", "aerodrome"],
});

const result = await swarm.run(
  "Deploy 100 USDC into Morpho vault with automated risk management",
);

// Open the Base MCP approval URL in the user's Base Account
console.log(result.approvalUrl);