Ledger Gate

Understand the analytics event schema, event types, and the full request lifecycle emitted by @ledgergate/ledgergate-sdk.

Overview

Every HTTP request tracked by the SDK produces one or more structured analytics events. Events are schema-versioned JSON objects sent in batches to the Ledger Gate analytics endpoint.

Events follow an append-only model — they are never modified after emission.

Event Lifecycle

A typical x402-enabled request produces two events:

request.received   ← emitted when the request arrives
       │
  (your handler)
       │
payment.required   ← emitted when a 402 response is sent

A successful paid request produces:

request.received   ← emitted on arrival
payment.verified   ← emitted when the response indicates verified payment

A non-payment request produces:

request.received      ← emitted on arrival
request.completed     ← emitted when the response finishes

Event Types

The SDK emits five event types, defined in the EventType enum:

Event type	Constant	When emitted
`request.received`	`EventType.REQUEST_RECEIVED`	At the start of every sampled request
`payment.required`	`EventType.PAYMENT_REQUIRED`	When the response has HTTP status 402
`payment.verified`	`EventType.PAYMENT_VERIFIED`	When `x-payment-status: verified` is detected
`payment.failed`	`EventType.PAYMENT_FAILED`	When `x-payment-status: failed` is detected
`request.completed`	`EventType.REQUEST_COMPLETED`	For all other responses (non-402)

Payment Status Values

The PaymentStatus enum maps to the values found in the x-payment-status header:

Constant	Value	Meaning
`PaymentStatus.REQUIRED`	`"required"`	Payment is required; client has not paid yet
`PaymentStatus.VERIFIED`	`"verified"`	Payment was verified by the server
`PaymentStatus.FAILED`	`"failed"`	Payment verification failed

Event Schema

All events share the same AnalyticsEvent shape (schema version "1.0"):

interface AnalyticsEvent {
  /** Schema version — always "1.0" in the current release */
  schemaVersion: "1.0";

  /** Unique ID for this event instance (UUID v4) */
  eventId: string;

  /** Event type — one of the EventType values */
  eventType: string;

  /** ISO 8601 timestamp of when the event was built */
  timestamp: string;

  /** Request metadata */
  request: {
    /** Correlation ID shared across all events for the same HTTP request */
    id: string;
    /** HTTP method, always uppercase (GET, POST, …) */
    method: string;
    /** Normalised path without query string */
    path: string;
    /** HTTP response status code (present on all events except request.received) */
    statusCode?: number;
    /** End-to-end latency in milliseconds (present on all events except request.received) */
    latencyMs?: number;
    /** SHA-256 hashed and truncated client IP address */
    clientIpHash?: string;
    /** Redacted request headers */
    headers?: Record<string, string>;
  };

  /** x402 payment metadata — only present on payment.* events and
      request.completed events where payment headers were detected */
  payment?: {
    isRequired: boolean;
    address?: string;
    amount?: string;
    network?: string;
    token?: string;
    status?: "required" | "verified" | "failed";
  };

  /** SDK metadata */
  sdk: {
    name: string;
    version: string;
  };
}

Path normalisation

The request.path field is normalised before being stored:

Query strings are stripped (/api/data?foo=bar → /api/data)
A leading slash is always added if missing
Trailing slashes are removed (except for /)

All events emitted for the same HTTP request share the same request.id (UUID v4), making it straightforward to correlate request.received with its matching completion event in the Ledger Gate dashboard.

Example Events

`request.received`

{
  "schemaVersion": "1.0",
  "eventId": "a1b2c3d4-...",
  "eventType": "request.received",
  "timestamp": "2026-03-10T12:00:00.000Z",
  "request": {
    "id": "f9e8d7c6-...",
    "method": "GET",
    "path": "/api/v1/price",
    "clientIpHash": "3f2a1b9e0c7d4e5f",
    "headers": {
      "accept": "application/json",
      "user-agent": "my-client/1.0",
      "authorization": "[REDACTED]"
    }
  },
  "sdk": {
    "name": "ledgergate-sdk",
    "version": "1.0.0"
  }
}

`payment.required`

{
  "schemaVersion": "1.0",
  "eventId": "b2c3d4e5-...",
  "eventType": "payment.required",
  "timestamp": "2026-03-10T12:00:00.045Z",
  "request": {
    "id": "f9e8d7c6-...",
    "method": "GET",
    "path": "/api/v1/price",
    "statusCode": 402,
    "latencyMs": 45,
    "clientIpHash": "3f2a1b9e0c7d4e5f"
  },
  "payment": {
    "isRequired": true,
    "address": "bc1qexample...",
    "amount": "1000",
    "network": "bitcoin",
    "token": "BTC",
    "status": "required"
  },
  "sdk": {
    "name": "ledgergate-sdk",
    "version": "1.0.0"
  }
}

`payment.verified`

{
  "schemaVersion": "1.0",
  "eventId": "c3d4e5f6-...",
  "eventType": "payment.verified",
  "timestamp": "2026-03-10T12:00:01.120Z",
  "request": {
    "id": "a0b1c2d3-...",
    "method": "GET",
    "path": "/api/v1/price",
    "statusCode": 200,
    "latencyMs": 120
  },
  "payment": {
    "isRequired": false,
    "address": "bc1qexample...",
    "amount": "1000",
    "network": "bitcoin",
    "token": "BTC",
    "status": "verified"
  },
  "sdk": {
    "name": "ledgergate-sdk",
    "version": "1.0.0"
  }
}

`request.completed`

{
  "schemaVersion": "1.0",
  "eventId": "d4e5f6a7-...",
  "eventType": "request.completed",
  "timestamp": "2026-03-10T12:00:00.030Z",
  "request": {
    "id": "e5f6a7b8-...",
    "method": "POST",
    "path": "/api/users",
    "statusCode": 201,
    "latencyMs": 30
  },
  "sdk": {
    "name": "ledgergate-sdk",
    "version": "1.0.0"
  }
}

TypeScript Reference

import {
  type AnalyticsEvent,
  AnalyticsEventSchema,  // Zod schema for validation
  EventType,
  type PaymentStatus,
  PaymentStatus,
} from "@ledgergate/ledgergate-sdk";

Export	Description
`AnalyticsEvent`	TypeScript type for a validated event object
`AnalyticsEventSchema`	Zod schema — use for validation in your own tooling
`EventType`	Enum of all event type string values
`PaymentStatus`	Enum of `"required"`, `"verified"`, `"failed"`

Events