# Accept payments

*Charge for API routes with x402 on Radius*

This guide adds per-request pricing to a [Hono](https://hono.dev) app, such as a Cloudflare Worker, with [`radius-sdk`](/reference/radius-sdk.md). Buyers pay in SBC over [x402](/build/x402.md), and the Radius facilitator settles each payment on Radius before your handler runs. Your server needs a recipient address, not a private key.

## Before you start

* A Hono app. The middleware does no I/O at module scope, so it runs on Cloudflare Workers.
* A wallet address to receive payments. See [Create and fund a wallet](/build/wallet.md).
* To test payments, a second wallet funded with testnet SBC.

## Install

```bash
pnpm add radius-sdk hono
```

## Protect routes

Add `radiusPayments` in front of the routes you want to charge for. This Worker charges 0.001 SBC for `GET /api/lookup` and 0.01 SBC for `POST /api/query`, and pays both to the `PAY_TO` binding:

```typescript
import { Hono } from 'hono';
import { radiusPayments, type RadiusPaymentVariables } from 'radius-sdk/hono';

type Env = { Bindings: { PAY_TO: `0x${string}` }; Variables: RadiusPaymentVariables };
const app = new Hono<Env>();

app.use(
  '/api/*',
  radiusPayments<Env>({
    network: 'testnet',
    payTo: (c) => c.env.PAY_TO,
    routes: {
      'GET /api/lookup': { price: '0.001 SBC', description: 'One lookup' },
      'POST /api/query': '0.01 SBC',
    },
  }),
);

app.get('/api/lookup', (c) => c.json({ result: 'ok' }));
app.post('/api/query', (c) => c.json({ results: [] }));

export default app;
```

Route keys are `METHOD /path` and accept Hono-style `*` wildcards. Requests that match no route pass through for free.

## Set prices

A price is a string in SBC display units (`'0.001 SBC'` or `'0.001'`) or an object in base units (`{ amount: '1000' }`; SBC has six decimals). To price per request, pass a function of the Hono context:

```typescript
routes: {
  'GET /api/report': { price: (c) => (c.req.query('detail') === 'full' ? '0.05 SBC' : '0.01 SBC') },
},
```

A route can also override the recipient with its own `payTo`.

## Test on testnet

Run the app locally, for example with `wrangler dev`, and request a protected route without paying:

```bash
curl -i http://localhost:8787/api/lookup
```

The response is `402 Payment Required` with a `PAYMENT-REQUIRED` header describing the price. Pay it from a funded testnet wallet with [`radius-cli`](/reference/radius-cli.md#x402-endpoint-consumption):

```bash
RADIUS_HOME=.radius RADIUS_NETWORK=testnet \
  radius-cli wallet x402 get http://localhost:8787/api/lookup \
  --x402-threshold 0.01 \
  -y
```

The CLI prints the response and the settlement transaction. A payer that holds only SBC can pay: the Radius facilitator sponsors the one-time Permit2 approval.

## Read the payment in a handler

For a paid request, `c.get('radiusPayment')` holds the receipt: `transaction`, `payer`, `amount`, and `explorerUrl`. To log every payment in one place, pass `onSettled`:

```typescript
radiusPayments<Env>({
  // …
  onSettled: (receipt, c) => console.log('paid', c.req.path, receipt.payer, receipt.transaction),
});
```

The middleware also adds a `PAYMENT-RESPONSE` header carrying the transaction hash, so the buyer gets a receipt too.

## Choose when payment settles

By default, the middleware verifies and settles the payment **before** your handler runs, so the handler only runs for money already received. If the handler then fails, the buyer has paid without getting the resource. Log the transaction hash with the failure so you can refund or serve the resource on retry.

Set `settle: 'after'` to verify the payment, run the handler, and settle only when it responds with a status below 400. This is the x402 default flow: buyers are not charged for an error response, but your handler does its work before the payment is final.

## Go to mainnet

Mainnet needs two configuration changes. Everything else switches with `network`:

| Setting             | Testnet                    | Mainnet                               |
| ------------------- | -------------------------- | ------------------------------------- |
| `network`           | `'testnet'`                | `'mainnet'`, or omit it (the default) |
| `payTo`             | A testnet address          | Your mainnet recipient address        |
| SBC contract        | Selected by `network`      | Selected by `network`                 |
| Facilitator         | Radius testnet facilitator | Radius mainnet facilitator            |
| Facilitator API key | Not needed                 | Not needed                            |
| Buyers pay with     | Testnet SBC                | Mainnet SBC                           |

```typescript
app.use(
  '/api/*',
  radiusPayments<Env>({
    network: 'mainnet',
    payTo: (c) => c.env.PAY_TO,
    routes: {
      'GET /api/lookup': { price: '0.001 SBC', description: 'Reputation lookup for one IP address' },
    },
  }),
);
```

Set the deployed Worker's recipient with `wrangler secret put PAY_TO`, or as a `[vars]` entry in `wrangler.toml`. The server still needs no private key.

The Radius facilitator needs no API key on mainnet or testnet. To use another facilitator that requires one, pass `facilitator: { url, apiKey }`; the key is sent as `x-api-key`. See [Facilitator](/reference/radius-sdk.md#facilitator) in the reference.

## Next steps

* [Tutorial: sell a data lookup](/build/tutorials/sell-data.md) — Build and run a paid Worker step by step
* [radius-sdk reference](/reference/radius-sdk.md) — Every option for `radiusPayments`
* [Make payments](/build/make-payments.md) — Pay x402 endpoints from an app or agent
* [x402 payments](/build/x402.md) — How x402 payments work on Radius
* [`worker-seller` example](https://github.com/radiustechsystems/radius-cli/tree/main/packages/sdk/examples/worker-seller) — A runnable Worker with free and paid routes