Quickstart

This assumes an Express app with @x402/express (x402 v2). For x402 v1 or another framework, see Integrations.

Get an API key

In Forge, open your project’s Agents page and create an API key (it starts with forge_). It’s shown once. The same page shows your backendUrl, which ends in /api/sdk/v2.

Install

npm install @forgeintel/sdk@beta

Mount the middleware before your payment middleware

server.js

import { paymentMiddleware } from "@x402/express";
import { createForge } from "@forgeintel/sdk";

const forge = createForge({
  apiKey: process.env.FORGE_API_KEY,     // forge_…
  backendUrl: process.env.FORGE_BACKEND_URL,  // from your Agents page, ends in /api/sdk/v2
  publicUrl: "https://api.example.com",       // this service's public origin
});

const app = express();
app.use(forge.middleware());                        // 1. Forge first
app.use(paymentMiddleware(routes, resourceServer)); // 2. your x402 setup, unchanged

Order matters. Forge has to see the 402 challenge and the paid response on their way out.

Flush events on shutdown

process.on("SIGTERM", () => server.close(() => forge.shutdown()));

Check it

Inspect a paid route without paying:

npx awal x402 details "https://api.example.com/your/paid/route"

The output should show the rating sentence at the end of the description, and a forge-feedback block under Extensions. See Verify your setup for more checks.

publicUrl is required and never taken from the request’s Host header, which anyone can fake. It’s the origin agents see in rating URLs.

How it works: what Forge changes, and why each change is safe.
OpenAPI: let discovery tools (such as agentcash) show the rating routes before the call.

Get started

Integrations

Guides

Next

​Next

Next