Agents that pay their own way.

# Introduction

x402Swarms is a runtime for spawning networks of autonomous agents that transact over the x402 protocol. Each agent can independently discover paid APIs, settle USDC micropayments per request, and consume the response — all without human-managed accounts or API keys.

The protocol is built on the long-reserved HTTP 402 Payment Required status code. When an agent hits a paid endpoint, the server returns a 402 with payment terms; the agent signs a payment and retries. The whole loop settles on-chain in under two seconds.

# Installation

The runtime ships as a TypeScript package. Install x402swarms alongside the x402 SDK packages for the chains you want to settle on.

# core runtime + x402 packages
npm install x402swarms @x402/core @x402/fetch

# add the chains you'll settle on
npm install @x402/evm   # Base, Arbitrum, Polygon
npm install @x402/svm   # Solana

# Quickstart

Spin up a single agent, give it a funded wallet, and let it buy a weather data call. The agent handles the 402 handshake automatically.

import { Agent } from "x402swarms";

const agent = new Agent({
  wallet: process.env.AGENT_PRIVATE_KEY,
  network: "base",
  limits: { perCall: "0.05", daily: "5.00" } // USDC
});

// agent hits a paid endpoint — 402 handled automatically
const data = await agent.fetch("https://api.example.com/weather?");

console.log(data.json());
console.log(agent.receipts()); // on-chain payment trail

# The Agent

An Agent is the atomic unit: one wallet, one set of spending limits, one HTTP client that understands x402. It exposes a fetch() drop-in that transparently pays for any 402 response within its limits.

• agent.fetch(url, opts) — request a resource; auto-pays on 402.
• agent.receipts() — returns the on-chain payment ledger.
• agent.balance() — current USDC balance of the agent wallet.

# The Swarm

A Swarm coordinates many agents toward one goal. A planner splits the task, spawns workers, and merges their results. Workers are ephemeral; the swarm's shared memory persists across the run.

import { Swarm } from "x402swarms";

const swarm = new Swarm({
  size: 8,                      // number of worker agents
  network: "solana",
  budget: "25.00",              // total USDC cap for the run
  discovery: "bazaar"           // auto-find cheapest endpoints
});

const result = await swarm.run({
  goal: "Compile a market report on SOL memecoins launched today"
});

console.log(result.summary);
console.log(swarm.spent()); // total USDC spent across all agents

# Wallets & limits

Spending controls are enforced before any payment is signed. An agent that hits a cap stops and reports rather than overspending. This is the guardrail that makes autonomy safe.

# Configuration

Configure the runtime via the constructor or a swarm.config.json file at your project root.

# FAQ

Do agents need an API key for each provider?

No. That's the entire point of x402 — payment is the authentication. An agent pays per request and gets the resource, with no account or key.

What stops an agent from draining its wallet?

Hard spending limits (perCall, daily, budget) are enforced in the runtime before any payment is signed. Fund the wallet with only what you're willing to spend.

Which chains are supported?

Anywhere x402 settles — currently Base, Solana, Arbitrum, Polygon, and Ethereum. Base and Solana are the most common thanks to low fees and fast finality.

Is this affiliated with Coinbase?

No. x402Swarms is an independent project built on the open x402 standard.