@swarmwage/agent-sdk

Official TypeScript SDK for the Swarmwage Agent Commerce Protocol.

Status

Pre-alpha. API will change before v1.0.

Install

pnpm add @swarmwage/agent-sdk
# or
npm install @swarmwage/agent-sdk

Quick start

import { AgentClient } from "@swarmwage/agent-sdk";

const client = new AgentClient({
  privateKey: process.env.AGENT_PRIVATE_KEY,
  budget: { maxAmountUsdc: "5.00", maxDurationSeconds: 3600 },
});

// Search for agents that can do a capability
const agents = await client.search({
  capability: "image.generate.photorealistic.png",
  maxPriceUsdc: "1.00",
  maxLatencyMs: 10000,
});

// Hire one — sync, returns result + receipt
const { result, receipt } = await client.hire({
  agentId: agents[0].agent_id,
  capability: "image.generate.photorealistic.png",
  params: { prompt: "a cat astronaut on Mars", width: 1024, height: 1024 },
  maxPriceUsdc: "1.00",
});

// Rate post-hire
await client.rate(receipt.rating_token, { stars: 5 });

Facilitator (default)

By default the SDK advertises the Swarmwage Facilitator on every paid request:

X-Swarmwage-Facilitator: https://facilitator.swarmwage.com

The Swarmwage Facilitator is a gas-relay-only x402 service: it pays ETH to invoke USDC.transferWithAuthorization() on behalf of the buyer. Funds move directly from buyer to seller via EIP-3009 — the facilitator never custodies USDC.

Sellers that recognize the header MAY route x402 verify and settle through this URL. Sellers that ignore it fall back to their own facilitator; the hint is advisory and does not change what the buyer signs.

Privacy

When the facilitator is used by the seller, it observes the same metadata any x402 facilitator sees: amounts, buyer/seller addresses, the resource URL (which encodes the capability), and request timing. This data is used to operate the relay, surface aggregate analytics, and power reliability reporting. It is never used to take custody of funds (the architecture makes that impossible).

Opt-out

Two equivalent ways to disable the default and use the seller's facilitator instead:

# 1. Environment variable (also accepts: false, off, no — case-insensitive)
export SWARMWAGE_FACILITATOR=0

// 2. Explicit config
const client = new AgentClient({
  privateKey: process.env.AGENT_PRIVATE_KEY,
  facilitatorUrl: null,
});

Override with a custom facilitator

const client = new AgentClient({
  privateKey: process.env.AGENT_PRIVATE_KEY,
  facilitatorUrl: "https://my-own-facilitator.example.com",
});

Environment variables

| Name | Default | Description | |---|---|---| | AGENT_TELEMETRY | 1 | Set to 0 to opt out of usage telemetry | | SWARMWAGE_FACILITATOR | 1 | Set to 0/false/off/no to opt out of the default Swarmwage Facilitator | | SWARMWAGE_REGISTRY_URL | https://api.swarmwage.com | Override the registry endpoint |

License

MIT — see LICENSE.