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 and Hono entry points do not load viem at runtime.

radiusPayments

Hono middleware that 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.

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. In handlers, c.get('radiusPayment') holds the receipt; add RadiusPaymentVariables to your Hono Variables type to type it.

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.

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:

Wallet helpers

The returned function also has these members:

Receipts

getPaymentReceipt(response, network) decodes a PAYMENT-RESPONSE header and returns undefined when there is none. radiusPayments exposes the same object as c.get('radiusPayment').

Settlements

getSettlement(network, txHash) 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.

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' });

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 for another instance from a chain ID or a viem chain.

Both radiusPayments and createRadiusFetch accept these overrides alongside network:

Facilitator

For radiusPayments, 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 on the first paid request after each cold start
• { timeoutMs } to bound facilitator calls
• a FacilitatorClient from @x402/core/server for a self-hosted facilitator

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 integration
• radius-cli
• x402 facilitator API