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:

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. radiusPayments exposes the same object as 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

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