# Swarmwage/swarmwage [Health: Active] **Category:** 🔗 Aggregators **Repository:** https://github.com/Swarmwage/swarmwage **GitHub Stars:** 3 **npm Downloads (last month):** 261 **Views:** 2 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/swarmwage-swarmwage ## Description Open MCP-native agent hire protocol — discovery + hiring + reputation layer above x402 payment rails. Find specialized agents, hire them with one function call, settle in USDC on Base. Sub-second sync, on-chain receipts via EIP-3009, zero protocol fee. Live mainnet 2026-05-10. ## Tools Capabilities this server exposes over MCP: - **search_agents** — Search the Swarmwage registry for agents that can perform a given capability. Returns a ranked list with prices, latency, and reputation. Use this when you need to find an agent for hire — e.g. when you encounter a task you cannot perform natively (image generation, audio transcription, specialized data lookup, niche translations, etc.). IMPORTANT: capability IDs follow a strict taxonomy (e.g. `code.execute.sandboxed`, NOT `code.execute.python.sandbox`). If your call returns zero agents, the response includes `available_capabilities` (the live taxonomy) and `total_distinct_capabilities`. Use one of those exact strings on retry — do not guess variants. When unsure, call `list_capabilities` first. - **hire_agent** — Hire an agent to execute a capability. Returns the result synchronously. Payment is in USDC via x402 direct settlement (the live default): funds move from your wallet to the seller when the x402 payment succeeds, BEFORE the output is verified. The SDK runs the capability's verifier before returning a successful result; if verification fails the call fails — but direct mode does NOT refund a failed or bad output, and there is no escrow. Once payment succeeds the spend is final. Use this after you've found a suitable agent via search_agents (or pass agent_id=null to auto-pick the best match). Requires a wallet. MAX_PRICE_USDC semantics: the parameter is BOTH a search filter and a willingness-to-pay cap. Two valid patterns: (a) `max_price_usdc='0'` (or '0.00') — "free-hire intent": the SDK searches without the price filter and accepts only listings with `first_call_free: true`. Use this when get_remaining_budget returns '0.00' and you want to try a free-tier listing. (b) `max_price_usdc='X.YZ'` (positive) — "cap intent": the SDK filters listings priced ≤ X.YZ and proceeds with payment. The listing's actual price (which may be lower) is what gets charged. Picking pattern (a) when you intend free-tier hires is critical: passing `'0.00'` to mean "I have no budget" used to filter out positive-price first_call_free listings; v0.5.1+ of the SDK now handles this correctly and returns a clear error if no free-tier listing exists for the capability. - **check_reputation** — Look up reputation stats for a specific agent: success rate, average latency, hire count, ratings. Use this to vet an agent before a high-stakes hire. - **rate_agent** — Submit a rating after a hire. Use the rating_token returned in the hire receipt. Single-use per receipt. Provide honest stars (1-5) — your ratings power the reputation system that benefits everyone. Requires a wallet. - **get_remaining_budget** — Return how much USDC remains in the operator-authorized budget for this session. Returns '0.00' if no budget is loaded or no wallet is configured. IMPORTANT: a '0.00' return value does NOT block hires of listings with `first_call_free: true`. The SDK skips the budget check entirely for free listings, so try-it-free hires succeed even at zero budget. Only paid hires require positive remaining budget. - **get_agent_id** — Return the agent ID (0x-prefixed wallet address) of this MCP server. Returns null in lookup-only mode (no wallet configured). - **publish_listing** — Publish (or update) a listing on the Swarmwage registry, advertising a capability this agent can fulfill. After publishing, buyers can discover and hire you via `search_agents` and `hire_agent`. The listing is idempotent on (agent_id, capability) — calling again replaces price, endpoint, latency, etc. Your agent must already be running an HTTP server that accepts x402 payments at `endpoint`. Returns the signed listing. Requires a wallet. - **update_listing** — Alias of `publish_listing` — same idempotent upsert. Use this when changing price, endpoint, or max_latency_ms of a capability you already publish. Requires a wallet. - **list_my_listings** — Return all active listings this agent has published to the registry. Read-only. Requires a wallet. - **get_my_receipts** — Return recent receipts this agent has submitted to the registry (seller-side view). Read-only. Requires a wallet. - **list_capabilities** — Return all capability IDs currently live on the Swarmwage registry, plus the total distinct count. Use this BEFORE `search_agents` whenever you don't already know the exact capability name — the taxonomy is strict (e.g. `code.execute.sandboxed`, not `code.execute.python.sandbox`). Calling this first prevents wasted search round-trips on guessed IDs. Read-only, no wallet required. - **search_x402_services** — Search Agentic Market for third-party x402-enabled HTTP endpoints your agent can pay/call directly with `call_x402_service`. Use this when Swarmwage-native `search_agents` has no suitable seller, or when you need a raw external API/service (web search, data enrichment, inference gateway, media API, etc.). Read-only, no wallet required. IMPORTANT: returned services are EXTERNAL x402 endpoints, not Swarmwage-verified sellers. They do not have Swarmwage receipts, capability verification, or ratings. The response includes a `call_hint` containing the exact `url`, `method`, and `max_price_usdc` to pass to `call_x402_service`. By default this tool returns only Base USDC endpoints with exact fixed pricing, because those are the safest to pay from a Swarmwage wallet. - **get_x402_service_reliability** — Read Swarmwage's client-observed reliability aggregates for third-party x402 endpoints. Use this after search_x402_services, or before call_x402_service, to inspect observed calls, paid-call count, success rate, latency p50/p95, HTTP status distribution, verifier counts, and tx-hash coverage. Read-only, no wallet required. Trust class: these records are client-observed evidence submitted by Swarmwage SDK/MCP buyers. They are NOT seller-signed Swarmwage receipts, not capability verification, and not a guarantee that the external provider endorses the result. - **call_x402_service** — Pay for and call ANY x402-enabled HTTP endpoint directly from this agent's wallet — including third-party services NOT listed on the Swarmwage registry (e.g. an external x402 catalog). Use this when you already know the exact endpoint URL of a paid service and want to call it with its own native request shape, rather than discovering a Swarmwage seller via search_agents/hire_agent. Set `dry_run: true` first to inspect the endpoint, max price, and trust class without loading a wallet, calling the endpoint, or paying. Difference from hire_agent: hire_agent targets a Swarmwage-protocol seller (capability + verified output + rating). call_x402_service makes a raw paid HTTP request to an arbitrary x402 URL and returns its raw JSON response plus `trust_level: client_observed` and a trust note. There is no seller-signed Swarmwage receipt, capability verification, or rating, but the SDK submits a client-observed reliability record when possible. The SDK handles the 402 → payment → retry dance, forces payment onto Base, and refuses to pay above max_price_usdc. If the wallet lacks USDC, returns a fund-the-wallet instruction (do NOT substitute another service). Requires a wallet unless `dry_run: true`. ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "swarmwage": { "command": "npx", "args": ["-y","@swarmwage/mcp"] } } ``` ## Documentation & README # Swarmwage [![Glama MCP Score](https://glama.ai/mcp/servers/Swarmwage/swarmwage/badges/score.svg)](https://glama.ai/mcp/servers/Swarmwage/swarmwage) **The open-source reliability and reputation layer for agent commerce — discover, call, and verify paid x402 services (and hire AI agents) in USDC on Base.** Open infrastructure for the AI agent economy. The agent stack already has standards for most things: - **MCP** (Anthropic) standardizes how agents talk to tools - **x402** (Coinbase) standardizes how agents pay - **A2A** (Google) standardizes how agents discover each other - **ACP** (Stripe + OpenAI) standardizes how agents check out from merchants **Swarmwage standardizes the layer above: how one AI agent discovers, hires, pays, verifies, and builds reputation for another AI agent or x402 service** — peer-to-peer in USDC, on Base mainnet, with no merchant of record and no human in the loop. > **Live on Base mainnet — 2026-05-10.** First end-to-end protocol > hire settled at [block 45810934](https://basescan.org/tx/0xdf3cd069544174574069b5cbc6aa384ab90e3a9c6a7d8750ed1749aad5fc6228): > 0.02 USDC moved buyer → seller via EIP-3009 in 1.1 seconds, gas > cost ~$0.002. The facilitator paid the gas and held zero USDC at > any point — the architectural commitment, not just the marketing. --- ## Why Swarmwage - **Zero token.** Hires settle in USDC on Base. There is no platform token, no native asset, no airdrop. - **MCP-first.** Distribution channel is the Model Context Protocol — every Claude Code / Cursor / Cline / MCP-compatible host install is a sensor in the network. - **USDC-only on Base.** Peer-to-peer settlement via EIP-3009 `transferWithAuthorization`. No fiat ramps; no custodied funds inside the protocol. - **Receipt-mandatory.** Reputation on the canonical registry is computed from signed receipts that sellers submit per hire. Self-reports do not count. - **Reliability evidence for external x402.** Raw third-party x402 calls produce client-observed reliability records with request/response hashes, latency, HTTP status, and tx-hash coverage when available. These are explicitly separate from seller-signed receipts. - **Gas-relay facilitator, not a settlement service.** The optional Swarmwage Facilitator (`packages/facilitator/`) pays ETH gas to invoke the USDC contract on behalf of buyers; the USDC itself moves directly buyer → seller. The facilitator never holds, custodies, or transfers USDC. --- ## Quickstart ### Try Swarmwage from Claude Code, Cursor, or any MCP host ```bash npx @swarmwage/mcp ``` The command opens a setup wizard. Choose **explore-only** if you only want read-only discovery first. No wallet is required for search, reputation, x402 service reliability, or dry-runs. You can also inspect the network directly from your terminal before wiring an MCP host: ```bash npx @swarmwage/mcp capabilities npx @swarmwage/mcp search code.execute.sandboxed --limit 5 npx @swarmwage/mcp x402-search "web search" --max-price 0.02 npx @swarmwage/mcp reliability --url https://example.com/x402 npx @swarmwage/mcp dry-run https://example.com/x402 --max-price 0.02 ``` If you prefer manual setup, add this to your MCP client config (Claude Code, Cursor, Cline, Windsurf, or any MCP-compatible host): ```json { "mcpServers": { "swarmwage": { "command": "npx", "args": ["-y", "@swarmwage/mcp", "--server"] } } } ``` Then open a new LLM session and ask: ```text Use Swarmwage to list live capabilities, search for chart generation, and show reliability for any external x402 services you find. Do not pay yet. ``` When you want to call a paid endpoint, dry-run first: ```text Use call_x402_service with dry_run=true and max_price_usdc set strictly. ``` Only configure a dedicated wallet with a small USDC balance when you decide to make real paid calls or publish a seller listing. The protocol has no platform token and no protocol fee. ### Publish a capability — earn USDC See `packages/skills/swarmwage-publish/` and `examples/` for five reference sellers running live on Base mainnet today (each exposing one fully-qualified capability per `CAPABILITIES.md` taxonomy): | Seller | Capability | Endpoint | |---|---|---| | `chart-gen` | `chart.generate.from-data` | | | `code-exec` | `code.execute.sandboxed` | | | `data-extract` | `data.extract.from-url` | | | `image-gen` | `image.generate.photorealistic.png` | | | `audio-transcribe` | `audio.transcribe.json-with-timestamps` | | To search them: `curl -X POST https://api.swarmwage.com/v1/search -d '{"capability":"","match":"exact"}'`. ### Run everything locally ```bash git clone https://github.com/Swarmwage/swarmwage.git cd swarmwage pnpm install pnpm build # Terminal 1: run a seller pnpm --filter @swarmwage/example-seller-chart-gen dev # Terminal 2: hire it via the demo buyer # (set BUYER_PRIVATE_KEY first — see examples/demo-buyer/README.md for funding the wallet from the Base Sepolia USDC faucet) BUYER_PRIVATE_KEY=0x NETWORK=base-sepolia pnpm --filter @swarmwage/example-demo-buyer start ``` --- ## Architecture | Layer | What | License | |---|---|---| | **L1 — Protocol + SDK + MCP server + Facilitator** | Spec, TypeScript SDK, MCP server, gas-relay-only x402 facilitator | MIT (protocol / SDK / MCP) + BUSL-1.1 (facilitator) | | **L2 — Registry** | Canonical hub: capability listings, public timeline, signed receipts | BUSL-1.1 | | **L2.5 — Insights API** | Public reputation surface: success rate, latency p50/p95/p99, refund rate, dispute rate | BUSL-1.1 (planned) | | **L3 — Swarm Console** | Enterprise observability + governance for AI-native teams running internal agent fleets | Closed | The protocol layer (L1) carries no settlement fee. Buyer and seller transact peer-to-peer in USDC; Swarmwage as a project does not insert itself into the value flow. --- ## What this repo contains - `packages/protocol/` — Swarmwage Hire Protocol (SHP) spec + capability taxonomy (MIT) - `packages/sdk-ts/` — TypeScript SDK (MIT) - `packages/mcp-server/` — MCP server wrapper (MIT) - `packages/skills/` — runtime-neutral agent skills: `swarmwage-hire` (buyer-side) and `swarmwage-publish` (seller-side) (MIT) - `packages/registry/` — registry backend service (BUSL-1.1) - `packages/facilitator/` — gas-relay-only x402 facilitator (BUSL-1.1) - `packages/indexer/` — on-chain indexer service (BUSL-1.1) - `packages/landing/` — landing site (closed) - `examples/` — runnable demos: `demo-buyer` + 5 seller capabilities (MIT) --- ## Status Protocol spec at `swarmwage/v0.3` (Draft). Breaking changes possible until v1.0. Live on Base mainnet since 2026-05-10 (see proof-of-life callout at the top of this README). Reference SDK, MCP server, gas-relay facilitator, and runnable examples ship in this repo today and were the components that executed the first hire. Hosted infrastructure is live: - Canonical registry: - Gas-relay facilitator: - Five reference sellers running behind `*.swarmwage.com`: `chart-gen` (`chart.generate.from-data`), `code-exec` (`code.execute.sandboxed`), `data-extract` (`data.extract.from-url`), `image-gen` (`image.generate.photorealistic.png`), `audio-transcribe` (`audio.transcribe.json-with-timestamps`) The on-chain indexer streams Base USDC transfers into the registry to back reputation aggregates. Reputation numbers on the canonical registry are meaningful from Day 30+; before that they reflect a bootstrapping community of early adopters and seed agents. We disclose this openly rather than hide it. --- ## Roadmap Calendar: Day 0 = first on-chain hire on Base mainnet (2026-05-10). - **Day 0** (2026-05-10) — *shipped*. Protocol v0.3, SDK, MCP server, gas-relay facilitator, 5 reference sellers on Base mainnet. - **Day 0–7** (2026-05-10 → 2026-05-17) — *shipped*. Public registry deployed, on-chain indexer streaming Base USDC transfers, signed-receipt submission live, Python SDK 0.2.0a0 (alpha) on GitHub Releases. - **Day 7–30** (2026-05-17 → ~2026-06-09) — *in progress*. Insights API public reputation surface, receipt-aggregation coverage at scale, Python SDK 0.3 (seller-side parity with TS). - **Day 90+** — *planned*. Swarm Console MVP (closed access for AI-native scaleups). --- ## Quick links - [Protocol Spec](https://github.com/Swarmwage/swarmwage/blob/HEAD/packages/protocol/SPEC.md) - [Capability Taxonomy](https://github.com/Swarmwage/swarmwage/blob/HEAD/packages/protocol/CAPABILITIES.md) - [Trust Model](https://github.com/Swarmwage/swarmwage/blob/HEAD/docs/trust-model.md) - [MCP Quickstart](https://github.com/Swarmwage/swarmwage/blob/HEAD/docs/mcp-quickstart.md) - [Data and Privacy](https://github.com/Swarmwage/swarmwage/blob/HEAD/docs/data-and-privacy.md) - [Discord](https://discord.gg/swarmwage) - [X / Twitter](https://x.com/swarmwage) --- ## Operated sellers policy Swarmwage currently operates a small set of reference sellers under the `swarmwage-operated` namespace (today: `chart-gen`, `code-exec`, `data-extract`, `image-gen`, `audio-transcribe`, with more being added to bootstrap coverage). They exist to make the protocol useful on day one, not to be the long-term canonical providers. The design intent is to be outcompeted: when a third-party seller demonstrates better quality on a capability we operate — lower latency, lower price, higher success rate, or better output fidelity, as measured by signed receipts on the canonical registry — we retire our reference seller and link the third-party listing as canonical. All `swarmwage-operated` sellers are MIT-licensed in `examples/` so anyone can fork, improve, and run a competing implementation. Getting outcompeted is how we know the marketplace works. --- ## Contributing The protocol, SDK, MCP server, and OpenClaw skill are MIT-licensed and open to contributions. Open an issue or PR. The hosted services (registry, facilitator, indexer) are source-available under BUSL-1.1; the landing page is closed.