@zeroxyz/sdk

TypeScript SDK for Zero — the search and payment layer for AI agents.

Zero indexes the API capabilities published across the web and gives an agent one interface to find them, call them, and pay for them. You search for a capability, call its URL with client.fetch(), and the SDK settles payment automatically — over x402 or MPP, in USDC — handing you back the response and the payment receipt together. The wallet is the agent's identity, so there are no per-service API keys to provision.

Install

pnpm add @zeroxyz/sdk
# npm install @zeroxyz/sdk
# yarn add @zeroxyz/sdk

Requires Node 20.3+.

Quickstart

Search needs no credentials. This is the smallest thing that runs:

import { ZeroClient } from "@zeroxyz/sdk";

const client = new ZeroClient();

const { capabilities } = await client.search("current weather in tokyo");
for (const cap of capabilities) {
  console.log(cap.id, cap.name, cap.method, cap.url, cap.availabilityStatus);
}

Calling and paying for a capability needs a wallet. That's the next section.

Authentication

A client runs in one of three modes. Pick one at construction:

Passing both account and session is a configuration error — the two modes don't compose.

Account mode (bring your own key)

The common case: you have a private key and sign requests locally.

import { ZeroClient } from "@zeroxyz/sdk";

const client = ZeroClient.fromPrivateKey(
  process.env.ZERO_PRIVATE_KEY as `0x${string}`,
);

const result = await client.fetch("https://example.com/weather?city=tokyo", {
  maxPay: "0.01", // refuse to pay more than $0.01 USDC for this call
});

console.log(result.outcome); // "success" | "payment_failed" | ...
console.log(result.body);    // parsed JSON when the response is JSON
console.log(result.payment); // { protocol, txHash, ... }, or null on a free call

fromPrivateKey and fromMnemonic are convenience constructors. For any other signer — a KMS-backed account, a hardware wallet, a custom viem account — build the account yourself and pass it in:

import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.ZERO_PRIVATE_KEY as `0x${string}`);
const client = new ZeroClient({ account });

Session mode (acting for a Zero user)

Use this when your server holds a Zero-issued token pair for a user and wants the SDK to sign with that user's Zero-managed wallet, resolved on the first paid call:

const client = new ZeroClient({
  session: {
    accessToken: userSession.access,
    refreshToken: userSession.refresh,
    onRefreshed: async ({ accessToken, refreshToken }) => {
      await db.updateUserSession(userId, { accessToken, refreshToken });
    },
  },
});

The SDK refreshes the access token automatically after a 401, and every refresh rotates the refresh token. onRefreshed is your one hook to persist the new pair — skip it and the next process restart will present a token the server has already revoked.

client.fetch()

client.fetch() is the call you'll reach for most. Given a URL, it:

1. Sends the request.
2. If the server answers 402 Payment Required (x402 or MPP), reads the payment challenge and pays it.
3. Replays the request with proof of payment.
4. Returns the body, status, and payment metadata together.
5. Records a run on Zero when you pass a capabilityId, so the capability's reliability signal stays current and the call stays reviewable.

Endpoints that don't charge pass straight through: a 200 on the first request returns with payment: null and outcome: "success". No payment is attempted.

Building the request — search → get → fetch. A search() result carries the url and method, so a no-body GET capability can go straight to fetch(). For anything that takes a request body, call capabilities.get() first: its bodySchema, method, and headers are what tell you how to construct the call. Don't guess the body from the search summary. When present, exampleRequest is the single best artifact to copy — the bare, ready-to-send request body from a real successful call, already unwrapped from the stored transcript and validated against the current schema (it's null when there's no example or the stored one is stale, so fall back to bodySchema). The raw example ({ request, response }) is retained for the response sample.

Each search result also carries a token field (format: z_xxx.N) — a short server-issued attribution token that encodes the search context and the result's position. Pass it as capabilityId to fetch() (or as the id to capabilities.get()) instead of the raw uid/slug; the server uses it to attribute the run back to the originating search for ranking and analytics. Tokens expire when the session rolls, so use them within the same search session.

