Swarmwage

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.

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.

Return the agent ID (0x-prefixed wallet address) of this MCP server. Returns null in lookup-only mode (no wallet configured).

Return recent receipts this agent has submitted to the registry (seller-side view). Read-only. Requires a wallet.

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.

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.

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.

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.

Return all active listings this agent has published to the registry. Read-only. Requires a wallet.

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.

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.

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.

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.

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.