Ledger Gate

HTTP API reference for the Ledger Gate analytics endpoint — authentication, the events payload format, and response codes.

Overview

The Ledger Gate analytics API accepts batches of structured events from the SDK and stores them for your dashboard. The SDK handles all communication automatically — you only need this reference if you are building a custom adapter, testing event delivery, or integrating from a non-Node.js environment.

Base URL

https://api.ledgergate.io/v1

Authentication

All requests must include your API key as a Bearer token:

Authorization: Bearer <your-api-key>

Get your API key from the dashboard. API keys are scoped to a project.

`POST /events`

Ingest a batch of analytics events.

Request

Headers

Header	Value
`Authorization`	`Bearer <api-key>`
`Content-Type`	`application/json`

Body

An array of one or more AnalyticsEvent objects (schema version "1.0"):

[
  {
    "schemaVersion": "1.0",
    "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "eventType": "request.received",
    "timestamp": "2026-03-10T12:00:00.000Z",
    "request": {
      "id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
      "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"
    }
  }
]

The maximum batch size accepted is 100 events per request. The SDK's default transport.batchSize is 10.

Event schema

Field	Type	Required	Description
`schemaVersion`	`"1.0"`	✓	Must be exactly `"1.0"`
`eventId`	`string (UUID v4)`	✓	Unique ID for this event
`eventType`	`string`	✓	One of the event types
`timestamp`	`string (ISO 8601)`	✓	When the event occurred
`request.id`	`string (UUID v4)`	✓	Correlation ID shared by all events for the same HTTP request
`request.method`	`string`	✓	HTTP method (uppercase)
`request.path`	`string`	✓	Normalised path, no query string
`request.statusCode`	`integer`	—	HTTP response status code
`request.latencyMs`	`number`	—	End-to-end latency in milliseconds
`request.clientIpHash`	`string`	—	SHA-256 hashed and truncated client IP
`request.headers`	`object`	—	Redacted request headers
`payment`	`object`	—	x402 payment metadata (see below)
`payment.isRequired`	`boolean`	✓ (if `payment` present)	Whether a 402 was returned
`payment.address`	`string`	—	Payment destination
`payment.amount`	`string`	—	Requested amount
`payment.network`	`string`	—	Payment network
`payment.token`	`string`	—	Token or currency symbol
`payment.status`	`"required" \| "verified" \| "failed"`	—	Payment status
`sdk.name`	`string`	✓	SDK identifier
`sdk.version`	`string`	✓	SDK version

Responses

Status	Meaning
`202 Accepted`	Batch received and queued for processing
`400 Bad Request`	Payload failed schema validation — check the `errors` field in the response body
`401 Unauthorized`	Missing or invalid API key
`413 Content Too Large`	Batch exceeds 100 events
`429 Too Many Requests`	Rate limit exceeded — respect the `Retry-After` header
`500 Internal Server Error`	Transient server error — the SDK will retry automatically

202 response body

{
  "accepted": 10
}

400 response body

{
  "error": "validation_failed",
  "errors": [
    { "path": "[0].schemaVersion", "message": "Invalid literal value, expected \"1.0\"" }
  ]
}

Rate Limits

Tier	Requests/min	Events/day
Free	60	50,000
Pro	600	5,000,000
Enterprise	Unlimited	Unlimited

When a rate limit is exceeded, the API returns 429 with a Retry-After: <seconds> header. The SDK retries automatically with exponential backoff.

Idempotency

Each event has a globally unique eventId (UUID v4). The API deduplicates events by eventId — sending the same event twice is safe.

SDK Integration

If you're using one of the supported SDK adapters, you do not need to call this API directly. The SDK manages batching, authentication, retries, and serialisation automatically. See Getting Started to set up the SDK in under 5 minutes.

API Reference