SwarmApi · Technical overview

SwarmApi and x402: Agent-native APIs with HTTP settlement

Version 1.0 · May 2026 · Source: swarm-api-dev/swarm-api

Abstract

SwarmApi is a live HTTP gateway that exposes structured JSON APIs for AI agents—covering public-company disclosure (SEC EDGAR), news and hiring signals, open-web search, GitHub repository health, and software supply-chain metadata including CVE context. Access is monetized per successful HTTP response using x402: the open standard that repurposes HTTP 402 Payment Required together with stablecoin authorization (USDC on Base) so clients pay without vendor API keys or subscription contracts.

This document describes SwarmApi in the same conceptual frame as the x402 whitepaper: motivation, payment rail, core flow, agentic commerce, and pragmatic micropayments. It is not a substitute for the canonical x402 specification; where protocol bytes matter, implementers should follow the official paper and reference implementation.

1. Motivation

Autonomous and semi-autonomous agents need three things from third-party data: freshness, machine-readable shape, and permission to spend small amounts without humans inventing accounts for every vendor. Legacy API economics bias toward annual contracts, human onboarding, and static keys—poor fits for per-task agent runs.

On-chain settlement on fast L2s removes chargeback-shaped uncertainty for digital goods, enables sub-cent effective pricing at the protocol layer for micropayments, and lets an agent hold one funded wallet rather than a spreadsheet of API secrets. The x402 whitepaper argues this foundation clearly; SwarmApi applies it to a concrete catalog of research and engineering tools.

Problem: Agents stall on stale training data, unstructured HTML, or blocked vendor signup flows.
Approach: Normalize heterogeneous sources into JSON suited for tool-calling, then charge only when the gateway returns that payload.
Outcome: Predictable unit economics per agent task (e.g., a full company-intelligence pass priced as the sum of discrete tool calls).

2. The x402 protocol (recap)

x402 defines an HTTP-native payment challenge: a resource server may answer an unauthenticated request with 402 Payment Required and a machine-readable payment requirement. The client constructs an authorization for the quoted amount—typically EIP-3009 transferWithAuthorization USDC—attaches it on retry, and receives the resource when verification (and delegated settlement via a facilitator) succeeds.

At a high level the core payment flow matches the x402 whitepaper:

Client request — Agent or backend calls the API route.
402 challenge — Gateway returns terms (amount, asset, network, payee, timeout).
Signed retry — Client sends the signed authorization header expected by the gateway.
Verify, settle, respond — Gateway validates, fulfills the request JSON, and settlement completes on-chain through the configured facilitator.

For normative detail, headers, and middleware patterns, see the x402 whitepaper (PDF) and the x402 reference repository.

3. What SwarmApi is

SwarmApi is the gateway at https://api.swarm-api.com, a public catalog of priced HTTP resources, and client libraries that hide the 402 retry loop:

@swarm-api/mcp — Model Context Protocol server mapping catalog routes to tools for Cursor, Claude Desktop, Continue, and other MCP hosts (npm).
@swarm-api/sdk — TypeScript client for services and scripts (npm).
@swarm-api/setup — CLI for wallet material and paste-ready MCP configuration (npm).

Two MCP tools—gateway_ping and gateway_catalog—call public routes and never charge USDC, useful for wiring MCP before funding a wallet.

4. Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  MCP host       │     │  HTTP + SDK       │     │  Marketplace /   │
│  (Cursor, …)    │     │  backends         │     │  Dashboard       │
└────────┬────────┘     └────────┬─────────┘     └────────┬────────┘
         │ stdio / tools          │ HTTPS                   │ ops / schemas
         └────────────┬────────────┘                         │
                      ▼                                       │
             ┌────────────────────────────────────────────────┘
             │
             ▼
    ┌────────────────────────────┐
    │  SwarmApi Gateway           │
    │  x402 middleware · catalog  │
    └─────────────┬──────────────┘
                  │ EIP-3009 USDC · facilitator
                  ▼
           Base mainnet settlement

The Marketplace (https://marketplace.swarm-api.com) surfaces schemas and integration snippets; the Dashboard (https://dashboard.swarm-api.com) reflects aggregate settlement activity. Neither replaces the gateway contract: paid tools ultimately authenticate payment at https://api.swarm-api.com.

5. End-to-end payment flow (SwarmApi)

From an integrator's perspective SwarmApi behaves like any x402-protected API: first call may receive 402; funded clients complete signing (via SDK or MCP runtime) and retry automatically.

MCP deployments should configure per-request spend caps so agents refuse quotes above operator policy—analogous to human approval limits, expressed in atomic USDC on the client.

6. Catalog philosophy

Endpoints are deliberately granular: resolve identity, list filings, extract structured Items, pull insider transactions, attach fresh news and jobs, search the web, inspect GitHub repos, and audit packages—each priced independently so agents only pay for tools they invoke.

Sources include SEC EDGAR, GDELT-style news pipelines, public ATS job boards (Greenhouse / Lever where exposed), Brave Search, GitHub, language registries, and OSV.dev for vulnerability correlation. Coverage and latency vary by upstream; SwarmApi's contract is the JSON schema and HTTP semantics documented in the live catalog.

7. Traditional APIs vs. SwarmApi + x402

Dimension	Typical vendor API	SwarmApi
Credential	API key / OAuth tenant	USDC wallet + signed micropayment per request
Billing	Subscription or prepaid credits	Pay-per-use per successful response
Agent fit	Humans rotate keys; quota alerts	Programmatic 402 → sign → retry loop
Settlement	Card rails / invoicing	Stablecoin on Base (non-reversible like x402 narrative)

8. Security and operations

Wallet hygiene: MCP and SDK integrations hold signing keys locally; operators must protect filesystem permissions and CI secrets like any hot wallet.
Spend limits: Use SDK and host-level caps so compromised prompts cannot authorize unbounded USDC.
Transparency: Open-source gateway and clients (MIT); verify behavior against public routes and the published catalog.

9. Scope and honesty

SwarmApi does not guarantee completeness of third-party sources (e.g., every private job board or every CVE disclosure path). It is not a securities product or investment advice interface. Pricing is per HTTP tool success as implemented by the gateway; downstream agents remain responsible for correctness, compliance, and disclosure obligations in their jurisdictions.

10. References

Coinbase Developer Platform / x402 Foundation, x402: An open standard for internet-native payments (PDF).
x402 reference implementation: github.com/x402-foundation/x402.
SwarmApi source & issues: github.com/swarm-api-dev/swarm-api.
MCP registry listing: Smithery · swarm-api.

← Back to home · Top