radius-sdk reference

radius-sdk accepts and makes x402 v2 payments on Radius. It defaults to SBC, the Radius facilitator, and mainnet. It can also pay and charge in USDC on Base or any other EVM network (Networks), and speak MPP alongside x402. For task guides, see Accept payments and Make payments.

Source, changelog, and examples: radiustechsystems/tools/packages/sdk. radius-cli wallet pay uses the same client.

Entry points

Requires Node.js 22 or later, or a runtime with fetch such as Cloudflare Workers.

The root, server, and Hono entry points do not load viem at runtime. Install Hono only for radius-sdk/hono; install viem for radius-sdk/client.

radiusPayments

Answers unpaid requests to priced routes with 402 Payment Required, then verifies and settles paid requests through a facilitator. Requests that match no route pass through.

From radius-sdk/server, radiusPayments(options) returns a web-standard handler for Workers, Bun, Deno, and framework route handlers that use Request and Response:

import { radiusPayments } from 'radius-sdk/server';
 
const pay = radiusPayments({
  network: 'testnet',
  payTo: '0xYourWalletAddress',
  routes: { 'GET /api/lookup': '0.001 SBC' },
});
 
export default {
  fetch: pay.wrap((_request, payment) => Response.json({ paidBy: payment?.payer })),
};

From radius-sdk/hono, it returns Hono middleware with the same payment options:

import { radiusPayments } from 'radius-sdk/hono';
 
app.use('/api/*', radiusPayments({ network: 'testnet', payTo: '0xYourWalletAddress', routes: { 'GET /api/lookup': '0.001 SBC' } }));

It also accepts the network overrides. Dynamic payTo and price functions receive the web-standard Request for radius-sdk/server, or the Hono context for radius-sdk/hono; they can return promises. onSettled receives that same context as its second argument.

With settle: 'before', the web-standard handler receives the receipt as its second argument. Hono handlers read c.get('radiusPayment'); add RadiusPaymentVariables to the Hono Variables type. With settle: 'after', payment is not yet settled during the handler; use onSettled to record the receipt.

The SDK initializes the facilitator lazily on the first request matching a priced route, so creating either handler performs no module-scope I/O.

Settlement and streaming

The default settle: 'before' settles before the application handler runs and passes response bodies through without buffering, including SSE and token streams. A handler error or interrupted stream after settlement does not undo the payment. Validate inputs and check resource availability before entering the payment handler; see validate before charging.

settle: 'after' runs the handler first, buffers a successful response body, and settles before returning it. Responses with a status of 400 or higher are not charged. Use 'before' for streaming responses.

onSettled records settlement, not delivery. With 'before', it runs before the application handler. Errors thrown by the hook are logged by x402 core and do not fail the request. Store the receipt and delivery outcome separately.

RouteSpec

Prices

A Price is a string or number in display units of the asset ('0.001 SBC', '0.001', 0.001), or { amount: '1000' } in base units. SBC has six decimals.

createRadiusServer

createRadiusServer(options) from radius-sdk/server supplies the Radius resource server for upstream adapters such as @x402/express, @x402/next, and @x402/hono. It accepts network, settle, gasSponsoring, facilitator, onSettled, and the network overrides. Configure recipients and prices through routes() or handler().

For createRadiusServer, onSettled(receipt, context) receives the x402 request context, which can be undefined. requestOf(context) extracts the web-standard Request when an SDK adapter supplied it. RequestAdapter wraps a Request as an x402 HTTPAdapter for custom integrations.

Use upstream adapters from the 2.27.0 version line, matching the SDK's x402 dependencies. They initialize the facilitator at construction by default. Where module-scope I/O is forbidden, pass the adapter's syncFacilitatorOnStart: false option and await radius.server.initialize() during request handling before invoking the adapter. The SDK's own web-standard and Hono handlers handle lazy initialization for you.

Upstream adapters serve x402 only; MPP needs the SDK's own radiusPayments handler.

See Express and upstream adapters for an example.

createRadiusFetch

Returns a fetch that pays x402 and MPP challenges and retries the request. Responses other than 402 are returned unchanged.

