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.

Phase 5 testnet only. The faucet is free, public (no signup), throttled, and runs on Base Sepolia (chainId 84532). It hands out a mintable mUSDC — see the important footnote below before attempting a real policy purchase with it.
Two ways to claim:
  • Humans — click the Get test USDC button on lumina-org.com/faucet and paste your wallet address.
  • Agents — POST directly to the endpoint below.

​
Endpoint

POST https://lumina-api-production-ac85.up.railway.app/api/v1/faucet/claim
Content-Type: application/json

{ "wallet": "0xYourWalletAddress" }

​
curl

curl -X POST https://lumina-api-production-ac85.up.railway.app/api/v1/faucet/claim \
  -H "Content-Type: application/json" \
  -d '{ "wallet": "0xYourWalletAddress" }'

​
TypeScript (SDK)

SDK 0.6.x does not yet expose lumina.faucet.claim() — that helper is planned for v0.7. Until then, agents should call the endpoint directly: 
const res = await fetch(
  'https://lumina-api-production-ac85.up.railway.app/api/v1/faucet/claim',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ wallet: '0xYourWalletAddress' }),
  },
)
const { ethTxHash, usdcTxHash, mockUsdcAddress, nextEligibleAt } = await res.json()

​
What you get

AssetAmountBase units (6 dec for USDC, 18 dec for ETH)
mUSDC10,00010000000000
ETH (for gas)0.0550000000000000000
Both arrive in the same wallet you pass, in a single faucet call, each confirmed on Base Sepolia. The response shape is verbatim: 
{
  "success":          true,
  "ethTxHash":        "0x…",
  "usdcTxHash":       "0x…",
  "ethAmount":        "0.05",
  "usdcAmount":       "10000",
  "mockUsdcAddress":  "0xD944d8e5D8329994D83950872Ec210891d3Ab6AE",
  "nextEligibleAt":   "2026-05-24T18:00:00.000Z"
}

​
Limits

LimitValue
Per claim10,000 mUSDC + 0.05 ETH
Per wallet cooldown24 hours
Per IP cooldown24 hours
Global daily cap50 claims / 24h
StorageSQLite-backed (relayer-side)

​
Errors

Errors return { error, code } with HTTP 4xx/5xx and an optional Retry-After header (seconds) on rate-limit responses.
HTTPcodeMeaningResolution
400invalid_requestMissing or malformed wallet fieldSend { "wallet": "0x…" } with a checksummed EOA
429wallet_rate_limitedThis wallet already claimed in the last 24hWait until nextEligibleAt or use a different wallet
429ip_rate_limitedThis IP already claimed in the last 24hWait or use a different network egress
429daily_cap_reachedGlobal 50-claim daily cap exhaustedWait for UTC rollover
503out_of_ethRelayer ETH balance too low to fund 0.05 ETHPing the team — relayer top-up needed

​
Status endpoint

GET /api/v1/faucet/status is unauthenticated and returns: 
{
  "relayerEthBalance":   "0.8421",                             // ETH float, relayer wallet
  "relayerUsdcBalance":  null,                                 // null because mUSDC is mintable (no float)
  "mockUsdcAddress":     "0xD944d8e5D8329994D83950872Ec210891d3Ab6AE",
  "usdcPerClaim":        "10000",
  "ethPerClaim":         "0.05",
  "cooldownHours":       24,
  "claimsLast24h":       7,
  "dailyCap":            50,
  "enabled":             true
}
Use it before claiming to confirm enabled: true and that claimsLast24h < dailyCap.

​
mUSDC contract details

FieldValue
Address0xD944d8e5D8329994D83950872Ec210891d3Ab6AE
NetworkBase Sepolia (84532)
Decimals6 (same as canonical USDC)
MintablePermissionless — anyone can call mint(address to, uint256 amount) directly
ExplorerBaseScan
If you’d rather skip the rate-limited faucet entirely, call mint(to, amount) yourself via cast, viem, or ethers — there is no allowlist on the mock contract. The faucet is only useful for clients that also need the 0.05 ETH gas top-up. 
cast send 0xD944d8e5D8329994D83950872Ec210891d3Ab6AE \
  "mint(address,uint256)" 0xYourWallet 10000000000 \
  --rpc-url https://sepolia.base.org --private-key $PK

​
Payment token

mUSDC (0xD944d8e5D8329994D83950872Ec210891d3Ab6AE) is the configured payment token across the protocol. CoverRouterV2 (and TWAPBurner) were reconfigured to use mUSDC, so policy purchases paid with the minted mUSDC settle cleanly — transferFrom(buyer, vault, premium) succeeds. The faucet mints this same mUSDC, so funds you receive here are exactly what the protocol expects.
  • Use mUSDC for: real policy purchases on Base Sepolia, SDK smoke tests, contract reads, allowance flows, tooling, monitoring integrations — every path, including the ones where CoverRouter pulls USDC.
  • There is no separate bridged-USDC requirement; the legacy Circle USDC address is no longer used by the live deployment.

​
Next

  • Already have an API key and want to drive policies with your own wallet? See Buy your first policy.
  • Just want the fastest zero-wallet probe? Skip the faucet entirely and go to Sandbox-first — the relayer funds everything for you.