Ledger Gate

Add @ledgergate/ledgergate-sdk to your Express or Fastify server and start tracking x402 payment events in under 5 minutes.

Prerequisites

Before you begin, make sure you have:

A Ledger Gate account — sign up for free
An existing Express or Fastify API
Node.js 18 or later

Step 1 — Get your API key

After signing in, navigate to your dashboard and create a new project. Copy the API key — you'll need it in the next step.

Store it as an environment variable:

# .env
LEDGERGATE_API_KEY=your_api_key_here

Step 2 — Install the SDK

npm install @ledgergate/ledgergate-sdk
# or
pnpm add @ledgergate/ledgergate-sdk
# or
yarn add @ledgergate/ledgergate-sdk

Peer dependencies: express and fastify are optional. Only install the framework you actually use.

Step 3 — Add the middleware

Express

import express from "express";
import { createLedgergateSdk, createExpressMiddleware } from "@ledgergate/ledgergate-sdk";

const sdk = createLedgergateSdk({
  apiKey: process.env.LEDGERGATE_API_KEY!,
  debug: process.env.NODE_ENV !== "production",
});

const app = express();

// Mount middleware before your routes
app.use(createExpressMiddleware(sdk));

app.get("/api/data", (_req, res) => {
  res.json({ message: "Hello from your tracked API!" });
});

app.listen(3000);

// Flush remaining events on shutdown
process.on("SIGTERM", async () => {
  await sdk.shutdown();
  process.exit(0);
});

Fastify

import Fastify from "fastify";
import { createLedgergateSdk, fastifyLedgergate } from "@ledgergate/ledgergate-sdk";

const sdk = createLedgergateSdk({
  apiKey: process.env.LEDGERGATE_API_KEY!,
  debug: process.env.NODE_ENV !== "production",
});

const app = Fastify();

// Register plugin before your routes
await app.register(fastifyLedgergate, { sdk });

app.get("/api/data", async () => {
  return { message: "Hello from your tracked API!" };
});

await app.listen({ port: 3000 });

process.on("SIGTERM", async () => {
  await sdk.shutdown();
  process.exit(0);
});

Step 4 — View your dashboard

Make a few requests to your API, then head to your Ledger Gate dashboard. Within seconds you'll see request events, latency metrics, and x402 payment signals flowing in.

Step 5 — Configure for x402

If your API already returns HTTP 402 responses with payment metadata headers, the SDK detects them automatically. No extra configuration needed.

The SDK reads the following response headers by default:

Header	Description
`x-payment-address`	Payment destination (wallet address, Lightning invoice, etc.)
`x-payment-amount`	Requested payment amount
`x-payment-network`	Payment network (e.g. `bitcoin`, `lightning`, `ethereum`)
`x-payment-token`	Token or currency symbol (e.g. `BTC`, `SATS`, `ETH`)
`x-payment-status`	Current status: `required`, `verified`, or `failed`

To customise these header names or read from the response body instead, see the Configuration guide.

Next Steps

Configuration — Full SDK options reference
Adapters — Deep-dive on Express and Fastify integration
Events — Understand the event schema and lifecycle
Privacy & Redaction — What data is and isn't collected
Advanced Usage — Sampling, custom transport, graceful shutdown

Getting Started