Core Concepts

Overview

Atomic Rail lets you monetize any API endpoint with crypto payments. When someone calls your API, they pay directly to your wallet — no intermediaries, no payment processors, no chargebacks.This guide explains the key concepts behind how it all works.

The x402 Protocol

HTTP has a status code that most developers never use: 402 Payment Required. It was reserved for "future use" back in 1999. The x402 protocol finally puts it to work.Here's the flow:

1. A user calls your API endpoint
2. Your server returns 402 Payment Required with payment details
3. The user's wallet pays the specified amount
4. The user retries the request with proof of payment
5. Your server verifies the payment and returns the content

This all happens automatically. The user sees a payment prompt, approves it in their wallet, and gets access — usually in seconds.

Direct Wallet Payments

Unlike traditional payment processors, x402 payments go directly from the user's wallet to yours. There's no middleman holding your funds or taking a cut.Benefits of direct payments:

• Instant settlement — funds arrive immediately
• Zero platform fees — you keep 100% of revenue
• No chargebacks — blockchain payments are final
• Global by default — anyone with a wallet can pay

You provide your wallet address in the configuration, and that's where payments land.

Usage Metering

Payments are great, but you also need to know what's happening. How many requests are you getting? Who's paying? How much revenue per endpoint?Atomic Rail tracks every paid request automatically. When a user successfully pays for your API, we record:

• When it happened
• Which endpoint was called
• The price that was paid
• The payer's wallet address
• Whether the request succeeded or failed

This data flows to your dashboard in real-time, giving you full visibility into your API's usage and revenue.

Projects and Actions

Your Atomic Rail account is organized into Projects. Each project gets its own:

• Project ID for identification
• HMAC Secret for security
• Separate usage tracking
• Independent dashboard view

Within a project, you define Actions. An action represents a specific thing users can pay for — like accessing a premium endpoint, running a computation, or downloading a file. Each action has its own price and shows up separately in your analytics.This structure lets you track exactly which parts of your API generate the most revenue.

HMAC Event Signing

Every usage event is cryptographically signed before it reaches our servers. This prevents tampering and ensures data integrity.

When a paid request completes, your server creates a signature using your project's secret key. We verify this signature before storing the event. If someone tries to send fake events or modify data in transit, the signature check fails and we reject it.

Your secret key never leaves your server. We only see the signature, which proves the event came from you without revealing the key itself.

Non-Blocking Architecture

Metering should never slow down your API. Atomic Rail is designed to be invisible to your users.

When a request completes, the usage event is sent asynchronously — it doesn't block the response. If our servers are temporarily unreachable, your API keeps working normally. Events are logged locally and can be retried.

Your users get fast responses. You get complete analytics. Nothing is compromised.

Supported Networks

Atomic Rail works with multiple blockchains. Users can pay on whichever network they prefer:

• Base (Coinbase's L2 — fast and cheap)
• Ethereum mainnet
• Arbitrum
• Optimism
• Polygon
• Solana

For development and testing, use testnet versions like base-sepolia. No real money involved — just grab some testnet tokens from a faucet.

What Happens on Failure

If a payment fails or your API returns an error after payment, it's tracked as a failed event. This doesn't charge the user twice — the original payment already went through.

Failed events show up in your dashboard with a different status, so you can monitor error rates and debug issues. The success rate metric helps you understand your API's reliability at a glance.

Next Steps

Now that you understand the concepts, you're ready to:

• Follow the Quick Start to build your first paid endpoint
• Explore the Dashboard Guide to analyze your usage data
• Learn about Security best practices for production