Skip to main content
See /concepts/lifecycle for the end-to-end flow (policy → trigger → bond → wait/sell decision).
Polling is wasteful. Subscribe a URL, the API will POST JSON when something happens.

Subscribe

The secret is a 32-byte hex string. Returned exactly once. Store it in a secret manager — there’s no API to retrieve it later.

Available events

Use events: '*' to subscribe to everything for the wallet (recommended for new integrations).

Payload schema

Every delivery is JSON with the same envelope:
Event-specific data shapes:

Headers on every delivery

Verifying the signature (Express example)

Always compare with crypto.timingSafeEqual (or your language’s equivalent constant-time comparator) to prevent timing attacks. Always verify against the raw body, never the JSON-decoded representation.

Retry semantics

  • Acceptance: any 2xx response counts as delivered.
  • 4xx: marked failed permanently (the receiver said no).
  • 5xx / network: retried with exponential backoff (30s · 2^attempt).
  • Max attempts: 3 (so the longest gap from event to final failure is ~150s).
The worker polls the queue every 30 seconds. Latency from event to first delivery attempt is therefore 0–30s. Use X-Lumina-Delivery as a de-duplication key — the same event can be re-delivered if your endpoint times out then later succeeds.

List and revoke

Limits

  • One URL per wallet. Re-registering the same (wallet, url) pair returns 409. Delete and re-create to rotate the secret.
  • Multiple URLs allowed. Different URLs (e.g. dev/staging/prod) can coexist on the same wallet.
  • HTTPS required in production. http://localhost is allowed for testing.