The HTTP-transport envelope. Some capabilities store their request contract as Zero's HTTP-transport envelope — { input: { type: "http", method, queryParams, body } } — rather than a bare body. You don't have to special-case it: fetch() detects an envelope body and normalizes it to the real wire request — it carries the method (from the envelope's input.method, never inferring POST from body-presence) and moves a GET's queryParams onto the URL query string. So passing the envelope straight through works:

// A GET capability whose schema is the envelope — fetch() routes it to
// GET https://…/weather/current?city=tokyo (not a POST).
await client.fetch(cap.url, {
  body: JSON.stringify({ input: { type: "http", method: "GET", queryParams: { city: "tokyo" } } }),
});

If you'd rather inspect the schema yourself, the SDK exports the pure helpers it uses: extractInputEnvelope(bodySchema, method) (the query-param / body schema nodes), unwrapTransportEnvelope(exampleRequest) (the inner request from a stored example), and normalizeTransportEnvelopeRequest(url, { method, body }) (the { url, method, body } the wire request should use).

Additional utilities exported from @zeroxyz/sdk:

• inferSchema(value) — deterministic structural walk of a JSON value to a JSON-schema-ish draft (types + field names, no values). Useful for logging anonymized request/response shapes.
• tryParseJson(text) — returns parsed JSON or null on failure (no throw).
• urlMatchesTemplate(url, template) — returns true when a URL matches a path template like https://api.example.com/users/{id}. Mirrors the server-side templateToRegex logic.

A few further exports (display formatters, chain constants) exist so Zero's own surfaces (CLI, MCP plugin) render identically; they're marked @internal and aren't part of the supported partner contract.

const result = await client.fetch(url, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ city: "tokyo" }),
  maxPay: "0.01",          // USDC ceiling; an over-cap challenge aborts before signing
  capabilityId: "cap_abc", // attribute the run to a known capability
  walletAddress: "0x…",    // session mode: pay from this profile wallet (default: primary)
  signal: controller.signal,
});

switch (result.outcome) {
  case "success":
    // 2xx/3xx — result.body / result.bodyRaw are populated.
    break;
  case "insufficient_funds":
    // Wallet balance is too low to cover the challenge amount. No payment
    // was attempted. Top off via `zero wallet fund` (CLI) or fund the
    // wallet before retrying. result.error is a ZeroInsufficientFundsError
    // with .have and .need fields.
    break;
  case "payment_failed":
    // Couldn't pay: over your maxPay or an unrecognized 402 protocol.
    // Nothing settled — generally safe to retry.
    break;
  case "payment_rejected":
    // Paid, but the capability still returned 402 (a settlement/facilitator
    // race). Reconcile via result.warnings and result.payment.
    break;
  case "payment_close_failed":
    // MPP — charged, but the session-close voucher was rejected. The channel
    // is orphaned; reconcile out-of-band via result.payment.session.
    break;
  case "server_error":
    // The capability returned 4xx/5xx (after payment, if any). See
    // result.upstreamError.
    break;
  case "network_error":
    // The request never reached the server.
    break;
}

for (const warning of result.warnings ?? []) {
  // e.g. FETCH_WARNINGS.bodyTruncated, FETCH_WARNINGS.mppSessionCloseFailed
}

The FetchResult

fetch() always resolves to one object — it doesn't reject for expected runtime failures (those come back as an outcome; see Errors). The full shape:

capabilityId accepts the capability's uid (cap_…), slug, or an attribution token (z_xxx.N) from a search() result. Prefer the token when one is available — it lets the server tie the run back to the originating search for accurate ranking and analytics. Pass the uid or slug for direct fetches where no search was performed.

maxPay

maxPay is your hard per-call ceiling, in USDC. The challenge amount is checked against it before anything is signed; an over-cap challenge aborts with outcome: "payment_failed" and no on-chain spend. Set it on every paid call — it's the guardrail that keeps a mispriced or hostile endpoint from draining the wallet.

To put a human in the loop before any spend, read the price up front, show it to your user, and only call fetch() with maxPay once they approve. Prefer capabilities.get()'s pricing object when present: pricing.summary is the server-resolved display string (render it verbatim — don't re-derive from raw fields), pricing.kind classifies the shape (static | dynamic | session | metered | subscription | free | unknown), and pricing.primary.amountUsd / depositUsd give the structured numbers for sizing maxPay. cost.amount remains on every search result as the raw advertised scalar, but it flattens usage-priced caps — a dynamic cap's real cost scales with input.

Wallet & funding

The wallet you construct the client with is the agent's identity — paid calls draw USDC from it, and there are no per-service API keys to provision. Keeping it funded is the only operational task. Two funding models, both first-class:

• Partner-funded shared wallet (the common default). You hold one wallet on behalf of all your users, keep it topped up as a backend cost, and recoup it through your own billing. Per-user spend tracking and caps live in your app — maxPay is the per-call guard.
• End-user top-up. Each user funds the wallet directly; you surface a funding link when their balance runs low. Pairs with a per-user wallet.

