radius-sdk reference

radius-sdk accepts and makes x402 v2 payments on Radius. It defaults to SBC, the Radius facilitator, and mainnet. For task guides, see Accept payments and Make payments.

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

Entry points

Requires Node.js 20 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.

See Express and upstream adapters for an example.

createRadiusFetch

Returns a fetch that pays x402 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.

Payment rules:

• Pays only on the configured network and in the configured asset.
• Takes the first compatible offer within maxPerRequest, in the server's order.
• 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:

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:

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 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 RadiusNetwork) 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 (SBC) of the client's Radius chain; 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.

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 RadiusNetwork carries a viem Chain (radiusTestnet.chain) plus facilitatorUrl, faucetUrl, and asset. defineRadiusNetwork builds one from a chain ID or a viem chain.

Both radiusPayments and createRadiusFetch accept these overrides alongside 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
• { timeoutMs } to bound facilitator calls
• a FacilitatorClient from @x402/core/server for a self-hosted facilitator

The seller supports both permit2 and eip3009 when the facilitator advertises them for exact, including facilitators that prefer eip3009. This does not add EIP-3009 support to a token: the configured asset must support the selected transfer method. The documented SBC payment flow uses Permit2.

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