API Documentation
Complete reference for all 12 BlindOracle endpoints. Every paid endpoint uses x402 micropayments on Base L2. All requests pass through CaMel 4-layer security validation.
https://craigmbrown.com/api/v1
Authentication
Two authentication methods. Both can be used simultaneously for higher rate limits.
x402 Micropayment (Primary)
Include a payment proof in the X-402-Payment header. The server returns HTTP 402 with payment requirements if no proof is provided. Pay per call in USDC on Base L2.
API Key (Bulk)
Pre-paid API key in X-BlindOracle-Key header. Purchased via the x402 endpoint. Provides higher rate limits and prepaid balance deductions.
x402 Payment Flow
How pay-per-call micropayments work with every BlindOracle endpoint.
1. Call endpoint (no auth)
→
2. Receive HTTP 402 + payment requirements
→
3. Sign USDC payment on Base L2
→
4. Retry with X-402-Payment header
→
5. Receive response (HTTP 200)
# Step 1: Initial request returns 402
curl -s https://craigmbrown.com/api/v1/markets
# Response: {"status": 402, "payment_required": {...}}
# Step 2: Retry with payment proof
curl -X POST https://craigmbrown.com/api/v1/markets \
-H "X-402-Payment: eyJhbGciOiJFUzI1NiIsInR5cCI6Ing0MDIifQ..." \
-H "Content-Type: application/json" \
-d '{"question": "ETH > $5k?", "deadline": "2026-03-01T00:00:00Z", "initial_liquidity_sats": 10000}'
Prediction Markets
Create, predict on, and settle privacy-preserving prediction markets.
POST
/v1/markets
Create a new prediction market
$0.001
Create a privacy-preserving prediction market with a question, deadline, and initial liquidity pool funded in sats.
Request Body
{
"question": "Will ETH exceed $5000 by March 2026?",
"deadline": "2026-03-01T00:00:00Z",
"initial_liquidity_sats": 10000,
"resolution_source": "manual"
}
Response (200)
{
"market_id": 42,
"question": "Will ETH exceed $5000...",
"deadline": "2026-03-01T00:00:00Z",
"commitment_address": "bc1q...",
"status": "active",
"tx_hash": "0xabc..."
}
Try It
curl -X POST https://craigmbrown.com/api/v1/markets \
-H "Content-Type: application/json" \
-H "X-402-Payment: <payment_proof>" \
-d '{"question":"Will ETH exceed $5000 by March 2026?","deadline":"2026-03-01T00:00:00Z","initial_liquidity_sats":10000}'
POST
/v1/predictions
Place anonymous prediction
$0.0005 + 0.1%
Place a privacy-preserving prediction using commitment scheme sha256(secret || position || amount). Zero identity linkage.
Request Body
{
"market_id": 42,
"position": "YES",
"amount_sats": 5000,
"ecash_tokens": ["eCash_token_1..."]
}
Response (200)
{
"prediction_id": "pred_a1b2c3...",
"commitment": "sha256_hash...",
"market_id": 42,
"amount_sats": 5000,
"status": "confirmed",
"tx_hash": "0xdef..."
}
Try It
curl -X POST https://craigmbrown.com/api/v1/predictions \
-H "Content-Type: application/json" \
-H "X-402-Payment: <payment_proof>" \
-d '{"market_id":42,"position":"YES","amount_sats":5000}'
POST
/v1/markets/settle
Settle a prediction market
$0.002
Settle a market with final outcome. Winners receive eCash tokens for their payout.
Request Body
{
"market_id": 42,
"outcome": "YES",
"evidence_url": "https://..."
}
Response (200)
{
"market_id": 42,
"outcome": "YES",
"total_payout_sats": 15000,
"winners_count": 3,
"settlement_tx_hash": "0x...",
"status": "settled"
}
Try It
curl -X POST https://craigmbrown.com/api/v1/markets/settle \
-H "Content-Type: application/json" \
-H "X-402-Payment: <payment_proof>" \
-d '{"market_id":42,"outcome":"YES","evidence_url":"https://coinmarketcap.com/..."}'
Identity
NIP-58 badge credentials and agent reputation scoring.
GET
/v1/identity/verify
Verify agent identity
$0.0002
Verify NIP-58 badge credentials and compute a 0.0-1.0 reputation score.
Query Parameters
?agent_pubkey=abcdef0123456789...
&credential_id=550e8400-e29b-41d4-a716-446655440000
Response (200)
{
"agent_pubkey": "abcdef...",
"reputation_score": 0.85,
"active_credentials": 4,
"proof_types": ["presence", "participation"],
"verification_result": {...}
}
Try It
curl "https://craigmbrown.com/api/v1/identity/verify?agent_pubkey=abcdef0123456789..." \
-H "X-402-Payment: <payment_proof>"
POST
/v1/identity/mint
Mint identity badge
$0.001
Mint a NIP-58 badge credential with anti-synthetic validation via CaMel Layer 2.
Request Body
{
"agent_pubkey": "abcdef...",
"proof_type": "participation",
"metadata": {"event": "hackathon"},
"witnesses": ["npub1..."],
"witness_signatures": ["sig..."]
}
Response (200)
{
"credential_id": "uuid...",
"proof_type": "participation",
"nip58_kind": 30009,
"nostr_event_id": "event_...",
"status": "minted",
"issued_at": "2026-02-15T...",
"expires_at": null
}
Try It
curl -X POST https://craigmbrown.com/api/v1/identity/mint \
-H "Content-Type: application/json" \
-H "X-402-Payment: <payment_proof>" \
-d '{"agent_pubkey":"abcdef...","proof_type":"participation","metadata":{"event":"hackathon"}}'
Payments
Multi-rail balance management, invoicing, and withdrawals.
GET
/v1/payments/balance
Check balance
Free
Return current balances across all payment rails.
Query Parameters
?rail=all # Options: all, BTC, ETH, eCash, USDC, Lightning
Response (200)
{
"balances": {
"BTC": 50000,
"ETH": 0,
"eCash": 125000,
"USDC": 0,
"Lightning": 30000
},
"timestamp": "2026-02-15T12:00:00Z"
}
Try It
curl "https://craigmbrown.com/api/v1/payments/balance?rail=all"
POST
/v1/payments/invoice
Create Lightning invoice
$0.0001
Generate a BOLT11 Lightning invoice for receiving payments.
Request Body
{
"amount_sats": 10000,
"description": "Market deposit",
"expiry_seconds": 3600
}
Response (200)
{
"bolt11": "lnbc100u1p...",
"payment_hash": "abc123...",
"amount_sats": 10000,
"expires_at": "2026-02-15T13:00:00Z"
}
Try It
curl -X POST https://craigmbrown.com/api/v1/payments/invoice \
-H "Content-Type: application/json" \
-H "X-402-Payment: <payment_proof>" \
-d '{"amount_sats":10000,"description":"Market deposit"}'
POST
/v1/payments/withdraw/lightning
Withdraw to Lightning
$0.0005 + 0.1%
Withdraw eCash balance to a Lightning Network invoice.
Request Body
{
"amount_sats": 5000,
"bolt11_invoice": "lnbc50u1p..."
}
Response (200)
{
"success": true,
"amount": 5000,
"fee_amount": 5,
"rail": "lightning",
"tx_hash": "0x...",
"error": null
}
Try It
curl -X POST https://craigmbrown.com/api/v1/payments/withdraw/lightning \
-H "Content-Type: application/json" \
-H "X-402-Payment: <payment_proof>" \
-d '{"amount_sats":5000,"bolt11_invoice":"lnbc50u1p..."}'
POST
/v1/payments/withdraw/ethereum
Withdraw to Ethereum/Base
$0.001 + 0.05%
Withdraw eCash balance to an Ethereum/Base L2 address as USDC.
Request Body
{
"amount_sats": 10000,
"eth_address": "0x742d35Cc6634C0532925a..."
}
Response (200)
{
"success": true,
"amount": 10000,
"fee_amount": 5,
"rail": "ethereum",
"tx_hash": "0xabc...",
"error": null
}
Try It
curl -X POST https://craigmbrown.com/api/v1/payments/withdraw/ethereum \
-H "Content-Type: application/json" \
-H "X-402-Payment: <payment_proof>" \
-d '{"amount_sats":10000,"eth_address":"0x742d35Cc6634C0532925a..."}'
Swaps
Cross-chain atomic swaps via Boltz and Fedimint federation bridges.
GET
/v1/swaps/quote
Get swap quote
Free
Get fee estimate and route plan without executing a swap.
Query Parameters
?pair=btc_eth&amount=50000
# Pairs: btc_eth, btc_usdc, ecash_usdc,
# ecash_btc, lightning_base, eth_usdc
Response (200)
{
"quote_id": "q_abc123...",
"pair": "btc_eth",
"input_amount": 50000,
"estimated_output": 49500,
"fee_percent": 0.1,
"fee_amount": 50,
"route_steps": ["BTC->HTLC", "HTLC->ETH"],
"estimated_time_seconds": 600,
"provider": "boltz",
"expires_at": 1708012800
}
Try It
curl "https://craigmbrown.com/api/v1/swaps/quote?pair=btc_eth&amount=50000"
POST
/v1/swaps/btc-eth
Swap BTC to ETH
$0.001 + 0.1%
Submarine swap BTC to ETH via Boltz Exchange using HTLC for trustless atomic execution.
Request Body
{
"amount_sats": 50000,
"destination_address": "0x742d35Cc..."
}
Response (200)
{
"swap_id": "swap_abc...",
"input_amount": 50000,
"output_amount": 49500,
"fee_amount": 50,
"tx_hash": "0x...",
"provider": "boltz",
"status": "executing"
}
Try It
curl -X POST https://craigmbrown.com/api/v1/swaps/btc-eth \
-H "Content-Type: application/json" \
-H "X-402-Payment: <payment_proof>" \
-d '{"amount_sats":50000,"destination_address":"0x742d35Cc..."}'
POST
/v1/swaps/ecash-usdc
Swap eCash to USDC
$0.0005 + 0.05%
Bridge eCash tokens to USDC on Base L2 via Fedimint federation. Fast ~30 second settlement.
Request Body
{
"amount_sats": 10000,
"base_address": "0x742d35Cc..."
}
Response (200)
{
"swap_id": "swap_def...",
"input_amount_sats": 10000,
"output_amount_usdc": 9950,
"fee_sats": 5,
"tx_hash": "0x...",
"provider": "federation",
"status": "completed"
}
Try It
curl -X POST https://craigmbrown.com/api/v1/swaps/ecash-usdc \
-H "Content-Type: application/json" \
-H "X-402-Payment: <payment_proof>" \
-d '{"amount_sats":10000,"base_address":"0x742d35Cc..."}'
Rate Limits
Per-IP rate limits. API key holders receive 3x multiplier.
| Endpoint | Rate (req/min) | Burst | SLA Uptime | P95 Latency |
|---|---|---|---|---|
| /v1/markets | 10 | 3 | 99.5% | 2,000ms |
| /v1/predictions | 30 | 10 | 99.9% | 1,500ms |
| /v1/markets/settle | 5 | 2 | 99.9% | 5,000ms |
| /v1/identity/verify | 60 | 20 | 99.9% | 500ms |
| /v1/identity/mint | 10 | 3 | 99.9% | 3,000ms |
| /v1/payments/balance | 120 | 30 | 99.9% | 200ms |
| /v1/payments/invoice | 30 | 10 | 99.9% | 1,000ms |
| /v1/payments/withdraw/* | 10 | 3 | 99.5% | 5,000ms |
| /v1/swaps/quote | 120 | 30 | 99.9% | 500ms |
| /v1/swaps/btc-eth | 5 | 2 | 99.5% | 15,000ms |
| /v1/swaps/ecash-usdc | 20 | 5 | 99.9% | 3,000ms |
| /v1/health | Unlimited | -- | 99.99% | 10ms |