The same two primitives serve both:

// The address this client acts as. Account mode resolves locally; session
// mode resolves the user's primary managed wallet (provisioning on first call).
await client.wallet.address();

// Balance in USDC. Sums Base + Tempo by default; pass a chain for just one.
const { amount } = await client.wallet.balance();          // e.g. "12.50"
const onBase     = await client.wallet.balance({ chain: "base" });

// A one-time hosted top-up link — Coinbase by default, or provider: "stripe".
// USDC settles on Base.
const url = await client.wallet.fundingUrl({ amount: "10" });

Poll balance() to decide when to top up. Then either open fundingUrl() yourself to refill the shared wallet — from an ops dashboard, a low-balance alert, or alongside a direct USDC transfer to the wallet.address() result — or hand the link to the end user. Either way the link is single-use and burns when opened, so generate it at the moment of funding and don't pre-open one you intend to give to someone else.

In session mode (acting for a Zero user) wallets are managed server-side, and a few more methods apply:

await client.wallet.list();      // every wallet linked to the session user
await client.wallet.provision(); // create the user's managed wallet (idempotent)

// Link an existing self-custody wallet by private key (0x prefix optional).
// Pass makePrimary to have it pay for the user's calls from now on, and an
// optional nickname (owner-private display name, max 64 chars).
const imported = await client.wallet.import({
  privateKey: "0x…",
  makePrimary: true,
  nickname: "Trading bot",
});

// Switch which linked wallet is primary, or unlink one. remove() rejects the
// primary wallet and any wallet holding a balance — reassign / drain first.
await client.wallet.setPrimary({ walletAddress: imported.walletAddress });
await client.wallet.remove({ walletAddress: "0x…" });

// Nickname a wallet (or clear with null). Nicknames are private to the
// authenticated user — they never appear on reviews or public surfaces.
await client.wallet.setNickname({ walletAddress: "0x…", nickname: "Cold storage" });

// Revoke / re-grant Zero's signing delegation per wallet (default: primary).
await client.wallet.revokeDelegation({ walletAddress: "0x…" });
await client.wallet.reauthorizeDelegation({ walletAddress: "0x…" });

wallet.address() covers the common case (resolve — or provision — the primary managed wallet); reach for the methods above when you need the full wallet objects, explicit provisioning, or multi-wallet management. Imported wallets carry an importedAt timestamp on the returned wallet objects.

To pay from a non-primary wallet, pass walletAddress on the call itself — client.fetch(url, { walletAddress }) (or payments.pay / payMpp) resolves the named profile wallet for the payment intent's from, the managed signature, and the recorded run's attribution, and client.auth.sign* accept { walletAddress } too. The wallet must be a delegated Privy-embedded wallet on the session user's profile. Runs can likewise be filtered per wallet: client.runs.list({ walletAddress: ["0x…"] }) (default remains all profile wallets; an address not on the profile is a 400).

Namespaces

Beyond search() and fetch(), the client groups the rest of the API into resource namespaces:

// Search — ranked capabilities for a query (no auth required).
// No implicit price cap: omitting maxCost returns results at any price.
// Pass a value to cap costs (e.g. "0.05" for a tight cap, "0" for free-only).
const { capabilities } = await client.search("translate text to french", {
  maxCost: "0.05",  // optional: only results at or under this price
  protocol: "x402", // optional: "x402" | "mpp"
});

// Capabilities — full detail for one capability by uid, slug, or attribution token
const cap = await client.capabilities.get("cap_abc");     // by uid
const cap2 = await client.capabilities.get("z_Ab12cd.1"); // by search token

// Wallet — balance, one-time funding URL, and (session mode) multi-wallet
// management: list / provision / import / setPrimary / remove / setNickname /
// revokeDelegation / reauthorizeDelegation. See "Wallet & funding" above.
const { amount } = await client.wallet.balance();
const fundUrl    = await client.wallet.fundingUrl({ amount: "10" });

// Runs — fetch() records these for you on paid calls; reach for them
// directly when you want to log or review a call yourself
const run = await client.runs.create({
  capabilityId: "cap_abc",
  status: 200,
  latencyMs: 1234,
});
await client.runs.review({
  runId: run.runId,
  success: true,
  accuracy: 5,    // 1–5
  value: 4,       // 1–5
  reliability: 5, // 1–5
});

// Bug reports
await client.bugReports.create({
  category: "broken_execution", // see the BugReportCategory union for the full set
  capabilityId: "cap_abc",
  description: "Returns 502 on every call",
});

