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.

@x402/core is a required peer dependency: install it yourself (pnpm add radius-sdk @x402/core), and keep any upstream @x402/* adapters on the same version, so the SDK and your app share one copy. @x402/evm and viem are needed only for radius-sdk/client, and Hono only for radius-sdk/hono. The root, server, and Hono entry points do not load viem at runtime.

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.

Proxy to an origin

proxyTo(origin) returns a (request) => Promise<Response> function that forwards a request to an origin you do not change, keeping its method, path, and query. Use it as the paid handler, so paid requests reach the origin after settlement and requests that match no route pass through for free:

import { proxyTo, radiusPayments } from 'radius-sdk/server';
 
const pay = radiusPayments({ network: 'testnet', payTo: '0xYourWalletAddress', routes: { 'POST /v1/score': '0.01 SBC' } });
export default { fetch: pay.wrap(proxyTo('http://127.0.0.1:8000')) };

With Hono, register app.all('/*', (c) => toOrigin(c.req.raw)) after the middleware, where toOrigin = proxyTo(origin). The request goes out without Host, hop-by-hop headers, and payment credentials (PAYMENT-SIGNATURE, X-PAYMENT, Authorization: Payment); other Authorization schemes pass through. A request body is buffered, and the origin is asked for an uncompressed response (Accept-Encoding: identity); if it compresses anyway, the decoded body goes out without Content-Encoding. A client that disconnects aborts the origin request. Redirects are returned, not followed.

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 on the same @x402/* version as the @x402/core you install for the SDK. 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.

Add Radius to an existing x402 server

When your application already owns an x402ResourceServer and drives verify, work, and settle itself, register Radius on it with three functions from radius-sdk/server. They take one options object:

import { x402ResourceServer } from '@x402/core/server';
import { assertRadiusSupported, radiusFacilitators, registerRadius } from 'radius-sdk/server';
 
const radius = { networks: ['mainnet', 'testnet'], settle: 'after' } as const;
 
const server = registerRadius(new x402ResourceServer([...radiusFacilitators(radius), yourFacilitator]), radius);
 
await server.initialize();
assertRadiusSupported(server, radius);

• radiusFacilitators(options) returns one facilitator client per network. Put them first in the list you pass to new x402ResourceServer(...): core sends each network to the first facilitator that lists it, and x402ResourceServer cannot gain facilitators after it is built. Each client reports only its own network.
• registerRadius(server, options) registers the Radius exact scheme for each network and returns server.
• assertRadiusSupported(server, options) throws unless the facilitator from radiusFacilitators reported exact on every network. Call it after server.initialize(): core skips a facilitator it cannot reach while another answers, which would leave Radius offered in 402s but unable to settle, or settled by a facilitator you did not configure. A network answered by another facilitator in your list fails the check too.
• A facilitator call that gets no answer (a network error or a non-x402 error body) throws FacilitatorResponseError: the outcome is unknown, and a settle may have reached the chain. Answer with a 5xx, not as a rejected payment.

settle has no default here, because 'before' skips the facilitator's /verify. With 'before', server.verifyPayment() returns isValid: true without checking the payment, and /settle does the validating, so settle before you do any work. With 'after', verifyPayment() calls /verify as a dry run, then you do the work, then settlePayment(). Use 'after' for a verify, work, settle pipeline.

You build the routes and the 402 yourself in this setup, so radiusPayments options such as mpp and onSettled do not apply; register server.onAfterSettle(...) for settlement callbacks.

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.
• A request whose 402 comes after a redirect is paid at the final URL, repeating the original method and body (a POST that fetch turned into a GET on a 301, 302 or 303 is paid as a POST). A redirect after payment is followed without payment headers, and the receipt is read from it.

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.

watchTransfers queries up to head - 5000n on Radius mainnet and testnet: a five-second visibility delay, separate from transaction finality. blockLag overrides this nonnegative number of block-number units; it defaults to zero on other chains. Clients without a chain must set it explicitly for Radius. Without fromBlock, watching begins after the first observed head and waits for the lagged boundary to reach it. getTransfers remains an immediate snapshot unless you pass a lagged toBlock.

The watcher awaits each onTransfer and then onCheckpoint before advancing to the next chunk. Return the persistence promise from both callbacks. A thrown error or rejected promise retries the chunk, including previously delivered transfers. Stopping prevents further delivery but cannot cancel an in-flight callback.

A checkpoint is the inclusive end of a successfully processed query, not a completeness watermark. Receipts and logs can appear after their timestamp, and five seconds is not a guaranteed maximum delay. Use this ingestion contract:

1. Persist each event and its downstream effect atomically, with a unique key of (chainId, transactionHash, logIndex). transferKey supplies only the last two fields; namespace it by chain. Do not key on block number or transaction index.
2. Persist the checkpoint only after all effects are durable. Store cursors separately for each chain, token and filter configuration. Restart at the persisted checkpoint plus one to retry unacknowledged work, or earlier for overlap.
3. Periodically re-scan an overlapping historical window with getTransfers, using the same durable deduplication. Choose the window from measured visibility delays and recovery requirements. Keep replay progress separate from the forward cursor. A finite window cannot recover arbitrarily late logs; reconcile older intervals as needed.
4. Track a separate verified-through watermark only for intervals reconciled against an authoritative source with confirmed coverage. See receipt archive backfill for availability limits.

Delivery is replayable, not exactly once. Sorting is within each chunk by block number and log index; replay may deliver older events later, and these fields do not establish global execution order on Radius.

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 only (method="evm", intent="charge"). 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.

This is not a drop-in for a server whose MPP rail is Tempo through mppx. A Tempo challenge has method="tempo" and a different request; the SDK never emits one, and createRadiusFetch rejects it with no_compatible_offer. To accept Radius on such a server, add Radius over x402 (above), or add mppx's own evm method alongside Tempo.

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