SwarmX (@elizaos/plugin-x402-swarms)

March 30, 2026 · View on GitHub

ElizaOS v2 plugin that gives AI agents the ability to pay for APIs using the x402 HTTP payment protocol via the Dexter SDK and orchestrate multi-agent tasks using Swarms — settled in USDC across 5 networks (Base, Ethereum, Solana, Polygon, Arbitrum).

What This Enables

Hire AI agent teams — code review (3 agents), research (3 agents), multi-angle analysis (4 agents), debate (3 agents) — one API call, one USDC payment
Consume paid APIs autonomously — agent detects HTTP 402, pays with USDC via Dexter SDK, retries automatically
Discover x402 services — browse the OpenDexter marketplace of pay-per-call AI/data APIs
Delegate to Swarms — route complex tasks to multi-agent systems (15+ architectures) via the Swarms cloud API
Delegate with x402 data — combine x402 data fetching with swarm analysis in a single action
Run single agents — execute focused tasks with a specific agent role via Swarms
Sell agent services — expose your agent's capabilities as x402-gated HTTP endpoints
Budget controls — per-request, per-hour, and total session spending limits with persistent DB state
Access Passes — time-limited unlimited access for frequently-used endpoints

Featured Endpoints

Endpoint	Team	Agents	Price	What You Get
`POST /x402/code-review`	Code Review	Security Auditor + Performance Reviewer + Style Checker	$0.03	Three specialists audit your code in parallel — security, performance, and style — merged into one report
`POST /x402/research`	Deep Research	Researcher → Fact Checker → Writer	$0.05	A pipeline that investigates any topic, verifies claims, and delivers a polished report
`POST /x402/analyze`	Multi-Angle Analysis	Technical + Economic + Risk → Synthesizer	$0.03	Four domain experts analyze your topic from every angle, then synthesize actionable intelligence
`POST /x402/debate`	Debate & Decide	Proponent + Opponent + Judge	$0.03	Two agents argue opposing sides while a neutral judge weighs evidence and delivers a verdict

All endpoints accept JSON via HTTP POST and settle payments in USDC via the x402 protocol. 3 free calls/day — no wallet needed to start.

Architecture

See docs/ARCHITECTURE.md for the full system diagram.

See docs/TOKENOMICS.md for the economic model.

Quick Start

1. Install

bun add @elizaos/plugin-x402-swarms

2. Configure

cp .env.example .env
# Fill in: EVM_PRIVATE_KEY (or SOLANA_PRIVATE_KEY), OPENAI_API_KEY (or ANTHROPIC_API_KEY)
# Optional: SWARMS_API_KEY for multi-agent features

3. Add to Your Agent (ElizaOS v2)

import type { Project, ProjectAgent } from "@elizaos/core";
import { x402SwarmsPlugin } from "@elizaos/plugin-x402-swarms";

const character = {
  name: "PayAgent",
  bio: ["An AI agent that can pay for APIs and orchestrate multi-agent tasks."],
  system: "You are PayAgent. Use DISCOVER_X402_SERVICES to find paid APIs, PAY_FOR_X402_SERVICE to access them, DELEGATE_TO_SWARM for multi-agent tasks, or RUN_SWARM_AGENT for single-agent tasks.",
  plugins: [],
  settings: {
    EVM_PRIVATE_KEY: process.env.EVM_PRIVATE_KEY ?? "",
    X402_NETWORK_ID: "base-sepolia",
    X402_MAX_AUTO_PAY_USD: "0.10",
    X402_BUDGET_USD: "10.00",
    SWARMS_API_KEY: process.env.SWARMS_API_KEY ?? "",
    OPENAI_API_KEY: process.env.OPENAI_API_KEY ?? "",
  },
};

const agent: ProjectAgent = { character, plugins: [x402SwarmsPlugin] };
export const project: Project = { agents: [agent] };
export default project;

4. Run

# As an ElizaOS project:
elizaos start

# Or run the standalone demo:
bun run example

5. Chat with Your Agent

You: What x402 services are available?
Agent: Found 5 x402 service(s) on OpenDexter:
  WETH On-Chain Price (\$0.01/call), Solana Token Price (\$0.01/call)...

You: Access the x402 endpoint at https://pro-api.coingecko.com/api/v3/x402/onchain/simple/net
Agent: Access successful.
- Endpoint: GET https://pro-api.coingecko.com/...
- Amount paid: \$0.0100 USDC
- Tx: 5abc...xyz (eip155:84532)
- Remaining budget: \$9.99

You: Use the swarm to analyze top DeFi protocols and summarize risks
Agent: Swarm completed (SequentialWorkflow)
Agents: 2, Execution time: 12.3s
Result: [detailed analysis]...

You: Run a code review agent to check this smart contract
Agent: Agent "CodeReviewer" completed.
[detailed review]...

Plugin Components

