Quick Start
Get your first signed price attestation in under 5 minutes.
All you need is curl and a way to pay — either a Lightning wallet (for L402) or USDC on Base (for x402). No API keys. No accounts. No signup.
Free Endpoints (No Payment Required)
Before you spend a single sat, you can hit these endpoints to verify the oracle is live and inspect the response format.
Health Check
curl https://api.myceliasignal.com/health
Oracle Info
curl https://api.myceliasignal.com/sho/info
Returns available pairs, pricing, and protocol details.
x402 Payment Terms
curl https://api.myceliasignal.com/.well-known/x402
Returns USDC payment address and pricing for x402 protocol.
DLC Oracle Public Key
curl https://api.myceliasignal.com/dlc/oracle/pubkey
Paid Endpoints
Each paid request follows the same pattern: request the price, receive a 402 Payment Required response with payment instructions, pay, then retry with proof of payment. Choose your protocol:
Request the price
Hit any oracle endpoint. You'll get a 402 Payment Required response with an x402 payment payload.
curl -i https://api.myceliasignal.com/oracle/btcusd
The 402 response includes a JSON body with the USDC amount, recipient address on Base, and the payment schema.
Pay with USDC on Base
Send the specified USDC amount ($0.001 for spot, $0.002 for VWAP) to the recipient address on Base L2. Your wallet or agent signs the transaction.
Retry with payment proof
Resend the same request with the X-Payment header containing the transaction receipt.
curl https://api.myceliasignal.com/oracle/btcusd \ -H "X-Payment: <base64-encoded-payment-proof>"
Receive signed attestation
The oracle returns a JSON response with the price, sources, timestamp, canonical payload, and an Ed25519 signature.
{
"pair": "BTC/USD",
"price": "84231.50",
"currency": "USD",
"timestamp": "2026-02-28T07:51:00Z",
"sources": "coinbase,kraken,bitstamp,gemini,bitfinex,binance,okx,gate,binanceus",
"source_count": 9,
"method": "median",
"decimals": 2,
"canonical": "v1|BTCUSD|84231.50|USD|2|2026-02-28T07:51:00Z|a1b2c3|coinbase,kraken,...|median",
"signature": "a3f8c2d9e1...b7d10442",
"pubkey": "0x4a2b7c...public_key"
}
A cryptographically signed attestation proving that at the stated timestamp, the median BTC/USD price across 9 named exchanges was $84,231.50. The Ed25519 signature over the canonical payload lets you independently verify this attestation was produced by Mycelia Signal and has not been tampered with.
Request the price
Hit any oracle endpoint. You'll get a 402 Payment Required response with a Lightning invoice and a macaroon.
curl -i https://api.myceliasignal.com/oracle/btcusd
The 402 response headers include WWW-Authenticate: L402 with the macaroon and Lightning invoice.
Pay the Lightning invoice
Pay the invoice using any Lightning wallet or node (10 sats for spot, 20 sats for VWAP). Save the preimage from the payment receipt — you'll need it.
Retry with L402 credentials
Resend the request with the Authorization header containing the macaroon and preimage.
curl https://api.myceliasignal.com/oracle/btcusd \ -H "Authorization: L402 <macaroon>:<preimage>"
Receive signed attestation
The oracle returns a JSON response with the price, sources, timestamp, canonical payload, and a secp256k1 ECDSA signature.
{
"pair": "BTC/USD",
"price": "84231.50",
"currency": "USD",
"timestamp": "2026-02-28T07:51:00Z",
"sources": "coinbase,kraken,bitstamp,gemini,bitfinex,binance,okx,gate,binanceus",
"source_count": 9,
"method": "median",
"decimals": 2,
"canonical": "v1|BTCUSD|84231.50|USD|2|2026-02-28T07:51:00Z|a1b2c3|coinbase,kraken,...|median",
"signature": "304402207c8e...022054ab...",
"pubkey": "02a1b2c3d4...compressed_key"
}
A cryptographically signed attestation with a secp256k1 ECDSA signature. The same canonical payload format as x402, but signed with the Lightning-specific key pair. You can verify it using any Bitcoin-compatible signature verification library.
Available Pairs
All pairs are available on both protocols at the same endpoint path.
| Endpoint | Pair | Sources | Price |
|---|---|---|---|
/oracle/btcusd | BTC/USD Spot | 9 | $0.001 / 10 sats |
/oracle/btcusd_vwap | BTC/USD VWAP | 7 | $0.002 / 20 sats |
/oracle/ethusd | ETH/USD | 5 | $0.001 / 10 sats |
/oracle/eurusd | EUR/USD | 8 | $0.001 / 10 sats |
/oracle/xauusd | XAU/USD | 8 | $0.001 / 10 sats |
/oracle/solusd | SOL/USD | 9 | $0.001 / 10 sats |
/oracle/btceur | BTC/EUR | 17 | $0.001 / 10 sats |
/oracle/etheur | ETH/EUR | 4 | $0.001 / 10 sats |
/oracle/soleur | SOL/EUR | 4 | $0.001 / 10 sats |
/oracle/xaueur | XAU/EUR | Combined | $0.001 / 10 sats |
/oracle/btceur_vwap | BTC/EUR VWAP | Combined | $0.002 / 20 sats |
What's in the Response
Every paid response contains these fields. The canonical string is what the signature covers — this is what you verify.
| Field | Type | Description |
|---|---|---|
pair | string | Trading pair (e.g., "BTC/USD") |
price | string | Aggregated price as a decimal string |
currency | string | Quote currency (USD or EUR) |
timestamp | string | ISO 8601 UTC timestamp of computation |
sources | string | Comma-separated list of contributing sources |
source_count | integer | Number of sources in this attestation |
method | string | Aggregation method (median or vwap) |
decimals | integer | Decimal precision of the price |
canonical | string | Pipe-delimited canonical string that was signed |
signature | string | Hex-encoded cryptographic signature |
pubkey | string | Public key for signature verification |
Always verify the signature before trusting the price data. The canonical string is the source of truth — reconstruct it from the response fields and verify the signature against the public key. See the Signature Verification guide for code examples.
Next Steps
Now that you've received your first attestation:
Verify the signature → Learn how to cryptographically verify attestations in Python, JavaScript, and Rust.
x402 deep dive → Full integration guide for USDC on Base, including programmatic payment flows for AI agents.
L402 deep dive → Lightning integration with macaroon handling, invoice payment, and preimage extraction.