Response Schema

Complete JSON response format for each protocol and endpoint type.

Critical: No top-level price field

Oracle responses do not have a top-level price field. The price is embedded in the canonical string at position 3. Extract it with canonical.split("|")[3].

L402 Response (secp256k1)

Returned by the L402 proxy. This is the raw backend response passed through unchanged.

json

{
  "domain": "BTCUSD",
  "canonical": "v1|PRICE|BTCUSD|84231.50|USD|2|binance,binance_us,bitfinex,bitstamp,coinbase,gateio,gemini,kraken,okx|median|1741514400|482910",
  "signature": "<base64-DER-encoded-secp256k1-ECDSA>",
  "pubkey": "<33-byte-compressed-hex-secp256k1>",
  "signing_scheme": "secp256k1_ecdsa"
}

Field	Type	Description
`domain`	string	Pair identifier without slash (e.g., "BTCUSD")
`canonical`	string	Pipe-delimited canonical string that was signed. See format spec →
`signature`	string	Base64-encoded DER signature over SHA-256(canonical)
`pubkey`	string	Compressed secp256k1 public key, hex-encoded (33 bytes)

x402 Response (Ed25519)

Returned by the x402 proxy after successful USDC payment. The canonical string is from the backend, but the signature is re-signed with Ed25519.

json

{
  "domain": "BTCUSD",
  "canonical": "v1|PRICE|BTCUSD|84231.50|USD|2|binance,binance_us,bitfinex,bitstamp,coinbase,gateio,gemini,kraken,okx|median|1741514400|482910",
  "signature": "<base64-raw-ed25519-64-bytes>",
  "signing_scheme": "ed25519",
  "pubkey": "<32-byte-hex-ed25519>"
}

Field	Type	Description
`domain`	string	Pair identifier without slash
`canonical`	string	Pipe-delimited canonical string (same format as L402)
`signature`	string	Base64-encoded raw Ed25519 signature (64 bytes) over SHA-256(canonical)
`signing_scheme`	string	Always `"ed25519"`. L402 responses use `"secp256k1_ecdsa"`.
`pubkey`	string	Ed25519 public key, hex-encoded (32 bytes)

Protocol detection

Check the signing_scheme field: "ed25519" = x402 (USDC on Base), "secp256k1_ecdsa" = L402 (Lightning). Both are present in all paid responses.

ECON Response

Economic indicator and commodity endpoints return a different JSON structure. The canonical field contains the canonical payload.

json — econ example (US CPI)

{
  "region": "us",
  "indicator": "cpi",
  "period": "2026-02",
  "value": "326.785",
  "unit": "index198284100",
  "vintagedate": "2026-03-14",
  "sourcemodel": "directapi",
  "sourceagency": "BLS",
  "seriesid": "CUUR0000SA0",
  "canonical": "v1|ECON|US|CPI|326.785|index198284100|2026-02|2026-03-14|BLS|CUUR0000SA0|directapi|1741514400|830114",
  "signature": "<base64-signature>",
  "signing_scheme": "secp256k1_ecdsa",
  "pubkey": "<33-byte-compressed-hex>",
  "createdat": "2026-03-15"
}

Unified canonical key

All endpoints now return the canonical string under the canonical key. This applies to price, econ, commodities, and index endpoints alike.

402 Payment Required (x402)

json

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "1000",
    "resource": "https://api.myceliasignal.com/oracle/price/btc/usd",
    "description": "BTC/USD spot price — signed attestation",
    "payTo": "0x...",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "maxTimeoutSeconds": 60
  }],
  "error": "X-PAYMENT header is required"
}

402 Payment Required (L402)

The L402 402 response uses the WWW-Authenticate HTTP header rather than a JSON body:

http header

WWW-Authenticate: L402 macaroon="AgELbXljZWxpYS...", invoice="lnbc100n1pj..."

Extracting Data

python

# Extract price (position 3)
price = response["canonical"].split("|")[3]

# Extract sources (position 6, comma-separated)
sources = response["canonical"].split("|")[6].split(",")

# Extract timestamp (position 8)
timestamp = response["canonical"].split("|")[8]

← Endpoints & Pairs Canonical Format →

Layer 2 — Oracle Information Responses

Layer 2 responses follow the same signed envelope pattern but wrap a multi-signal snapshot rather than a single measurement.

Perp Regime Response

