Configuration

Overview

Pass a configuration object to createLedgergateSdk(). The only required field is apiKey — every other option has a sensible default.

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

const sdk = createLedgergateSdk({
  apiKey: process.env.LEDGERGATE_API_KEY!,

  // Optional — shown with their defaults
  endpoint: "https://api.ledgergate.io/v1/events",
  sampleRate: 1,
  debug: false,

  redaction: {
    hashIp: true,
    allowedHeaders: [],
    // ipHashSalt: "your-custom-salt",
  },

  transport: {
    batchSize: 10,
    flushIntervalMs: 5000,
    maxRetries: 3,
    timeoutMs: 10_000,
  },

  x402: {
    source: "header",
    fieldMapping: {
      address: "x-payment-address",
      amount: "x-payment-amount",
      network: "x-payment-network",
      token: "x-payment-token",
      status: "x-payment-status",
    },
  },
});

Top-level Options

apiKey (required)

apiKey: string

Your Ledger Gate API key. Get one from the dashboard. Never commit this value — always load it from an environment variable.

endpoint

endpoint?: string
// default: "https://api.ledgergate.io/v1/events"

The URL that events are sent to. Override this if you are self-hosting the analytics backend or routing through a proxy.

sampleRate

sampleRate?: number  // 0–1
// default: 1 (100%)

Controls what percentage of requests are tracked. A value of 0.1 samples 10% of traffic. Sampling is evaluated per-request at the start of the middleware.

Note: Unsampled requests are not tracked at all — no request.received event is emitted and no hooks are registered for the response.

// Track 25% of requests
const sdk = createLedgergateSdk({
  apiKey: process.env.LEDGERGATE_API_KEY!,
  sampleRate: 0.25,
});

debug

debug?: boolean
// default: false

When true, the SDK logs internal activity to console. Useful during development to verify events are being queued and sent.

[ledgergate-sdk] Event enqueued (1/10)
[ledgergate-sdk] Flushing 10 events to https://api.ledgergate.io/v1/events
[ledgergate-sdk] Successfully sent 10 events

Always set this to false (or omit it) in production.

redaction Options

Controls what request data is collected and how it is anonymised. See the Privacy & Redaction guide for full details.

redaction.hashIp

hashIp?: boolean
// default: true

When true, the client's IP address is extracted from headers (X-Forwarded-For, X-Real-IP) or the socket, then SHA-256 hashed and truncated to 16 hex characters before being stored. The raw IP is never logged or sent.

Set to false if you do not want to collect IP data at all.

redaction.allowedHeaders

allowedHeaders?: string[]
// default: []

By default, all sensitive headers are replaced with [REDACTED]. Use this allowlist to selectively pass specific headers through.

redaction: {
  allowedHeaders: ["x-custom-token", "x-tenant-id"],
}

Header names in this list are matched case-insensitively.

redaction.ipHashSalt

ipHashSalt?: string
// default: internal constant

A custom salt used when hashing IP addresses. You should set this to a random secret per deployment so that hashes from different deployments cannot be correlated.

redaction: {
  ipHashSalt: process.env.IP_HASH_SALT,
}

transport Options

Controls how events are buffered and delivered to the analytics endpoint.

transport.batchSize

batchSize?: number  // 1–100
// default: 10

The number of events to accumulate before triggering an immediate flush. When the buffer reaches this size, all buffered events are sent as a single HTTP request.

transport.flushIntervalMs

flushIntervalMs?: number  // 100–30000
// default: 5000 (5 seconds)

The time in milliseconds between automatic flushes. Acts as a safety net so events don't sit in the buffer indefinitely on low-traffic APIs.

transport.maxRetries

maxRetries?: number  // 0–5
// default: 3

How many times to retry a failed HTTP batch send before giving up. The SDK uses exponential backoff with ±20% jitter between retries.

Setting this to 0 disables retries entirely.

transport.timeoutMs

timeoutMs?: number  // 1000–30000
// default: 10000 (10 seconds)

HTTP request timeout for each batch send attempt. If the analytics endpoint doesn't respond within this window, the request is aborted and retried according to maxRetries.

x402 Options

Controls how x402 payment metadata is detected in HTTP responses.

x402.source

source?: "header" | "body" | "both"
// default: "header"

Where the SDK looks for payment metadata:

• "header" — Only check response headers (default, lowest overhead)
• "body" — Only check the parsed JSON response body
• "both" — Check both; headers take precedence over body values

To use "body" or "both", you must attach the parsed body to the request/response yourself. See Adapters — Providing a response body.

x402.fieldMapping

fieldMapping?: {
  address?: string   // default: "x-payment-address"
  amount?: string    // default: "x-payment-amount"
  network?: string   // default: "x-payment-network"
  token?: string     // default: "x-payment-token"
  status?: string    // default: "x-payment-status"
}

Custom header or body keys for each payment field. Only override the fields that differ from the defaults.

x402: {
  source: "header",
  fieldMapping: {
    address: "x-btc-address",
    amount: "x-btc-sats",
    network: "x-chain",
  },
}

Sensitive Headers

The following headers are always redacted regardless of configuration:

• authorization
• cookie / set-cookie
• x-api-key
• x-auth-token / x-access-token
• x-csrf-token / x-xsrf-token
• proxy-authorization
• www-authenticate

To allow any of these through, add them to redaction.allowedHeaders. Note that www-authenticate is also parsed for L402/LSAT challenges.

TypeScript

All configuration types are exported from the package:

import type {
  SdkConfig,       // fully resolved config (after defaults)
  SdkConfigInput,  // input type passed to createLedgergateSdk()
  RedactionConfig,
  TransportConfig,
} from "@ledgergate/ledgergate-sdk";

Validation is performed with Zod at runtime. If you pass an invalid value (e.g. sampleRate: 1.5), a ZodError is thrown immediately when createLedgergateSdk() is called — not silently at event-send time.