Skip to main content
The Lumina API is a thin REST surface over the on-chain protocol. The spec served at /openapi.json is the canonical contract — this section is a human-friendly tour.

​
Base URL

Local dev points at http://localhost:3000 by default (override the port via PORT env in the lumina-api repo).

​
Authentication

​
Live OpenAPI / Swagger UI

​
Idempotency

POST /api/v1/policies honours an optional Idempotency-Key header (UUIDv4 recommended). Replays return the cached response without double-spending.

​
Numeric encoding

Every on-chain integer (USDC base units, LUMINA wei, prices) is returned as a decimal string to avoid JavaScript Number precision loss. Convert with BigInt(str).

​
Error envelope

The SDK maps non-2xx into LuminaError with .status, .code, .message.

​
Postman collection

A complete collection is available in the lumina-api repo: docs/lumina-api.postman_collection.json. Import into Postman → set baseUrl and apiKey collection variables → done.

​
Endpoint examples

The next sub-pages walk through GET / CREATE / DELETE / WEBHOOK examples auto-generated by Mintlify from the openapi.json snapshot.