// Auth (session mode)
await client.auth.refresh();            // force a token refresh
await client.auth.logout(refreshToken); // revoke the session server-side

// Device-code login (RFC 8628 — for CLIs and other browserless flows)
const device = await client.auth.device.start();
console.log(device.verificationUri, device.userCode);
const grant = await client.auth.device.poll(device.deviceCode);

// Agent accounts (auth.md) — fully autonomous signup, no browser or human.
// Persist registration.claimToken + registration.identityAssertion securely:
// they are returned exactly once. `session` is a Zero session for the account.
const { registration, session } = await client.auth.agent.signup();

// A human can claim ownership of the account later. startClaim() returns a
// hosted URL; the page shows the HUMAN a pairing code (the reverse of the
// device flow) which they read back for completeClaim().
if (registration.claimToken) {
  const attempt = await client.auth.agent.startClaim({
    claimToken: registration.claimToken,
    email: "human@example.com",
  });
  console.log(attempt.verificationUri);
  const claimed = await client.auth.agent.completeClaim({
    claimToken: registration.claimToken,
    userCode: "1234-5678", // read back by the human
  });
  // claimed.status: "ok" | "not_confirmed" | "invalid_code" | "expired" —
  // on "ok", exchange the fresh assertion for a post-claim session:
  //   exchangeAssertion(claimed.identityAssertion) → exchangeAtZero(accessToken)
}

Errors from the AuthKit-hosted agent-auth surface throw ZeroAgentAuthError (status, body, and serverCode — the server's own error code, e.g. claim_expired).

Multi-tenant servers

A server that signs as a different end-user wallet on each request shouldn't build a fresh ZeroClient every call. Pass the wallet per call, or derive a reusable sub-client:

const base = new ZeroClient(); // shared transport config, no auth of its own

// Simplest: sign a single call as a given wallet.
await base.fetch(url, { account: tenantAccount, maxPay: "0.01" });

// Or hold a sub-client bound to that wallet. `withAccount` caches by address,
// so repeat calls for the same tenant reuse one instance.
const tenant = base.withAccount(tenantAccount);
await tenant.fetch(url, { maxPay: "0.01" });

withSession(session) is the session-mode equivalent for per-user token pairs; unlike withAccount it isn't cached, since sessions are typically one per request. On a long-running server, call base.clearAccountCache(account?) when a tenant churns — pass an account to drop one entry, or omit it to clear the cache entirely.

Errors

The SDK throws typed errors instead of strings. Match them with instanceof:

import {
  ZeroApiError,                  // a 4xx/5xx from Zero's own API
  ZeroAuthError,                 // missing auth, failed refresh, expired session
  ZeroInsufficientFundsError,    // wallet balance too low; .have and .need in USDC
  ZeroPaymentError,              // payment failed before settlement
  ZeroSessionCloseFailedError,   // MPP session-close voucher rejected
  ZeroTimeoutError,            // the configured timeout was exceeded
  ZeroConfigurationError,      // invalid ClientOptions
  ZeroWalletError,             // a wallet read or write failed
  ZeroValidationError,         // a response didn't match its expected schema
  ZeroError,                   // base class for all of the above
} from "@zeroxyz/sdk";

try {
  await client.fetch(url, { maxPay: "0.01" });
} catch (err) {
  if (err instanceof ZeroAuthError) {
    // re-auth and retry
  } else if (err instanceof ZeroError) {
    console.error(err.code, err.message);
  } else {
    throw err;
  }
}

client.fetch() reserves throwing for programmer errors — bad config, missing credentials, and the like. Expected runtime failures (insufficient_funds, network_error, payment_failed, an upstream 5xx) come back as a FetchResult with the matching outcome, so you handle them by branching on the result rather than by catching.

Logging

Pass a logger to observe SDK-level events — refreshes, recording failures, payment warnings:

new ZeroClient({
  logger: (event) => {
    if (event.level === "error") console.error(event.message, event.meta);
  },
});

Testing

The package ships mock helpers under @zeroxyz/sdk/testing for unit tests against a stubbed Zero API. They carry no runtime peer dependencies:

import { createTestClient, respondJson } from "@zeroxyz/sdk/testing";

const client = createTestClient({
  routes: {
    "GET /v1/capabilities/cap_abc": () =>
      respondJson({ id: "cap_abc", name: "Test capability" }),
  },
});

const cap = await client.capabilities.get("cap_abc");

For end-to-end tests against a real payment flow, mock at the network boundary with MSW or run the call against your own staging facilitator.