Returned by /oracle/perp/btc, /oracle/perp/eth, /oracle/perp/sol.

json

{
  "currency": "BTC",
  "layer": "Oracle Information",
  "regime": {
    "perp_regime": "BEARISH_MOMENTUM",
    "bias": "SHORT",
    "confidence": 0.7,
    "risk": "MODERATE",
    "signal_notes": "funding_negative, oi_declining, liq_short_dominant"
  },
  "signals": {
    "funding_pct": -0.00180,
    "oi_delta_1h": -0.024,
    "basis_regime": "CONTANGO",
    "liq_dominant": "SHORT",
    "msxi_value": -18.4,
    "msvi_value": 54.2
  },
  "canonical": "v1|PERP_REGIME|BTC|regime|BEARISH_MOMENTUM|bias|SHORT|...|1781100000|482910",
  "signature": "base64_ed25519...",
  "pubkey": "hex_pubkey",
  "signed": true,
  "fetched_at": 1781100000
}

Market Synopsis Response

Returned by /oracle/synopsis/market.

json

{
  "layer": "Oracle Information",
  "snapshot": {
    "mssi": {"value": 45.8, "regime": "ELEVATED"},
    "msti": {"value": 28.1, "regime": "COUPLED"},
    "msxi_btc": {"value": -18.4, "regime": "BEARISH"},
    "msvi_btc": {"value": 54.2, "regime": "ELEVATED"},
    "funding_btc": -0.00180,
    "oi_delta_1h": -0.024,
    "liq_1h_dominant": "SHORT",
    "btc_price": 62300.00,
    "eth_price": 2418.50,
    "high_impact_events_today": 2
  },
  "canonical": "v1|SYNOPSIS|MARKET|mssi|45.8|ELEVATED|...|1781100000|482910",
  "signature": "base64_ed25519...",
  "signed": true,
  "fetched_at": 1781100000
}

Layer 3 — Oracle Intelligence Responses

Layer 3 responses always include a disclaimer field. The disclaimer must not be stripped from any downstream display.

Macro Risk Response

Returned by /oracle/intel/macro/risk.

json

{
  "service": "macro_risk",
  "layer": "Oracle Intelligence",
  "risk_score": 60,
  "risk_regime": "HIGH",
  "factors": {
    "crypto_stress": {"mssi": 57.3, "regime": "HIGH", "weight": 0.4},
    "contagion": {"msti": 38.1, "regime": "COUPLED", "weight": 0.3},
    "macro_calendar": {"high_impact_today": 3, "weight": 0.3}
  },
  "disclaimer": "This is a market regime classification derived from quantitative signals, not financial advice...",
  "canonical": "v1|MACRO_RISK|MARKET|score|60|regime|HIGH|...|1781100000|482910",
  "signature": "base64_ed25519...",
  "signed": true,
  "fetched_at": 1781100000
}

Perp Setup Response

Returned by /oracle/intel/perp/setup.

json

{
  "service": "perp_setup",
  "layer": "Oracle Intelligence",
  "highest_confidence_setup": {
    "currency": "BTC",
    "signal_alignment": "SHORT",
    "regime": "BEARISH_MOMENTUM",
    "confidence": 0.7,
    "risk": "MODERATE",
    "edge": "funding_negative, oi_declining",
    "invalidation_conditions": "funding turns positive or liq flow flips"
  },
  "setups_found": 2,
  "market_bias": "CAUTIOUS",
  "mssi_regime": "ELEVATED",
  "disclaimer": "This is a signal alignment classification derived from quantitative regime data, not financial advice...",
  "signed": true,
  "fetched_at": 1781100000
}

DeFi Opportunity Response

Returned by /oracle/intel/defi/opportunity.

json

{
  "service": "defi_opportunity",
  "layer": "Oracle Intelligence",
  "highest_opportunity": {
    "protocol": "moonwell_base",
    "asset": "USDC",
    "chain": "base",
    "raw_apr": 4.00,
    "stress_penalty": 1.00,
    "risk_adjusted_apr": 3.00,
    "rationale": "stress penalty -1.0%"
  },
  "market_context": {
    "mssi_regime": "ELEVATED",
    "stress_penalty_applied": 1.0,
    "contagion_penalty_applied": 0.0
  },
  "disclaimer": "This is a risk-adjusted yield classification derived from quantitative signals, not financial advice...",
  "signed": true,
  "fetched_at": 1781100000
}