Component	Name	Purpose
Action	`PAY_FOR_X402_SERVICE`	Access x402-protected APIs with automatic USDC payment
Action	`DISCOVER_X402_SERVICES`	Browse OpenDexter marketplace for paid APIs
Action	`DELEGATE_TO_SWARM`	Delegate to 15+ multi-agent swarm architectures
Action	`RUN_SWARM_AGENT`	Run a single specialized agent via Swarms
Action	`DELEGATE_TO_SWARM_WITH_PAYMENT`	Fetch x402 data then feed it into a swarm analysis
Provider	`X402_PAYMENT_CONTEXT`	Injects wallet/budget/spending into LLM prompt
Provider	`X402_SERVER_CONTEXT`	Injects sell-side revenue and endpoint catalog into LLM prompt
Evaluator	`PAYMENT_EVALUATOR`	Warns at >80% budget usage, logs summaries
Service	`X402WalletService`	Dexter SDK wallet with budget controls
Service	`SwarmsService`	swarms-ts SDK wrapper for agent/swarm runs
Service	`X402ServerService`	Server-side x402 gate for selling agent services
Service	`PaymentMemoryService`	Persistent payment history and endpoint scoring

Routes

The plugin registers 5 HTTP routes for selling agent capabilities via x402 micropayments:

Route	Method	Price	Description
`/x402/research`	POST	$0.05	Multi-agent research pipeline (Researcher + FactChecker + Writer)
`/x402/analyze`	POST	$0.03	Multi-perspective analysis panel (Technical + Economic + Risk experts)
`/x402/agent`	POST	$0.02	Run a single AI agent with custom task, model, and system prompt
`/x402/catalog`	GET	FREE	List all available paid endpoints with pricing
`/x402/health`	GET	FREE	Service health, revenue stats, and network info

Paid routes use x402Gate to require USDC payment before processing. Free routes are publicly accessible.

Templates

4 pre-built swarm templates map user intent to specific architectures and agent configurations:

Template	Swarm Type	Agents	Trigger Examples
`ResearchPipeline`	SequentialWorkflow	Researcher, FactChecker, Writer	"research X", "write a report on X"
`AnalysisPanel`	MixtureOfAgents	TechnicalExpert, EconomicExpert, RiskExpert, Synthesizer	"analyze X from multiple perspectives"
`CodeReview`	ConcurrentWorkflow	SecurityAuditor, PerformanceReviewer, StyleChecker	"audit this smart contract", "review this code"
`DebateAndDecide`	MajorityVoting	Proponent, Opponent, Judge	"should I do X?", "pros and cons of X"

Templates are matched via regex trigger patterns. Custom templates can be registered at runtime with registerSwarmTemplate().

DB Schemas

3 Drizzle ORM tables provide persistent storage for payment analytics and budget tracking:

Table	Purpose	Key Columns
`x402_payment_history`	Every payment the agent makes	endpoint, amountUsd, txHash, network, qualityScore, responseTimeMs
`x402_endpoint_scores`	Aggregate quality scores per domain	totalCalls, totalSpentUsd, avgQualityScore, errorCount
`x402_budget_state`	Cross-session budget state per agent	dailySpentUsd, weeklySpentUsd, monthlySpentUsd, lifetimeSpentUsd

Schemas are exported as schema on the plugin object and auto-migrated by ElizaOS v2.

Environment Variables

Variable	Required	Default	Description
`EVM_PRIVATE_KEY`	One of EVM/Solana	—	EVM private key (hex) for Base/Polygon/Arbitrum
`SOLANA_PRIVATE_KEY`	One of EVM/Solana	—	Solana private key (base58)
`X402_NETWORK_ID`	No	`base-mainnet`	Network: `base-mainnet`, `base-sepolia`, `solana-mainnet`, `polygon-mainnet`, `arbitrum-mainnet`, `ethereum-mainnet`
`X402_MAX_AUTO_PAY_USD`	No	`0.10`	Max USDC per auto-pay request
`X402_BUDGET_USD`	No	`10.00`	Total session budget in USD
`X402_RECEIVE_ADDRESS`	No	—	Your address for receiving payments
`X402_ACCESS_PASS_TIER`	No	—	Access pass tier to offer/purchase: `24h` ($1), `7d` ($5), `30d` ($25)
`X402_ACCESS_PASS_MAX_SPEND`	No	`25.00`	Max spend for access pass purchase
`X402_FACILITATOR_URL`	No	Dexter default	Custom facilitator URL
`SWARMS_API_KEY`	For swarms	—	Swarms API key from swarms.world
`OPENAI_API_KEY`	One LLM key	—	OpenAI API key (used directly for single-agent tasks; falls back to Swarms if absent)
`ANTHROPIC_API_KEY`	One LLM key	—	Anthropic API key

Access Passes

For data and trading endpoints called at high frequency (100-10K calls/day), per-call x402 pricing adds unacceptable latency (~200-500ms per request for the 402 negotiate/pay/retry cycle). Access passes solve this: buyers pay once for time-limited unlimited access, then all subsequent calls are served at native HTTP latency.