import { createRadiusFetch } from 'radius-sdk/client';
 
const payFetch = createRadiusFetch({ network: 'testnet', signer: process.env.RADIUS_PRIVATE_KEY as `0x${string}`, maxPerRequest: '0.01 SBC' });

It also accepts the network overrides; with networks, they apply to the first network.

Payment rules:

• Pays only on the configured networks, each in its payment asset.
• Takes the first compatible offer within maxPerRequest: protocols in your order, then networks in your order, then offers in the server's order. When the server accepts more than one of your networks, the client first reads the wallet's balance on each, and the first one that covers the price wins, whichever protocol offers it. If none does, it throws insufficient_balance before signing. Set preferFunded: false to skip the balance reads.
• A price in display units is converted for each network's asset; a base-unit maxPerRequest applies to each asset as-is.
• Schemes: x402 v2 exact (Permit2 or EIP-3009) and upto (Permit2), and x402 v1 exact (EIP-3009).
• The signing window is the server's maxTimeoutSeconds, capped at 600 seconds.
• The paid retry never follows a redirect to another origin (redirect_refused).

Offers

onPaymentRequired receives a PaymentOffer, either an x402 offer or an MPP offer:

Approval requests

onApprovalRequired receives an ApprovalRequest for every allowance change: the Permit2 approval a payment needs, approvePermit2(), and approve(). Return false to decline; the call throws declined with the request as details.

Wallet helpers

The returned function also has these members. The wallet helpers act on the first network; on(network) returns them for another one.

Members that send a transaction return a TxResult: hash, status ('success' or 'reverted' from the receipt), and explorerUrl.

Receipts

getPaymentReceipt(response, network) decodes a PAYMENT-RESPONSE (x402) or Payment-Receipt (MPP) header and returns undefined when there is none. With settle: 'before', radiusPayments exposes the receipt as the web-standard handler's second argument or Hono's c.get('radiusPayment').

Settlements

getSettlement(radiusTestnet, txHash) (any PaymentNetwork) from radius-sdk/client, or payFetch.getSettlement(txHash), reads a settlement transaction from the chain. The result has status, blockNumber, transfers (each { from, to, amount } in the payment asset), paid(to?), paidFormatted(to?), and explorerUrl. Use paid(to) for what a recipient received: transfers lists every payment-asset transfer in the transaction, which can include the facilitator's fee conversion.

Balances

On Radius, eth_getBalance includes convertible SBC; see The Turnstile and balances. These viem actions from radius-sdk/client report each part separately:

Each takes an optional blockNumber or blockTag. radiusActions() adds them to a viem client:

import { createPublicClient, http } from 'viem';
import { radiusTestnet } from 'radius-sdk';
import { radiusActions } from 'radius-sdk/client';
 
const client = createPublicClient({ chain: radiusTestnet.chain, transport: http() }).extend(radiusActions());
const balances = await client.getBalances({ address: '0xYourWalletAddress' });

ERC-20 actions

erc20Actions({ token?, network? }) from radius-sdk/client adds token actions to a viem client. The token defaults to the payment asset of the client's chain when it is a preset (SBC on Radius, USDC on Base); on any other chain, name the token. Amounts are base units as bigint or display units as a string, for example '0.01'.

Writes wait for the receipt. Pass wait: false to return as soon as the transaction is sent, with status: 'pending'.

import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { radiusTestnet } from 'radius-sdk';
import { erc20Actions } from 'radius-sdk/client';
 
const wallet = createWalletClient({
  chain: radiusTestnet.chain,
  transport: http(),
  account: privateKeyToAccount(process.env.RADIUS_PRIVATE_KEY as `0x${string}`),
}).extend(erc20Actions());
 
const result = await wallet.transfer({ to: '0xRecipientAddress', amount: '0.01' });
console.log(result.status, result.explorerUrl);

Block numbers on Radius are millisecond timestamps, so 1,000,000 blocks is about 17 minutes; see eth_getLogs.

Permit2 actions

permit2Actions() from radius-sdk/client adds actions for the canonical Permit2 contract. x402 payments use them internally; use them directly to build your own Permit2 flows.

