See /concepts/lifecycle for the end-to-end flow (policy → trigger → bond → wait/sell decision).
Subscribe
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:data shapes:
Headers on every delivery
Verifying the signature (Express example)
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).
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://localhostis allowed for testing.