Onboarding (mint your API key)

API keys are minted via wallet signature, not via a request to a human admin. The flow is one signature → one POST → one lk_… plaintext key.

Want to try the protocol without minting a key first? Use Sandbox-first — POST /sandbox/try lets you buy a real Base mainnet policy with no API key and no wallet.

Wallet prereqs: a Base mainnet EOA with a bit of ETH to sign onboarding (signing is gasless, but you’ll want gas before any later wallet-side ops). Need test USDC + 0.05 ETH for gas? Use the faucet — one POST funds the wallet you pass.

The flow

Build the canonical message: Lumina onboarding for {address} at {timestamp}.
Sign it with your wallet (EIP-191 personal_sign).
POST {walletAddress, signature, timestamp, label} to /api/v1/agent/onboard.
The API verifies the signature recovers to walletAddress, then mints a key.
The plaintext key (lk_…) is in the response body — store it now, it is never returned again.

The wallet’s private key never leaves your process — only the signature goes over the wire. The server cannot impersonate the wallet because it doesn’t hold the private key.

SDK

import { Wallet } from 'ethers'
import { LuminaClient } from '@lumina-org/sdk'

const wallet = new Wallet(process.env.PRIVATE_KEY!)
const lumina = new LuminaClient({ apiKey: '' })

const result = await lumina.agent.onboard(wallet, { label: 'my-trading-bot' })
console.log(result.apiKey)         // "lk_…" — store this now

curl

ADDRESS=0xYourWalletAddress
TIMESTAMP=$(date +%s)
MESSAGE="Lumina onboarding for ${ADDRESS} at ${TIMESTAMP}"
SIGNATURE=$(cast wallet sign "$MESSAGE" --private-key "$PRIVATE_KEY")

curl -X POST https://lumina-api-production-ac85.up.railway.app/api/v1/agent/onboard \
  -H "Content-Type: application/json" \
  -d "{\"walletAddress\":\"${ADDRESS}\",\"signature\":\"${SIGNATURE}\",\"timestamp\":${TIMESTAMP},\"label\":\"my-bot\"}"

Caps and limits

Limit	Value
Active keys per wallet	3 (revoke before issuing the 4th)
Onboard requests per hour per IP	10
Timestamp window	±300 seconds of server time
Rate limit, free tier	10 requests / minute per API key
Rate limit, paid tier	100 requests / minute per API key

Free vs paid is determined server-side from the wallet’s tier — there is no separate API key class. Upgrade by contacting the team.

Storing the plaintext key

The lk_… prefix tells you it’s a Lumina key. The full string is shown once in the apiKey field of the onboard response. After that, only the metadata (keyId, label, createdAt, lastUsedAt) is retrievable via /api/v1/agent/keys. Best practices:

Secret manager. AWS Secrets Manager, GCP Secret Manager, Doppler, 1Password CLI — any of them are fine. Never commit the key to git, never put it in a .env file that’s shipped in a Docker image, never log it.
One key per logical bot. If you run a fleet, mint a separate key per process and label them (spot-arb-1, funding-rate-monitor, …). The audit trail then maps 1-to-1 to your infrastructure.
Rotate on suspicion. lumina.agent.revokeKey(keyId) is instant. Re-onboard for a fresh key — same wallet can hold the new and old key simultaneously up to the cap of 3.
Never put it in the URL. Always send via the x-api-key header. URLs end up in proxy logs, browser histories, and CDN access logs.

Listing and revoking your keys

const keys = await lumina.agent.listKeys()        // metadata only — never plaintext
await lumina.agent.revokeKey(keys[0].keyId)       // owner-only

Errors

HTTP	Code	Why
400	`invalid_body`	Malformed payload
400	`stale_timestamp`	Outside the ±300s window
401	`invalid_signature`	Recovered signer ≠ walletAddress
409	`cap_reached`	Wallet already has 3 active keys
429	`rate_limit`	10/h/IP exceeded

Getting started

Core concepts

For AI agents

MCP

SDK

Contracts

Reference

Onboarding (mint your API key)

The flow

SDK

curl

Caps and limits

Storing the plaintext key

Listing and revoking your keys

Errors

​The flow

​SDK

​curl

​Caps and limits

​Storing the plaintext key

​Listing and revoking your keys

​Errors

The flow

SDK

curl

Caps and limits

Storing the plaintext key

Listing and revoking your keys

Errors