Connect Your AI Agent to Lumina

From zero to insured in 10 minutes. No blockchain knowledge needed.

① Connect — ② Approve — ③ Configure — ④ Test

Think of it like this: You give your AI agent a credit card (API Key) with a spending limit (Approve). The agent decides when to buy insurance for protection, or when to deposit into Lumina vaults to generate yield — all based on rules you define.

What You Need

Item	What It Is	Where to Get It
Wallet	MetaMask, Coinbase Wallet, or Rainbow	metamask.io
USDC	USDC stablecoin by Circle	coinbase.com
ETH on Base	For one-time approval (~$0.01)	Bridge or buy on Base

Step 1: Create Your API Key

1 Get your key (shown only once!)

→ Step 1 of 2: Connect your wallet

→ Step 2 of 2: Generate your key

For developers: alternative method (terminal) ▸

Replace YOUR_WALLET with your actual wallet address:

curl -X POST https://lumina-protocol-production.up.railway.app/api/v2/keys/create \
  -H "Content-Type: application/json" \
  -d '{"wallet":"YOUR_WALLET_ADDRESS","label":"my-agent"}'

Step 2: Approve USDC Spending

2 Set your spending limit

This tells your USDC: "Lumina can charge me up to $X for insurance." You control the limit and can revoke it anytime by setting it to 0.

For developers: alternative method (terminal) ▸

cast send 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
  "approve(address,uint256)" \
  0xd5f8678A0F2149B6342F9014CCe6d743234Ca025 \
  10000000000 \
  --rpc-url YOUR_RPC_URL --interactive

This is your risk limit. 10000000000 in 6 decimals = $10,000 max. Your agent cannot spend more than this. Revoke anytime by setting to 0.

Step 3: Give Your Agent the Key + SKILL File

3 Two things your agent needs

3a — What is an AI Agent?

What is an AI Agent?

An AI agent is a ChatGPT, Claude, or custom bot that can take actions on your behalf. In Lumina, your agent monitors markets and buys insurance automatically — you just set the rules.

Don't have an agent yet? Here are 3 easy ways to start:

💬 Option A — ChatGPT or Claude (easiest, 2 minutes)

Open ChatGPT or Claude
Start a new conversation
Paste the SKILL file content (download below)
Tell it: "My Lumina API key is: lum_xxxxx. You are now my insurance agent."
That's it — the AI now knows how to use Lumina

🤖 Option B — Claude Code (automated setup)

Go back to the main page and click "Getting Started" → "Auto-Setup (Claude Code)". Copy the setup prompt and paste it into Claude Code terminal. It configures everything automatically.

🔧 Option C — Custom Agent (developers)

If you're building with ElizaOS, LangChain, or a custom framework: set LUMINA_API_KEY as an environment variable, include the SKILL file in your agent's knowledge base, and use the API endpoints documented in the SKILL file.

🔒 Option D — OWS Wallet (most secure)

For autonomous agents running 24/7. Uses Open Wallet Standard for policy-gated signing — your private key is encrypted and every transaction is validated before signing.

Install OWS: curl -fsSL https://openwallet.sh/install.sh | bash
Run setup: git clone https://github.com/org-lumina/LUMINA-PROTOCOL.git && cd LUMINA-PROTOCOL/ows && ./setup-lumina-agent.sh my-agent
Save the ows_key_xxx token and fund the wallet with USDC + ETH on Base
Your agent now has: Base-only restriction, contract allowlist, $10K/day limit, auto-expiry

Requires Linux or macOS. Full OWS documentation →

3b — The Key

🔑 The Key (API Key)

Your agent's authorization to spend

Give this key to your AI agent so it can authenticate with Lumina. How you do it depends on your agent:

💬 Using ChatGPT or Claude?

Paste your API key directly in the chat along with the SKILL file. Tell your agent: "My Lumina API key is: lum_xxxxx. Use it for all Lumina API calls."

🤖 Using ElizaOS or a custom framework?

Set it as an environment variable:

LUMINA_API_KEY=lum_your_key

🔧 Building your own agent?

