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.

If you are an LLM agent on first contact with Lumina, start here. The sandbox lets you exercise the full purchase path — relayer signs the tx, relayer pays the gas, relayer also pays the premium from a sandbox-funded wallet — without you having to mint an API key or fund a wallet. It’s the smallest possible “did this protocol work end-to-end?” probe.

​
When to use the sandbox

ScenarioUse sandbox?
LLM agent prototyping, first callYes — zero setup
Smoke test in CIYes — cheap, fast, no secrets to inject
Integration check after an SDK upgradeYes — confirms the chain still settles
Production trafficNo — capped to $100/IP/hour
Hedging a real positionNo — the bond is owned by the sandbox wallet, not you

​
Discovery: GET /sandbox/info

Hit this first to confirm the sandbox is enabled and read its current configuration. No auth required. 
curl https://lumina-api-production-ac85.up.railway.app/sandbox/info

{
  "enabled":            true,
  "sandboxWallet":      "0x…",                 // wallet that pays premium + holds the bond
  "coverageCapUsdc":    "100000000",            // $100 per call, in 6-dec USDC
  "asset": {
    "symbol":           "BTC",
    "bytes32":          "0x4254430000…"         // pre-encoded asset literal
  },
  "defaultProductId":   "0xe87625ef…dfeaddd",
  "defaultProductName": "FLASHBTC1H-001",
  "rateLimit": {
    "perIp":            10,
    "windowSeconds":    3600
  }
}

​
Purchase: POST /sandbox/try

curl -X POST https://lumina-api-production-ac85.up.railway.app/sandbox/try \
  -H "Content-Type: application/json" \
  -d '{}'                          # all fields optional — uses defaults

import { LuminaClient } from '@lumina-org/sdk'   // ^0.6.0

// No apiKey needed for the sandbox surface.
const lumina = new LuminaClient({})

const info  = await lumina.sandbox.info()
const trial = await lumina.sandbox.try()         // uses defaultProductName + capped cover

console.log('policyId:', trial.policyId)
console.log('txHash:  ', trial.txHash)
console.log('product: ', trial.productName)

​
Switching shields

Pass productName (or productId) and the API auto-resolves the asset literal from the registry: 
curl -X POST https://lumina-api-production-ac85.up.railway.app/sandbox/try \
  -H "Content-Type: application/json" \
  -d '{ "productName": "FLASHETH24-001" }'        # → asset auto-resolves to ETH

await lumina.sandbox.try({ productName: 'FLASHETH48-001' })

​
Side-by-side: curl ↔ TypeScript

StepcurlTypeScript SDK 0.6
Read configcurl /sandbox/infoawait lumina.sandbox.info()
Default trialcurl -X POST /sandbox/try -d '{}'await lumina.sandbox.try()
Switch product-d '{"productName":"FLASHETH24-001"}'lumina.sandbox.try({ productName: 'FLASHETH24-001' })
Custom cover-d '{"coverageAmount":"50000000"}'lumina.sandbox.try({ coverageAmount: '50000000' })
Both lumina.sandbox.info() and lumina.sandbox.try() are public methods in SDK 0.6.0 (no apiKey required on the client).

​
Body fields

FieldTypeDefaultNotes
productNamestringFLASHBTC1H-001One of the 6 active products. See Products and assets.
productIdbytes32resolved from productNameMutually exclusive with productName.
coverageAmountstring (USDC base units)coverageCapUsdc from /sandbox/infoCapped at 100000000 ($100). Larger values are clamped server-side, not rejected.

​
Limits

LimitValue
Coverage cap per call$100 (100000000 base units)
Rate limit10 calls / hour / IP
WalletSandbox wallet pays premium and holds the resulting bond
Trigger payoutGoes to the sandbox wallet, not you — this is a behavior probe, not a hedge
NetworkBase Sepolia (chainId 84532) — testnet only

​
Transitioning to full onboarding

Once your sandbox call succeeds end-to-end, graduate to the real path:
  1. Mint an API key — one wallet signature, you get an lk_… key.
  2. Fund the buyer wallet with USDC (Base Sepolia faucets are linked in the quickstart). The relayer still pays the gas; the buyer pays only the premium.
  3. Call lumina.policies.purchase(...) with your productName, buyer, and coverageAmount. See First policy.
  4. Subscribe to webhooks for policy_triggered and bond_minted — see Webhooks.
The sandbox is intentionally identical to the production path apart from who owns the buyer wallet and the $100 cap, so code written against lumina.sandbox.try() is one rename away from lumina.policies.purchase().