Writes return a TxResult. The EIP-712 helpers and ABI (permit2Domain, PERMIT2_ABI, and the type definitions) are exported too.

MPP

MPP, the Machine Payments Protocol, is the HTTP Payment authentication scheme. radius-sdk speaks its evm charge method. Like x402's exact scheme with EIP-3009, an MPP charge is an EIP-3009 authorization of the network's stablecoin, and the same facilitator settles it. Only the HTTP envelope differs:

Buyers. createRadiusFetch pays both. When a 402 offers both, protocols sets the preference, x402 first by default. MPP payments need no approval and no gas. A request that already sends its own Authorization header is not paid over MPP, because the credential goes in that header.

Sellers. Add mpp to radiusPayments:

const pay = radiusPayments({
  network: 'testnet',
  payTo: '0xYourWalletAddress',
  routes: { 'GET /api/lookup': '0.001 SBC' },
  mpp: { secretKey: env.MPP_SECRET_KEY },
});

Every 402 then also carries an MPP challenge per network. It mirrors the x402 offers that use EIP-3009, with the same price, asset, recipient, and expiry. The challenge ID is an HMAC of the challenge under secretKey, so credentials are checked without stored state. Use at least 32 random characters (openssl rand -base64 32), and the same key on every instance that serves the routes.

The SDK checks the realm (mpp.realm, by default the request's host), the expiry, the route's current price, and the authorization's nonce, which is bound to the challenge. Then the facilitator verifies and settles the payment, before or after the handler as settle says. The handler's receipt and onSettled have protocol: 'mpp', and the response carries Payment-Receipt.

Errors

Seller responses

The SDK's web-standard and Hono handlers return 502 with error: 'facilitator_error' when a facilitator call fails without the facilitator's own answer, such as a dropped connection or gateway error page. Settlement can already have reached the chain. A 502 does not mean nothing moved: reconcile the attempt before authorizing another payment. A facilitator's explicit payment rejection still returns 402.

Buyer errors

Payment failures throw RadiusPaymentError with a code and, for some codes, details:

Networks

A PaymentNetwork carries a viem Chain (radiusTestnet.chain) plus its payment asset, default facilitatorUrl, faucetUrl (Radius only), and the names x402 v1 challenges use for it. definePaymentNetwork({ chain, asset, facilitatorUrl }) builds one for any other EVM network; asset gives the token's address, symbol, decimals, and EIP-712 domain name and version.

Both radiusPayments and createRadiusFetch accept these overrides alongside network:

Prices in display units assume a USD stablecoin, which every preset uses.

Several networks

networks makes a seller offer one payment option per network on every route, in that order. Each network is settled by its own facilitator. Base mainnet has no default facilitator, so name one:

const pay = radiusPayments({
  networks: ['mainnet', { network: 'base', facilitator: { url: 'https://your-base-facilitator.example' } }],
  payTo: '0xYourWalletAddress',
  routes: { 'GET /api/lookup': '0.001' },
});

The same payTo receives on every network. A price in display units is converted for each network's asset. A price that names an asset with { amount, asset } is rejected when there are several networks. Receipts report the network a payment settled on. With networks, top-level facilitator and overrides apply to the first network.

Facilitator

For radiusPayments and createRadiusServer, facilitator takes:

• { url, apiKey } for another hosted facilitator; apiKey is sent as x-api-key
• { live: false } to use the built-in Radius /supported answer instead of fetching it during initialization (Radius networks only)
• { timeoutMs } to bound facilitator calls
• a FacilitatorClient from @x402/core/server for a self-hosted facilitator

The seller offers whichever of eip3009 and permit2 the facilitator lists first for exact, and eip3009 when it names none. The Radius facilitators list eip3009 first. This does not add EIP-3009 support to a token: the configured asset must support the selected transfer method.

Environment variables

radiusEnv(env) reads these variables, using the same names as radius-cli, and returns options to spread into either function. Explicit options take precedence. On Cloudflare Workers, pass c.env.

Examples

Related pages

• Accept payments
• Make payments
• x402 payments
• radius-cli
• x402 facilitator API