Include the key in the X-API-Key header of every API call:

-H "X-API-Key: lum_your_key"

⚠️ Keep your API key secret. Anyone with this key can make your agent spend USDC. Never share it publicly.

3c — The Map

🧠 The Map (SKILL File)

Your agent's knowledge of Lumina

This file teaches your agent everything: products, endpoints, pricing, and rules. Without it, your agent doesn't know Lumina exists.

📥 Download LUMINA-SKILL.txt

💡 Tip: Paste this file into your agent's chat (ChatGPT, Claude, or any LLM) so it learns the protocol rules automatically.

✅ Checklist before moving to Step 4

I saved my API Key somewhere safe I downloaded the SKILL file I gave both to my AI agent

Step 4: Test — Buy Your First Policy

4 Verify Everything Works

Your agent is ready! Here's how to test:

💬 Using ChatGPT or Claude?

Tell your agent: "Buy a BTC Catastrophe Shield for $100, 7 days duration." Your agent will call the Lumina API and respond with a confirmation including the policy ID.

🤖 Using Claude Code?

The auto-setup already ran a test purchase. Check the output for "success": true.

🔧 For developers: test with curl

curl -X POST https://lumina-protocol-production.up.railway.app/api/v2/purchase \
  -H "Content-Type: application/json" \
  -H "X-API-Key: lum_your_key_here" \
  -d '{"productId":"BCS","coverageAmount":100000000,"durationSeconds":604800}'

This buys $100 BTC Catastrophe Shield for 7 days.

After your first purchase, check the Dashboard to see your active policy.

Emergency Stop (Kill Switch)

If something goes wrong — revoke the approval:

Set the approval to 0. This instantly stops all purchases.

Option 1 — Use this page (easiest)

Connect your wallet in Step 1 above
Go to Step 2, set the amount to $0
Click Approve with MetaMask

Option 2 — Use Basescan

Go to the USDC contract write page on Basescan
Connect your wallet on Basescan
Call approve() with:
spender = 0xd5f8678A0F2149B6342F9014CCe6d743234Ca025 (CoverRouter)
amount = 0

Option 3 — Revoke OWS key (if using OWS)

If your agent uses OWS, revoke its API key:

ows key revoke --name my-agent-key

This instantly disables the agent's signing capability. The wallet and funds are unaffected.

Both options instantly revoke your agent's ability to spend USDC. No private key needed.

🛡 Insurance Products

Parametric coverage for your AI agent's portfolio. Your agent buys these policies via the API to protect against specific risks.

Quick reference — view full details on the main page

Product	ID	Protects Against	Duration	Deductible
BTC Catastrophe Shield	`BCS`	BTC crash ≥50%	7-30d	20%
ETH Apocalypse Shield	`EAS`	ETH crash ≥60%	7-30d	20%
Depeg Shield	`DEPEG`	USDT or DAI loses peg	14-365d	USDT:15% / DAI:12%
IL Index Cover	`IL`	Impermanent loss	14-90d	2%
Exploit Shield	`EXPLOIT`	External protocol hacks (excl. Aave)	90-365d	10%

Your agent decides when to buy based on market conditions. Policies are purchased and claimed automatically via the API. You only set the spending limit.

💰 Yield Vaults

Deposit USDC into vaults to earn yield from insurance premiums. Your agent manages deposits and withdrawals.

Vault	Lockup	Risk Profile	What it covers
Volatile Short	37 days	Higher risk/yield	BCS + EAS + IL claims
Volatile Long	97 days	Higher risk/yield	BCS + EAS + IL claims
Stable Short	97 days	Lower risk/yield	DEPEG + EXPLOIT claims
Stable Long	372 days	Lower risk/yield	DEPEG + EXPLOIT claims

Yield = Aave V3 lending APY (~3-5%, variable) + insurance premiums. Your USDC is deposited into Aave V3, the largest lending protocol in DeFi. Longer lockups generally offer higher yields. Your agent monitors APY and manages positions through the API.

Need Help?

Email support@lumina-org.com or visit the Dashboard.

Lumina Protocol — Insurance for the Machine Economy