Tier	Price	Duration
Day Pass	$1	24 hours
Week Pass	$5	7 days
Month Pass	$25	30 days

Selling passes (operators): Set X402_ACCESS_PASS_TIER in your env to configure which tiers you offer. The Dexter SDK advertises available tiers in the 402 response and handles pass verification internally.

Buying passes (consumers): When your agent or bot calls a data endpoint, the 402 response includes access pass options alongside per-call pricing. The Dexter SDK can automatically purchase a pass if X402_ACCESS_PASS_TIER is configured (e.g., 24h, 7d, 30d). After purchase, all calls from that wallet are served instantly until expiry.

Per-call pricing ($0.001-$0.10) remains the default for multi-agent AI tasks (research, analyze, debate) where the x402 latency is negligible relative to the task execution time.

See docs/TOKENOMICS.md for the full access pass economic model.

How x402 Works

Agent --> GET /data --> 402 Payment Required
                         |
               { price: "\$0.01", payTo: "0x...", network: "eip155:8453" }
                         |
               Dexter SDK: signs USDC transfer, checks budget
                         |
Agent --> GET /data (with payment proof) --> 200 OK + data

x402 is an open standard. No API keys, no subscriptions — just HTTP + stablecoins. The Dexter SDK handles the 402 -> sign -> retry flow automatically with budget controls and access pass support. Gas fees are sponsored by the Dexter facilitator.

Swarm Architectures

The DELEGATE_TO_SWARM action supports these architectures (set via swarmType):

Type	Use Case
`SequentialWorkflow`	Step-by-step pipelines (research -> write -> edit)
`ConcurrentWorkflow`	Independent parallel tasks
`MixtureOfAgents`	Multiple expert perspectives, synthesized
`HiearchicalSwarm`	Director + workers for complex projects
`GroupChat`	Brainstorming or collaborative discussion
`HeavySwarm`	Deep research requiring thorough investigation
`MajorityVoting`	Decisions needing consensus
`DeepResearchSwarm`	Extended research pipelines
`AgentRearrange`	Custom DAG-based agent topology
`MultiAgentRouter`	Intelligent task routing to best agent
`AutoSwarmBuilder`	API auto-generates the right swarm
`auto`	Let the API pick (default)

LLM Routing

SwarmX uses a cost-optimized dual-backend strategy for LLM calls:

Endpoint Type	Endpoints	Backend	Why
Single-agent	`/x402/agent`, summarize, translate, extract, sentiment	Direct OpenAI API	No orchestration overhead. ~$0.001/call, ~95% margin.
Multi-agent	`/x402/research`, `/x402/analyze`, code-review, write, debate	Swarms API	Requires multi-agent orchestration (2-4 agents). ~40-60% margin.

Single-agent tasks use src/utils/llm.ts which calls OpenAI directly with OPENAI_API_KEY
Multi-agent tasks use SwarmsService which calls the Swarms cloud API with SWARMS_API_KEY
Fallback: if OPENAI_API_KEY is not set, all tasks route through Swarms (works but costs more)

Examples

Basic Agent (`examples/basic-agent.ts`)

Minimal ElizaOS v2 project with x402 payments and swarm delegation. Run with bun run example.

SignalHawk (`examples/signalhawk/`)

Full-featured autonomous trading intelligence agent that:

Buys on-chain and market data via x402 micropayments
Runs multi-analyst MajorityVoting swarms for consensus signals
Sells structured signal cards with confidence %, analyst agreement, and cost breakdown

See examples/signalhawk/ for the complete implementation.

GitHub Action

Audit smart contracts on every PR with 4 AI agents. See github-action/ for full docs.

name: Contract Audit
on:
  pull_request:
    paths:
      - 'contracts/**/*.sol'

permissions:
  contents: read
  pull-requests: write

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: SolTwizzy/swarmx-audit@v1
        with:
          files: 'contracts/**/*.sol'
          fail-on-critical: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The action posts a structured audit report as a PR comment (security findings, economic attack vectors, gas optimizations) and fails the check if critical issues are found. Free tier (10 calls/day) works without a wallet.

Development

bun install          # Install dependencies
bun run build        # Compile TypeScript
bun run test         # Run unit + integration tests (162 cases)
bun run test:smoke   # Marketplace smoke tests (needs network)
bun run dev          # Watch mode
bun run example      # Run standalone demo

Key Dependencies

@elizaos/core@2.0.0-alpha.32 — ElizaOS v2 runtime
@dexterai/x402@^2.0.0 — Dexter SDK for x402 payments
swarms-ts@^0.1.0-alpha.10 — Swarms TypeScript SDK
drizzle-orm@^0.45.1 — Database schemas for payment persistence
zod@^3.22.0 — Runtime validation

Roadmap

See TODO-NEXT.md for post-MVP next steps:

CI/CD with GitHub Actions
npm publish to registry
Server-side x402 middleware (sell your agent's services)
Event hooks for payment analytics
Custom HTTP routes for wallet status

License

MIT