Real-time API metering

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

Use cases

AI/ML APIs

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

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:

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:

// 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

FAQ

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

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

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

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

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

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

Next steps

• Quick Start — Send your first transaction on Radius