Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lumina-org.com/llms.txt

Use this file to discover all available pages before exploring further.

The agent’s job is one HTTP call. Everything else — gas, on-chain encoding, event scraping for the policyId — happens server-side.

​
Sequence

​
SDK

import { keccak256, toUtf8Bytes } from 'ethers'

const policy = await lumina.policies.purchase({
  productId: keccak256(toUtf8Bytes('FLASHBTC24-001')),
  buyer: '0xYourWalletAddress',
  coverageAmount: '50000000',                  // $50 in 6-dec USDC
  asset: 'USDC',                               // SDK encodes to bytes32 for you
  idempotencyKey: crypto.randomUUID(),         // strongly recommended
})

​
curl

curl -X POST https://lumina-api-production-ac85.up.railway.app/api/v1/policies \
  -H "x-api-key: $LUMINA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "productId":      "0xdc5bcc7d6e2e9ca89d46d4f6672db80985d5e86509243dcca44a4e87d871a7b9",
    "coverageAmount": "50000000",
    "asset":          "0x5553444300000000000000000000000000000000000000000000000000000000",
    "buyer":          "0xYourWalletAddress"
  }'

​
Field deep-dive

  • productId — bytes32 hash. Compute as keccak256(toUtf8Bytes('FLASHBTC24-001')). Pre-computed values are listed in Shields.
  • coverageAmount — string of USDC base units. $50 = "50000000". Always pass as a string to preserve precision.
  • asset — bytes32 of the asset symbol. ethers.encodeBytes32String('USDC') = 0x5553444300…0000. The SDK accepts the symbol 'USDC' and encodes for you.
  • buyer — the wallet that pays the USDC premium (NOT the relayer). Must hold ≥ premium and have approved the relayer-side spender.

​
Idempotency

Pass Idempotency-Key: <uuidv4> on every retryable purchase. Replays return the original response without double-spending. The key is scoped per agent; it’s safe (and good practice) to derive a fresh UUID per logical attempt.

​
Errors

HTTPCodeRetry?
400validation_errorNo
401invalid_api_keyNo
422shield_pausedMaybe later
422exceeds_capacityMaybe later
429rate_limitYes (backoff)
5xxserver_errorYes (≤3 attempts)