SwarmX (@elizaos/plugin-x402-swarms)

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 | Type | 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: ItachiDevv/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/[email protected] — 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