Quick Start

This guide will show you how to turn any standard API route into a paid, metered endpoint in under 5 minutes using the Atomic Rail Control Plane.

1. Install

Install the framework-agnostic gate package.

npm install @atomic-rail/usage-gate

2. Initialize the Gate

Create a central gate instance. This class is framework-agnostic and handles all the complex x402 payment logic and Registry synchronization for you.

import { AtomicGate, type AtomicGateConfig } from "@atomic-rail/usage-gate";

export const gateConfig: AtomicGateConfig = {
projectId: process.env.METER_PROJECT_ID!,
hmacSecret: process.env.METER_HMAC_SECRET!,
sellerWallet: "0xYourWalletAddress",
};

export const gate = new AtomicGate(gateConfig);

3. Protect Your Routes

Use the gate in your middleware or request handler. It automatically fetches your latest pricing and status from the Action Registry.

// middleware.ts
import { gate } from "./lib/gate";

export default async function middleware(request: Request) {
if (request.url.includes("/api/")) {
const result = await gate.process(request);
if (result.shouldBlock) return result.response;
}
}

4. Meter Your Handler (Metering)

While the middleware handles gating (blocking non-payers), withUsageGate handles metering (sending the event to Atomic Rail). Reuse your gateConfig from Step 2 and use UsageGateRequest to get autocomplete for the payer info.

// api/premium/route.ts
import { withUsageGate, type UsageGateRequest } from "@atomic-rail/usage-gate";
import { gateConfig } from "../../lib/gate";

export const GET = withUsageGate({ actionId: "premium-api", meter: gateConfig }, async (req: UsageGateRequest) => {
// req.payerAddress is now typed and verified
return Response.json({ status: "paid", payer: req.payerAddress });
});

5. Configure Project URLs

Before your integration is fully functional, you must configure your project's connection details in the dashboard.

1. Go to Settings → General.
2. Application Base URL: Set this to where your API is hosted (default: http://localhost:3000). This is used to verify request origins.
3. Facilitator URL: Add the CDP testnet faciliator to your x402 Facilitator URL(default: https://x402.org/facilitator). This is the bridge that handles payment verification.

6. Register Actions (No-Code)

You don't need to hardcode prices or networks anymore.

1. Head to your Atomic Rail Dashboard.
2. Go to the Action Registry.
3. Any new actionId you've used in your code will appear as a "Ghost". Click "Claim" to set the official Price, Network, and Status.
4. Note: If a ghost action doesn't appear, you can manually click "Create Action" and enter your actionId manually.

7. Test in the Playground

No real funds required for testing.

1. Open the Interactive Playground in the dashboard.
2. Select your action and click "Run Simulation".
3. The gate will detect the simulation header, bypass the payment check, and exercise your full pipeline.

Why it's better

• Framework Agnostic: Works in Next.js, Express, Bun, Hono, etc.
• Dynamic Control: Change prices or disable endpoints in the UI—no code redeploys.
• Header-First: Automatically extracts the most accurate price and network from verified wallet transactions.

💡 Pro-Tip: Type Safety

For the best development experience, you can use our built-in TypeScript types:

• AtomicGateConfig: Ensure your central gate initialization has all required fields.
• AtomicGateResult: Get type safety on the result object in your middleware (e.g., result.shouldBlock, result.response).
• UsageGateRequest: As shown in Step 4, this extends the standard Request object with the payerAddress property.