---
title: Real-time API Metering
description: Charge per API call with instant settlement on Radius using verifiable payments, metering logic, and developer-friendly flows.
---
# Real-time API metering

*Charge per API call with instant on-chain settlement*


Use this guide to implement per-request billing with instant settlement on Radius.

## Problem statement

Conventional API billing relies on monthly invoices processed with credit card rails. In practice, this means API providers are extending credit for services rendered for 30+ days while also paying 2.9% + 0.30 USD in transaction fees. For agents procuring services in real-time for sporadic, bursty workloads, this model is insufficient.

Radius solves this with real-time, per-request billing. Each API call includes payment that settles instantly. No credit card fees. No counterparty risk. No intermediaries.

## How it works

When a client calls your API:

1. **Client sends payment proof** — The client constructs a microtransaction on Radius and includes proof in the API request
2. **Server verifies payment** — Your API server verifies the payment on Radius in milliseconds
3. **Request executes** — If payment is valid, your API processes the request
4. **Instant settlement** — The payment is finalized within seconds, and you control the tokens immediately

Total latency: sub-second verification + your API response time. No batch processes. No waiting for settlement.

## Benefits over traditional API billing

| Feature                 | Traditional              | Radius                |
| ----------------------- | ------------------------ | --------------------- |
| **Payment fees**        | 2.9% + 0.30 USD          | 0.00010 USD per transfer |
| **Settlement time**     | 30+ days                 | Seconds               |
| **Chargebacks**         | Common, costly           | Impossible (on-chain) |
| **Global access**       | Credit card required     | Wallet + USD only     |
| **Minimum transaction** | 5–10 USD                 | 0.00010 USD   |
| **Revenue control**     | Intermediary takes a cut | You control 100%      |

## Use cases

### AI/ML APIs

Charge per inference or per token. Users pay only for what they use, instantly:

```typescript
const costPerToken = parseEther('0.000001'); // Per token charged
const tokensGenerated = 150;
const totalCost = BigInt(tokensGenerated) * costPerToken;

// Client pays before using the API
const hash = await walletClient.sendTransaction({
  to: apiServer,
  value: totalCost,
});
```

### Premium data feeds

Real-time stock prices, weather data, sports stats—charge per request:

```typescript
app.post('/api/stock-price', async (req, res) => {
  const { symbol, paymentHash } = req.body;

  // Verify payment for premium data
  const payer = await verifyPayment(paymentHash, PREMIUM_DATA_COST, serverAccount.address);

  if (!payer) {
    return res.status(402).json({ error: 'Payment required' });
  }

  // Return premium stock price data
  res.json({ symbol, price: 123.45, timestamp: Date.now() });
});
```

### Content APIs

Charge for access to paywalled articles, ebooks, or videos:

```typescript
// Client pays for each piece of content
const contentId = '123-article-slug';
const hash = await walletClient.sendTransaction({
  to: publisherAddress,
  value: ARTICLE_COST,
});

// Request with proof of payment
const content = await fetch('/api/articles/' + contentId, {
  headers: { 'X-Payment-Hash': hash },
});
```

## Best practices

- **Show pricing upfront** — Let users know the cost before sending payment
- **Batch requests** — Allow clients to send multiple queries in one payment
- **Discounts for volume** — Offer lower per-request costs for bulk prepayment
- **Error handling** — Handle failed payments gracefully; return 402 Payment Required
- **Monitoring** — Track payment success rates and processing times

## Related workshop projects

- [`merchant-console-demo`](https://github.com/radius-workshop/merchant-console-demo) — Threat-intelligence API demo with x402-gated endpoints, live settlement stats, and paid agent traffic visualization
- [`rad-router-proxy`](https://github.com/radius-workshop/rad-router-proxy) — Local proxy that lets AI IDEs pay Rad Router through x402 on Radius
- [`radius-agent-contracts`](https://github.com/radius-workshop/radius-agent-contracts) — Includes a `PayPerQuery` contract for pre-funded metered API usage
- [Workshop playground](/use-cases/workshop-playground) — Catalog of public Radius sample and demo repositories

## FAQ

**How long does payment verification take?**

Sub-second. Radius achieves near-instant finality, so payment verification completes in milliseconds.

**Can clients batch multiple requests into one payment?**

Yes. You can structure pricing around request batches or data volume rather than individual calls.

**What if a payment transaction fails?**

The transaction fails on-chain with no side effects. Your API returns 402 Payment Required, and the client can retry.

**Do I need a smart contract?**

No. Native token transfers work perfectly. Only use smart contracts if you need complex payment logic (for example, split payments, conditional refunds).

**Can I refund payments?**

Yes, by sending tokens back to the client. You control the server wallet and can execute refund transactions directly.

**How do I handle pricing changes?**

Update your server code and redeploy. Clients see the new pricing immediately. Consider a grace period for old prices.

## Next steps

- **[Quick Start](/get-started/claim-and-transact)** — Send your first transaction on Radius
- **[x402 integration](/developer-resources/x402-integration)** — Add HTTP-native payment negotiation to an API