Quick Start

Get your first signed price attestation in under 5 minutes.

Prerequisites

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.

Preview Data (any endpoint)

Append /preview to any paid endpoint to get real but unsigned data, up to 5 minutes stale — no payment required.

bash

curl https://api.myceliasignal.com/oracle/price/btc/usd/preview
curl https://api.myceliasignal.com/oracle/econ/us/cpi/preview

Health Check

bash

curl https://api.myceliasignal.com/health

Oracle Info

bash

curl https://api.myceliasignal.com/

Returns available pairs, pricing, and protocol details.

x402 Payment Terms

bash

curl https://api.myceliasignal.com/.well-known/x402

Returns USDC payment address and pricing for x402 protocol.

DLC Oracle Public Key

bash

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.

bash

curl -i https://api.myceliasignal.com/oracle/price/btc/usd

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.01 for spot, $0.02 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.

bash

curl https://api.myceliasignal.com/oracle/price/btc/usd \
  -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.

json — example response

{
  "domain": "BTCUSD",
  "canonical": "v1|PRICE|BTCUSD|84231.50|USD|2|coinbase,kraken,bitstamp,gemini,bitfinex,binance,okx,gateio,binanceus|median|1741514400|482910",
  "signature": "a3f8c2d9e1...b7d10442",
  "pubkey": "7ab07fbe7d08cd16823e5eb0db0e21f3f38e9366d5fd00d14e95df0fb9b51a1a",
  "signing_scheme": "ed25519"
}

What you just received

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.

bash

curl -i https://api.myceliasignal.com/oracle/price/btc/usd

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.

bash

curl https://api.myceliasignal.com/oracle/price/btc/usd \
  -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.

json — example response

{
  "domain": "BTCUSD",
  "canonical": "v1|PRICE|BTCUSD|84231.50|USD|2|coinbase,kraken,bitstamp,gemini,bitfinex,binance,okx,gateio,binanceus|median|1741514400|482910",
  "signature": "MEUCIQDKkZXzh7QesbDqw70BMBA5xpMbYtoDV3yd1GC7K/tKLQIgKnu/6XMmx9xw7QFC28cJ2IYvBZ8fQmP4MQelaJcZg94=",
  "pubkey": "02b1377c30c7dcfcba428cf299c18782856a12eb4fab32b87081460f4ba2deab73",
  "signing_scheme": "secp256k1_ecdsa"
}

What you just received

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 Endpoints

63 endpoints across crypto, stablecoin pegs, FX, economic indicators, and commodities. All available on both L402 and x402. Append /preview to any endpoint for free unsigned sample data.

Example Endpoints	Category	x402	L402
`/oracle/price/btc/usd`	Crypto spot	$0.01	10 sats
`/oracle/price/btc/usd/vwap`	Crypto VWAP	$0.02	20 sats
`/oracle/price/eth/usd`	Crypto spot	$0.01	10 sats
`/oracle/price/xau/usd`	Precious metals	$0.01	10 sats
`/oracle/price/eur/usd`	FX	$0.01	10 sats
`/oracle/price/usd/jpy`	FX	$0.01	10 sats
`/oracle/econ/us/cpi`	Economic indicator	$0.10	1000 sats
`/oracle/econ/us/fedfunds`	Economic indicator	$0.10	1000 sats
`/oracle/econ/commodities/wti`	Commodities	$0.10	1000 sats

See Endpoints & Pairs for the full list of all 63 endpoints.

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

Important

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.

← Overview Signature Verification →