@1x402/sdk

@1x402/sdk

Caller SDK for the 1x402 x402 router. Discover x402 APIs, top up credits, route paid calls through the toll booth, or pay a provider directly — all authorized by a single wallet.

npm i @1x402/sdk viem

viem is a peer dependency (you bring the wallet).

Quick start

import { createClient } from "@1x402/sdk";
import { privateKeyToAccount } from "viem/accounts";

const client = createClient({
  account: privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`),
  // baseUrl defaults to https://1x402.sh/api
  // network defaults to "base" (mainnet USDC)
});

// 1. Find an API (free, semantic search over the index)
const found = await client.discover("send a transactional email");
//    → { ok, count, results: [{ id, provider, path, price_usd, ... }] }

// 2. Add prepaid credits (pays the x402 paywall with your wallet's USDC)
await client.topup();

// 3. Route a paid call through the toll booth (one signed request)
const res = await client.route({
  category: "email",
  input: { path: "/api/send", method: "POST", body: JSON.stringify({ to: "a@b.com" }) },
});
//    → { ok, status, endpoint, charged_micro, paid_micro, spread_micro, data }

API

createClient(config): Client

option	type	default	notes
account	LocalAccount	—	a viem account; or pass privateKey
privateKey	0x…	—	derived into an account if account is absent
baseUrl	string	https://1x402.sh/api	router base URL
network	"base" | "base-sepolia"	"base"	which USDC network topup pays on
fetch	typeof fetch	global	override the transport

client.discover(query, { limit? }) — free

Semantic search over indexed x402 endpoints. Returns the best matches with price, provider, and live quality.

client.balance() — free

Your prepaid credit balance: { caller, balance_micro, balance_usd }.

client.topup() — costs USDC

Pays the router's x402 paywall with your wallet and credits your balance. Returns { ok, credited_micro, balance_micro, txHash }.

client.route({ category | endpointId, input, idempotencyKey? }) — spends credits

Signs a SIWX message (binding a fresh idempotency key + timestamp to your wallet), debits credits, pays the upstream provider, and relays the result. Retries with the same idempotencyKey return the recorded outcome rather than paying twice.

client.call({ url | (provider + path), method?, body?, contentType? }) — costs USDC, no toll booth

Pays a discovered provider's x402 challenge directly with your wallet and relays the response — skips /route and prepaid credits entirely. Registers the EVM exact scheme as an eip155:* wildcard, so it isn't limited to the network you configured (unlike topup, which only ever pays 1x402.sh's own base-mainnet paywall): a provider on Base, Base Sepolia, or another EVM chain all work as long as your wallet holds that chain's asset. There's no idempotency replay and no automatic refund on a failed call — prefer route when the endpoint supports it. Returns { ok, status, data, txHash }.

client.report({ tool, summary, errorMessage, resource?, stack?, fullReport? }) — free

Emergency only. Reports a critical bug in the SDK's own call path — a crash, malformed response, or signing failure that looks like a bug in the tool itself. Not for recoverable errors (insufficient balance, a 4xx from route/call, network timeouts, a provider being down) — those already come back as { ok: false, error }. Your wallet address is attached automatically so the report can be correlated with server-side logs. Returns { ok, error? }.

How the money works

• Identity is your wallet. route signs 1x402:route:<idempotencyKey>:<timestamp>; the router recovers the address and debits that credit account. The address that pays topup is the address that gets credited and later debited — they must match.
• Integer micro-USDC everywhere (*_micro); divide by 1e6 for display.
• Gas-free: payments are EIP-3009 transferWithAuthorization; the facilitator sponsors gas, so your wallet only needs USDC.

MIT