SDK quickstart

Create a service in Forge and an API key on its Activity page (Set up API key). Set FORGE_API_KEY on the server. Keep it out of source control and browser code. Use your existing x402 payment middleware and routes.

Node.js · Express
Python · FastAPI

Requires Node.js 20.19+ and Express 4.21 or 5.

server.js

import express from "express"
import { createForge } from "@forgeintel/sdk"

const app = express()
const forge = createForge({
  apiKey: process.env.FORGE_API_KEY,
  agentContext: true, // ask agents who they are, optional; off by default
})

app.use(forge.middleware()) // before your existing x402 middleware
// Keep your existing payment middleware, OpenAPI route, and handlers.

Install: npm install @forgeintel/sdk@0.5.0-beta.17.Both switches are off by default: with only an API key, Forge reports telemetry and changes nothing agents see. With agentContext: true, Forge asks agents for their name and search query and records them when sent, but never rejects a paid call without them; { required: true } requires them. Express details.

Requires Python 3.10+ and an ASGI application.

server.py

import os
from fastapi import FastAPI
from forgeintel import Forge, ForgeMiddleware

app = FastAPI()
# Add your existing x402 middleware and routes first.
forge = Forge(
    api_key=os.environ["FORGE_API_KEY"],
    agent_context=True,  # ask agents who they are, optional; off by default
)
app.add_middleware(ForgeMiddleware, forge=forge)

Install: python -m pip install forgeintel-sdk==0.1.0b14.Starlette runs the last added middleware first, so Forge goes outside payment handling. Keep serving server:app. Python details.

Prefer to start from working code? forge-examples has the same paid weather API in Express and FastAPI, with Forge already wired in.

Check the connection

Confirm the SDK’s diagnostics report enabled: true with no configuration errors. Deploy, make an unpaid request to an existing paid route, wait for the background event queue to flush, then select Test connection on the service’s Activity page. This confirms collector contact; it does not prove service ownership or a completed payment. Verification steps.

Start

Integrate

Guides

SDK quickstart

Check the connection

​Check the connection

Check the connection