@atomic-rail/usage-gate

Registry-first API monetization with automated metering

Turn any API route into a paid endpoint in minutes.
Everything—pricing, gating, and status—is managed from your dashboard.

✨ Features

• 💰 Registry-First — Change prices or disable endpoints from your dashboard without redeploying code.
• 📊 Automatic Metering — Every request tracked with verified payer info.
• 🔐 HMAC-Signed Verification — Secure communication between your API and the Action Registry.
• ⚡ Framework Agnostic — Works with Next.js, Express, Hono, Bun, and more.
• 🌐 Direct Payments — Funds go straight from the payer to your wallet via x402.

📦 Installation

npm install @atomic-rail/usage-gate

🚀 Quick Start

1. Install

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 } from "@atomic-rail/usage-gate";

export const gate = new AtomicGate({
  projectId: process.env.METER_PROJECT_ID!,
  hmacSecret: process.env.METER_HMAC_SECRET!,
  sellerWallet: "0xYourWalletAddress",
});

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.

import { gate } from "./lib/atomic";

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

Wrap your route handler with withUsageGate to emit usage events to your dashboard and access the verified payerAddress.

import { withUsageGate } from "@atomic-rail/usage-gate";

const config = {
  actionId: "premium-api",
  meter: {
    projectId: process.env.METER_PROJECT_ID!,
    hmacSecret: process.env.METER_HMAC_SECRET!,
  }
};

export const GET = withUsageGate(config, async (req) => {
  return Response.json({
    status: "paid",
    payer: req.payerAddress,
  });
});

5. 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".
4. Click "Claim" to set the official Price, Network, and Status.

🔄 How It Works

1. Registry Fetch: The AtomicGate fetches your latest pricing and status from the Atomic Rail Action Registry.
2. Payment Verification: If a route is gated, the gate verifies the PAYMENT-SIGNATURE header via the x402 protocol.
3. Metering: withUsageGate emits an HMAC-signed event to the Atomic Rail meter service after your handler successfully executes.
4. Analytics: Real-time revenue and usage stats appear in your dashboard.

⚙️ Configuration

AtomicGateConfig

| Option | Description | | -------------- | ----------------------------------------------- | | projectId | Your Project ID from the Atomic Rail dashboard. | | hmacSecret | Your HMAC Secret for signing registry requests. | | sellerWallet | The EVM address where payments should be sent. | | debug | Enable verbose logging for development. |

📋 Requirements

• Node.js 18+ (or Bun/Deno with Web Standard APIs)
• Any framework using Web Standard Request/Response
• No complex x402 configuration required (handled by AtomicGate)

❓ FAQ

Where do payments go?
Directly to your wallet. We don't touch your funds — only track usage and provide the gating infrastructure.

What if the Action Registry is down?
AtomicGate uses a stale-while-revalidate caching strategy. If the registry is unreachable, it uses the last known configuration to ensure your API stays live.

How do I view analytics?
Sign in at atomicrail.com and check your project dashboard.

📄 License

MIT © Atomic Rail