# Mycelia Signal
 
## Product Taxonomy

Mycelia Signal endpoints are organized into three layers:

**Oracle Data** — raw signed measurements
  Prices, FX, metals, stablecoins, VWAP ($0.01-$0.02)
  Indices: MSVI volatility, MSXI sentiment, MSSI stress, MSTI contagion ($0.05)
  Derivatives: funding, OI, basis, orderbook, IV, greeks, term structure ($0.01-$0.05)
  Liquidation flow, gas, DeFi yield/metrics, GPU compute, LLM inference ($0.01-$0.05)
  Economic calendar, surprises, expiry, COT, marine, weather ($0.05-$1.00)
  Signed historical data: spot OHLCV, funding, index history ($0.05-$0.10)

**Oracle Regimes** — interpreted signals (machine-actionable classifications)
  /oracle/synopsis/market — 15-signal market state snapshot ($0.25)
  /oracle/perp/btc — BTC perp trading regime with bias, confidence, risk ($0.15)
  /oracle/regime/equity — TradFi regime: RISK_ON/NEUTRAL/STRESS/PANIC ($0.10)
  /oracle/regime/liquidity — Liquidity regime: DEEP/NORMAL/THIN/FRAGILE ($0.10)

**Oracle History** — cryptographically signed archival data
  /oracle/history/* — spot, funding, index history with per-row original signatures ($0.05-$0.10)


> Mycelia Signal is a sovereign cryptographic oracle and crypto price feed API serving real-time Bitcoin, Ethereum, FX rates, stablecoin pegs, precious metals, US/EU macro indicators, commodities, MSVI volatility index, MSXI sentiment index, MSSI stress index, MSTI crypto-TradFi contagion index, MESI equity stress index, MNVI NQ volatility index, TradFi Regime (RISK_ON/NEUTRAL/STRESS/PANIC), Liquidity Regime (DEEP/NORMAL/THIN/FRAGILE), Cross-Asset Divergence, Regime Consensus, Marine Oracle (sea state, vessel tracking, voyage forecast), CME BTC COT institutional positioning, and parametric weather/climate oracle data across 182 paid endpoints, LLM inference pricing, economic calendar, DeFi protocol metrics, liquidation flow, futures term structure, and signed historical data. Every query returns a canonical signed payload — pair, value, sources, aggregation method, timestamp, and nonce — independently verifiable against a known public key. Pay-per-query via Lightning (L402) or USDC on Base (x402). No API keys. No subscriptions. No vendor trust required.
 
Mycelia Signal is designed for AI agents, DeFi protocols, and institutions that require verifiable, tamper-proof financial data. Unlike traditional oracle networks, every attestation embeds a full audit trail — not just a value, but cryptographic proof of how it was derived. The canonical attestation format (Oracle Attestation Spec v0.4) is open and independently verifiable by any party at any time.
 
## Thesis

- [Attested State Infrastructure](https://myceliasignal.com/thesis/): The economics of machine-verifiable state — why shared, cryptographically signed infrastructure emerges naturally as machine-to-machine coordination scales. Covers duplication economics under AI-assisted development, the LIBOR precedent, verification externalities, and why maintenance costs dominate build costs at scale.

## Core Concepts
 
- [Price Feed API & DLC Oracle](https://myceliasignal.com/price-feeds/): Crypto price feed API, FX rates API, and Bitcoin DLC oracle — full product overview with endpoint reference and pricing
- [How It Works](https://myceliasignal.com/docs/): Overview of the sovereign oracle model, attestation design, and payment protocols
- [Canonical Attestation Format](https://myceliasignal.com/docs/canonical-format/): The signed payload structure — fields, encoding, and verification logic. Format: `v1|PRICE|PAIR|PRICE|CURRENCY|DECIMALS|SOURCES|METHOD|TIMESTAMP|NONCE`
- [Test Vectors](https://myceliasignal.com/docs/test-vectors/): SHA-256 digests and field positions for every canonical type — PRICE, ECON, VOLATILITY, SENTIMENT, STRESS, GAS, WEATHER, MARINE
- [Methodology](https://api.myceliasignal.com/methodology.json): Machine-readable index methodology — components, weights, sources, normalization, confidence, canonical formats for MSVI, MSXI, MSSI
- [Verification Guide](https://myceliasignal.com/docs/verification/): How to verify a signed attestation against the Mycelia Signal public key
- [Public Keys](https://myceliasignal.com/docs/keys/): Current and historical signing keys for independent verification. L402: secp256k1 ECDSA. x402: Ed25519. Per-instance keypairs per GC node.
 
## Payment Protocols
 
- [L402 / Lightning](https://myceliasignal.com/docs/l402/): Pay-per-query via Bitcoin Lightning Network using the L402 protocol (macaroon + preimage). 10 sats (spot/FX/metals), 20 sats (VWAP), 133 sats (marine seastate), 267 sats (marine route), 500 sats (MSVI/MSXI/MSSI), 667 sats (marine vessel/voyage), 1000 sats (econ/commodities), 10000 sats (DLC threshold/enum/numeric).
- [x402 / USDC on Base](https://myceliasignal.com/docs/x402/): Pay-per-query via USDC on Base using the x402 HTTP payment protocol. $0.01 (spot/FX/metals), $0.02 (VWAP/inference), $0.05 (indices/derivatives/defi/liq-flow/calendar/history spot+funding), $0.10 (weather/marine/history index/surprises), $1.00 (econ indicators/COT), $7.00 (DLC).

## How to Make a Paid Request (x402)

When you call a paid endpoint without payment, you receive HTTP 402 with payment requirements in the response body (`accepts[0].maxAmountRequired` in USDC base units). Here is how to pay:

### Node.js (recommended for agents)
```javascript
import { payForResource } from "@x402/client";
import { createWalletClient, http } from "viem";
import { base } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount("0xYOUR_PRIVATE_KEY");
const wallet = createWalletClient({ account, chain: base, transport: http() });

// Step 1: Call endpoint, get 402 + payment requirements
const res = await fetch("https://api.myceliasignal.com/oracle/price/btc/usd");
if (res.status === 402) {
  const requirements = await res.json(); // { x402Version, accepts: [...] }
  // Step 2: Sign and submit payment
  const payment = await payForResource(wallet, requirements);
  // Step 3: Retry with payment header
  const paid = await fetch("https://api.myceliasignal.com/oracle/price/btc/usd", {
    headers: { "X-PAYMENT": payment }
  });
  const data = await paid.json(); // { canonical, signature, pubkey, ... }
}
```

### Python
```python
import requests, json

# Step 1: Hit endpoint, get 402
r = requests.get("https://api.myceliasignal.com/oracle/price/btc/usd")
if r.status_code == 402:
    reqs = r.json()  # { x402Version: 1, accepts: [{ maxAmountRequired, ... }] }
    # Step 2: Sign EIP-3009 transferWithAuthorization using web3.py
    # Step 3: Retry with X-PAYMENT header containing signed payment
    # See full guide: https://myceliasignal.com/docs/x402/
```

### Key details
- Network: Base (chain ID 8453)
- Asset: USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)
- Prices: $0.01 (spot), $0.02 (VWAP), $0.05 (indices/derivatives), $1.00 (macro), $7.00 (DLC)
- No API keys needed. Payment IS the authentication.
- Free preview: append `/preview` to any endpoint for unsigned sample data
- Full quickstart guide: https://myceliasignal.com/docs/quickstart/
- npm: `npm install @x402/client viem`
 
## API Reference
 
- [Quickstart](https://myceliasignal.com/docs/quickstart/): Get your first signed attestation in minutes
- [Endpoints](https://myceliasignal.com/docs/endpoints/): Full API endpoint reference for all 182 supported endpoints
- [Response Schema](https://myceliasignal.com/docs/response-schema/): Complete response field definitions and types
- [Error Codes](https://myceliasignal.com/docs/error-codes/): Error handling reference
- [OpenAPI Spec](https://api.myceliasignal.com/openapi.json): Machine-readable API specification (OpenAPI 3.1.0 v3.3.1, 258 paths) covering all endpoints, request/response schemas, canonical attestation format, and payment protocol details
 
## Supported Endpoints (182 paid total)
 
**Crypto spot** (10 sats / $0.01): BTC/USD, BTC/EUR, BTC/JPY, ETH/USD, ETH/EUR, ETH/JPY, SOL/USD, SOL/EUR, SOL/JPY, XRP/USD, ADA/USD, DOGE/USD
 
**Stablecoin pegs** (10 sats / $0.01): USDT/USD, USDC/USD, USDT/EUR, USDT/JPY
 
**Crypto VWAP — 5-minute** (20 sats / $0.02): BTC/USD VWAP, BTC/EUR VWAP, ETH/USD VWAP
 
**Precious metals** (10 sats / $0.01): XAU/USD, XAU/EUR, XAU/JPY
 
**FX pairs** (10 sats / $0.01): EUR/USD, EUR/JPY, EUR/GBP, EUR/CHF, EUR/CNY, EUR/CAD, GBP/USD, GBP/JPY, GBP/CHF, GBP/CNY, GBP/CAD, USD/JPY, USD/CHF, USD/CNY, USD/CAD, CHF/JPY, CHF/CAD, CNY/JPY, CNY/CAD, CAD/JPY
 
**US economic indicators** (1000 sats / $1.00): CPI, CPI Core, Unemployment, NFP, Fed Funds Rate, GDP, PCE, Yield Curve (10Y-2Y)
 
**EU economic indicators** (1000 sats / $1.00): HICP, HICP Core, HICP Services, Unemployment, GDP, Employment
 
**Commodities** (1000 sats / $1.00): WTI Crude, Brent Crude, Henry Hub NatGas, Copper, DXY
 
**CME BTC COT — Institutional Positioning** (1000 sats / $1.00): CFTC leveraged fund, asset manager, and dealer net positions for BTC CME futures
 
**Parametric weather** (100 sats / $0.10): WRSI, rainfall, temperature, wind — global ERA5 coverage, parametric insurance triggers

**Volatility, Sentiment, Stress, Contagion indices** (500 sats / $0.05): MSVI BTC/USD, MSVI ETH/USD, MSXI BTC/USD, MSXI ETH/USD, MSSI Market, MSTI Market
 
Most paid endpoints have a free `/preview` path returning unsigned, cached data for format discovery and integration testing. Preview data is intentionally stale — do NOT use for trading or time-sensitive decisions. Staleness by layer:
- Layer 1 (prices, gas, compute, DeFi, weather, marine): up to 60 minutes stale (`cache_max_age_minutes: 60` in response)
- Layer 1 MSFR (funding/OI/basis): up to 2 hours stale
- Layer 2 indices (MSVI/MSXI/MSSI/MSTI): up to 60 minutes stale
- Layer 2 MESI/MNVI: up to 24 hours stale
- Layer 2/3 intel/regime/synopsis/perp: up to 24 hours stale (`preview_cached: true` in response)
- Regime Persistence: 24 hours stale (computed from historical data as-of 24h ago)
All previews include `preview: true` and `signed: false` fields. Full paid endpoints return real-time Ed25519-signed data.
 
## MSVI — Mycelia Signal Volatility Index (500 sats / $0.05)
 
- `GET /oracle/volatility/btc/usd` — BTC/USD MSVI signed index (0-100 scale)
- `GET /oracle/volatility/eth/usd` — ETH/USD MSVI signed index (0-100 scale)
- `GET /oracle/volatility/btc/usd/preview` — free unsigned preview
- `GET /oracle/volatility/eth/usd/preview` — free unsigned preview
- `GET /oracle/volatility/btc/usd/methodology` — free signed methodology document
- `GET /oracle/volatility/eth/usd/methodology` — free signed methodology document
 
MSVI components: Realized Volatility (Parkinson 30D, 30%), Implied Volatility (Deribit ATM options, 25%), Term Structure (7D/90D IV ratio, 15%), Funding Rate signal (6-exchange capped weighted median: Binance, Bybit, OKX, Bitget, Gate, Hyperliquid, 20%), Put/Call Ratio (Deribit OI, 10%). Output: 0-100 index, Ed25519 signed, methodology versioned and signed.

Canonical format: `v1|VOLATILITY|BTCUSD|MSVI|{value}|{unit}|30D|RV:{rv}:{w},IV:{iv}:{w},TS:{ts}:{w},FR:{fr}:{w},PCR:{pcr}:{w}|CONFIDENCE:{c}|METHOD:v1|{timestamp}|{nonce}`
 
## MSXI — Mycelia Signal Sentiment Index (500 sats / $0.05)
 
- `GET /oracle/sentiment/btc/usd` — BTC/USD MSXI signed index (-100 to +100 scale)
- `GET /oracle/sentiment/eth/usd` — ETH/USD MSXI signed index (-100 to +100 scale)
- `GET /oracle/sentiment/btc/usd/preview` — free unsigned preview
- `GET /oracle/sentiment/eth/usd/preview` — free unsigned preview
 
MSXI measures directional market positioning. Positive values indicate bullish sentiment (longs dominant), negative values indicate bearish sentiment (puts bid, shorts paying). Five components: Funding Rate direction (6-exchange capped weighted median: Binance, Bybit, OKX, Bitget, Gate, Hyperliquid, 30%), Options Skew — 25-delta risk reversal (Deribit, 25%), Put/Call Ratio (Deribit OI, 20%), Term Structure slope (Deribit 7D/77D, 15%), Cross-exchange Basis — spot spread across 6 exchanges (10%). Output: -100 to +100 index. Regimes: EXTREMEBULLISH, BULLISH, NEUTRAL, BEARISH, EXTREMEBEARISH. Regime transitions use ±2 hysteresis dead band (enter BULLISH at +27, exit to NEUTRAL at +23). Ed25519 signed.

Canonical format: `v1|SENTIMENT|BTCUSD|MSXI|{value}|INDEX|FR:{fr}:{w},SKEW:{skew}:{w},PCR:{pcr}:{w},TS:{ts}:{w},BASIS:{basis}:{w}|REGIME:{regime}|CONFIDENCE:{c}|METHOD:v1|{timestamp}|{nonce}`
 
## MSSI — Mycelia Signal Stress Index (500 sats / $0.05)
 
- `GET /oracle/stress/market` — market-wide MSSI signed index (0-100 scale)
- `GET /oracle/stress/market/preview` — free unsigned preview
 
MSSI measures systemic market stress independent of price direction. High readings indicate structural fragility — elevated volatility, stablecoin peg stress, or extreme funding positioning. Four components: Volatility Regime via MSVI average BTC+ETH (30%), Stablecoin Stress — max absolute deviation of USDT/USDC from $1.00 (25%), Funding Extremity — absolute z-score of 10-exchange OI-weighted funding rate via MSFR oracle (30%), Funding Dispersion — cross-venue max-min funding rate spread averaged across BTC/ETH/SOL (15%). Output: 0-100 index. Regimes: CALM, ELEVATED, HIGH, EXTREME. Regime transitions use ±2 hysteresis dead band (enter ELEVATED at 27, exit to CALM at 23). Ed25519 signed. Market-wide single number, not per-pair.

Canonical format: `v1|STRESS|MARKET|MSSI|{value}|INDEX|VOL:{vol}:{w},STBL:{stbl}:{w},FR:{fr}:{w},DISP:{disp}:{w}|REGIME:{regime}|CONFIDENCE:{c}|METHOD:v1|{timestamp}|{nonce}`

## MSTI — Mycelia Signal Transmission Index (Crypto-TradFi Contagion)
- `GET /oracle/contagion/market` — MSTI crypto-TradFi contagion index (0-100 scale, $0.05)
- `GET /oracle/contagion/market/preview` — free unsigned preview
- `GET /oracle/contagion/catalogue` — free discovery endpoint

MSTI measures the degree to which crypto markets are coupled to traditional finance. Four components: Rolling 30D BTC-equity Pearson correlation against the active regional equity index (30%), Equity Volatility regime (25%), DXY Momentum — USD strength trend (20%), Beta amplification — how strongly BTC amplifies equity moves (25%). Output: 0-100 index. Regimes: DECOUPLED, MIXED, COUPLED, CONTAGION. When COUPLED or CONTAGION, macro shocks transmit directly into crypto; when DECOUPLED, crypto trades on its own dynamics. Ed25519 signed. Market-wide single number.
 
## Marine Oracle — Sea State, Vessel Tracking, Voyage Forecast

- `GET /oracle/marine/catalogue` — free endpoint listing
- `GET /oracle/marine/{lat}/{lon}/seastate` — signed sea state at coordinates (133 sats / $0.10)
- `GET /oracle/marine/{lat}/{lon}/seastate/preview` — free unsigned preview
- `GET /oracle/marine/vessel/{mmsi}` — live vessel position via AIS + sea state at vessel coordinates (667 sats / $0.50)
- `GET /oracle/marine/route/summary` — worst/mean wave height along a route between two coordinates (267 sats / $0.20)
- `GET /oracle/marine/voyage/forecast` — 7-day voyage forecast projecting vessel position and forecast sea state at each waypoint (667 sats / $0.50)

Sea states: CALM (<0.5m) | SLIGHT (<1.25m) | MODERATE (<2.5m) | ROUGH (<4m) | HEAVY (<6m) | SEVERE (<9m) | EXTREME (≥9m)

Parametric trigger thresholds: heavy weather >4.0m | severe >6.0m | extreme >9.0m

Data sources: Open-Meteo Marine API (wave height, swell, 7-day forecast) + aisstream.io (free global AIS WebSocket, real-time vessel position). Ed25519 signed. Canonical format: `v1|MARINE|{lat},{lon}|WAVE:{w}m|SWELL:{s}m|{sea_state}|{timestamp}|{nonce}`


## Weather Oracle — Parametric Insurance Data (100 sats / $0.10)

- `GET /oracle/weather/catalogue` — free endpoint listing with trigger thresholds
- `GET /oracle/weather/{lat}/{lon}/wrsi/{window}d` — Water Requirement Satisfaction Index, Ed25519 signed (100 sats / $0.10)
- `GET /oracle/weather/{lat}/{lon}/rainfall/{window}d` — Cumulative rainfall in mm, Ed25519 signed (100 sats / $0.10)
- `GET /oracle/weather/{lat}/{lon}/temperature/{window}d` — Temperature min/max/mean, Ed25519 signed (100 sats / $0.10)
- `GET /oracle/weather/{lat}/{lon}/wind/{window}d` — Wind speed max/mean, Ed25519 signed (100 sats / $0.10)

WRSI windows: 30, 60, 90 days. Rainfall/temperature windows: 7, 14, 30, 60, 90 days. Wind windows: 7, 14, 30 days. Global coverage at 0.25° resolution.

Parametric trigger thresholds: drought (WRSI < 0.50), severe drought (WRSI < 0.25), frost (tmin < 0°C), heat stress (tmax > 35°C), gale (wind > 62 km/h), storm (wind > 117 km/h).

Data source: ERA5 reanalysis via Open-Meteo. Designed for parametric crop insurance, agricultural DeFi, and climate risk assessment. Ed25519 signed. Canonical format: `v1|WEATHER|{metric}|{lat},{lon}|{window}D|VALUE:{value}|TRIGGER:{status}|{timestamp}|{nonce}`

## Gas Oracle — Cross-Chain Gas Prices (10 sats / $0.01 per chain, 50 sats / $0.05 index)

Real-time gas prices across 6 chains: Ethereum, Base, Arbitrum, Polygon, Optimism, Solana. Queries 3 public RPCs per chain, computes median gas price in gwei, normalizes to USD transaction cost using live ETH price.

- `GET /oracle/gas/{chain}` — single chain gas price and TX cost (paid)
- `GET /oracle/gas/{chain}/preview` — 24h-stale cached data (free)
- `GET /oracle/gas/index` — all 6 chains sorted cheapest-first with ranking (paid)
- `GET /oracle/gas/index/preview` — 24h-stale cross-chain index (free)
- `GET /oracle/gas/catalogue` — available chains and pricing (free)

Chains: ethereum, base, arbitrum, polygon, optimism, solana (also accepts aliases: eth, arb, poly, op, sol).

Note: L2 costs reflect execution gas only, not L1 data posting fee. Relative ranking is accurate. Ed25519 signed. Canonical format: `v1|GAS|{chain}|{gas_gwei}|{base_fee}|{tx_cost_usd}|{native_price}|{sources}|median|{timestamp}`

## DLC Oracle (Discreet Log Contracts) — 10,000 sats / $7.00

Mycelia Signal operates the only production HTTP DLC oracle — delivering spec-compliant BIP-340 Schnorr attestations for Bitcoin Discreet Log Contract settlement over standard HTTP, payable natively in Lightning sats or USDC. Wire format is byte-for-byte compatible with kormir, dlcdevkit, rust-dlc, bitcoin-s, and any spec-compliant DLC library. The oracle public key is stable and published for independent verification.

Three event types: threshold (legacy), disjoint union (enum), and digit decomposition (numeric). All $7.00 USDC / 10,000 sats flat per event — covers nonce generation, secure storage, and auto-attestation at maturity.

**Legacy endpoints (threshold contracts):**
- `GET /dlc/oracle/pubkey` — secp256k1 oracle public key (free)
- `GET /dlc/oracle/status` — oracle status and active contract counts (free)
- `GET /dlc/oracle/announcements` — list all active announcements (free)
- `GET /dlc/oracle/announcements/{eventid}` — single announcement by event ID (free)
- `GET /dlc/oracle/attestations/{event_id}` — BIP-340 Schnorr attestation for settled event (free)
- `GET /dlc/oracle/threshold` — list active threshold contracts (free)
- `POST /dlc/oracle/threshold` — register threshold contract (10,000 sats / $7.00). Fields: pair, strike, direction, expiry.
- `DELETE /dlc/oracle/threshold/{eventid}` — cancel threshold contract, oracle attests `safe` immediately (10,000 sats / $7.00)

**Enum events — disjoint union (spec-compliant, added Apr 25 2026):**
- `POST /dlc/oracle/enum` — create 2-100 outcome event (10,000 sats / $7.00). Returns BIP-340 signed announcement + TLV blob.
- `POST /dlc/oracle/enum/preview` — free dry-run validation, no nonces generated
- `GET /dlc/oracle/enum` — list all enum events with settled status (free)
- `GET /dlc/oracle/enum/{eid}` — get announcement JSON (free)
- `GET /dlc/oracle/enum/{eid}/serialized` — hex-encoded TLV blob for DLC client ingestion (free)
- `GET /dlc/oracle/enum/{eid}/attestation` — get attestation if settled, 404 if pending (free)
- `POST /dlc/oracle/enum/{eid}/attest` — admin manual attestation with X-Oracle-Secret (admin)

**Numeric events — digit decomposition (spec-compliant, added Apr 25 2026):**
- `POST /dlc/oracle/numeric` — create digit decomposition event (10,000 sats / $7.00). Configurable base (2-256), digits (1-32), signed/unsigned. Optional scaleFactor for sub-unit precision (100=cents, 10000=bps).
- `POST /dlc/oracle/numeric/preview` — free dry-run validation
- `GET /dlc/oracle/numeric` — list all numeric events (free)
- `GET /dlc/oracle/numeric/{eid}` — get announcement JSON (free)
- `GET /dlc/oracle/numeric/{eid}/serialized` — hex-encoded TLV blob (free)
- `GET /dlc/oracle/numeric/{eid}/attestation` — get per-digit attestation if settled (free)
- `POST /dlc/oracle/numeric/{eid}/attest` — admin manual attestation (admin)

**Auto-resolution:** Events created with `metadata.resolverConfig` self-settle at maturity. Enum supports `price_buckets` (fetches price, finds matching bucket) and `webhook` (GETs URL for winning outcome). Numeric supports `price_source` (fetches price, applies scaleFactor) and `webhook`.

**Supported DLC pairs:** BTCUSD, BTCUSDVWAP, BTCEUR, BTCEURVWAP, BTCJPY, ETHUSD, ETHEUR, ETHJPY, SOLUSD, SOLEUR, SOLJPY, XAUUSD, XAUEUR, XAUJPY, XRPUSD, ADAUSD, DOGEUSD

**Spec compliance:** Per discreetlogcontracts/dlcspecs — Oracle.md, Messaging.md, NumericOutcome.md. TLV types: enum_event_descriptor (55302), digit_decomposition_event_descriptor (55306), oracle_event (55330), oracle_announcement (55332), oracle_attestation (55400).

- [DLC Integration](https://myceliasignal.com/docs/dlc/): Full DLC oracle documentation including event ID formats, attestation verification, and contract lifecycle
 

## CME BTC COT — Institutional Positioning (1000 sats / $1.00)

- `GET /oracle/cot/btc` — CFTC Commitments of Traders BTC CME futures positioning, Ed25519 signed

CFTC TFF (Traders in Financial Futures) report for BITCOIN - CHICAGO MERCANTILE EXCHANGE (code 133741). Returns leveraged fund (hedge fund) net position, asset manager net position, and dealer net position — long, short, net, % of open interest, and week-on-week changes. Weekly cadence: data as of prior Tuesday, published Friday 15:30 EST. 24-hour cache. No preview endpoint — data is weekly, not real-time.

Use as institutional overlay signal: divergence between leveraged fund shorts and asset manager longs historically precedes directional moves.

Canonical format: `v1|COT|BTCUSD|LEV:{lev_net}|AM:{am_net}|DEALER:{dealer_net}|OI:{oi}|DATE:{report_date}|{timestamp}|{nonce}`

## Data Sources
 
- [Sources](https://myceliasignal.com/docs/sources/): The exchanges and data providers aggregated for each pair, and how outliers are handled
 
## AI Agent Integrations
 
- [MCP Server](https://myceliasignal.com/docs/mcp/): Model Context Protocol server — 182 tools, enables AI agents to query all endpoints natively via Claude, Cursor, and other MCP-compatible tools. Both L402 and x402 payment rails supported.
- [LangChain Plugin](https://pypi.org/project/langchain-mycelia-signal/): `langchain-mycelia-signal` on PyPI — LangChain tools for all paid endpoints with automatic x402 payment handling. Free tier (unsigned preview) requires no config.
- [ElizaOS Plugin](https://www.npmjs.com/package/@jonathanbulkeley/plugin-mycelia-signal): `@jonathanbulkeley/plugin-mycelia-signal` on npm — ElizaOS plugin for all paid endpoints.
 
## Agent Discovery
 
Mycelia Signal implements standard agent discovery protocols:
 
- `GET /` — machine-readable JSON manifest (name, description, docs, openapi, health, sample endpoint)
- `GET /.well-known/agent.json` — Google A2A protocol agent card with intents and skills
- `GET /.well-known/agent-card.json` — A2A agent card (26 skills)
- `GET /.well-known/x402` — x402 strict-v2 payment discovery document listing all 182 paid endpoints with maxAmountRequired
- `GET /openapi.json` — full OpenAPI 3.1.0 specification (v3.3.1, 258 paths), served directly
- `GET /llms.txt` — this document, served directly
- `GET /health` — health check (free, no payment required)
 
## Optional
 
- [SLA](https://myceliasignal.com/docs/sla/): Uptime commitments and service level terms
- [Homepage](https://myceliasignal.com/): Product overview, pricing, and use cases

## Funding Rate Oracle (MSFR)
Multi-exchange perpetual swap funding rate composite. 10 sources: Binance, Bybit, OKX, Deribit, Hyperliquid, Kraken, Coinbase, Crypto.com, Bitget, dYdX. OI-weighted median, predicted rate for next settlement, z-score vs 3-day rolling history, regime classification (EXTREME_BACKWARDATION / BACKWARDATION / NEUTRAL / CONTANGO / EXTREME_CONTANGO), cross-exchange divergence (arbitrage signal). Updated every 60 seconds. Previews are 2 hours delayed.
- GET /oracle/funding/btc/usd — $0.05 USDC (preview: /oracle/funding/btc/usd/preview)
- GET /oracle/funding/eth/usd — $0.05 USDC (preview: /oracle/funding/eth/usd/preview)
- GET /oracle/funding/sol/usd — $0.05 USDC (preview: /oracle/funding/sol/usd/preview)
- GET /oracle/funding/catalogue — free endpoint listing

## Open Interest Oracle
Aggregate open interest across 5 exchanges (Binance, Bybit, OKX, Deribit, Hyperliquid) with 1h/4h/24h deltas showing positioning changes. Per-exchange breakdown. Updated every 60 seconds. Note: OI units vary by exchange (coins, USD, or contracts).
- GET /oracle/oi/btc/usd — $0.01 USDC (preview: /oracle/oi/btc/usd/preview)
- GET /oracle/oi/eth/usd — $0.01 USDC (preview: /oracle/oi/eth/usd/preview)
- GET /oracle/oi/sol/usd — $0.01 USDC (preview: /oracle/oi/sol/usd/preview)
- GET /oracle/oi/catalogue — free endpoint listing

## Basis/Carry Oracle
Spot-futures basis (mark price vs index price spread) and annualized carry trade returns across 5 exchanges. Per-exchange carry comparison reveals where the best carry trades are. Regime classification: CONTANGO (mark above spot) / BACKWARDATION (mark below spot) / FLAT. Updated every 60 seconds.
- GET /oracle/basis/btc/usd — $0.02 USDC (preview: /oracle/basis/btc/usd/preview)
- GET /oracle/basis/eth/usd — $0.02 USDC (preview: /oracle/basis/eth/usd/preview)
- GET /oracle/basis/sol/usd — $0.02 USDC (preview: /oracle/basis/sol/usd/preview)
- GET /oracle/basis/catalogue — free endpoint listing

## Liquidation Flow Oracle
Real-time liquidation events across Binance, OKX, Deribit, Hyperliquid. Long/short imbalance, clustering intensity, burst detection, per-exchange breakdown. WebSocket-sourced. Ed25519 signed.
- GET /oracle/liquidations/{btc,eth,sol}/usd — $0.03 USDC
- GET /oracle/liquidations/{pair}/preview — free
- GET /oracle/liquidations/catalogue — free

## Order Book Imbalance Oracle
Cross-exchange order book depth, spread, sweep cost across 5 exchanges (Binance, Bybit, OKX, Deribit, Hyperliquid). Top-of-book imbalance, depth ratio, depth collapse detection. Adaptive: 60s normal, 5s during stress (MSSI > 45). Ed25519 signed.
- GET /oracle/orderbook/{btc,eth}/usd — $0.03 USDC
- GET /oracle/orderbook/{pair}/preview — free
- GET /oracle/orderbook/catalogue — free

## IV Surface Oracle
Implied volatility surface from Deribit options chain. ATM IV, 25-delta put/call IV, skew, near/far term structure ratio. Parsed from 870+ BTC and 690+ ETH options every 60 seconds. Ed25519 signed.
- GET /oracle/iv/{btc,eth}/usd — $0.03 USDC
- GET /oracle/iv/{pair}/preview — free
- GET /oracle/iv/catalogue — free

## Multi-Exchange Options Greeks Oracle
Cross-exchange consensus Greeks (delta, gamma, theta, vega, rho) computed from 2130+ BTC, 1822+ ETH, and 246+ SOL options across Deribit, OKX, and Bybit. Black-Scholes with custom norm_cdf. ATM summary, 25-delta skew, per-expiry breakdown. 30-second cache. Ed25519 signed.
- GET /oracle/greeks/{btc,eth,sol}/usd — $0.05 USDC
- GET /oracle/greeks/{ccy}/usd/preview — free
- GET /oracle/greeks/catalogue — free

## Futures Term Structure Oracle
Multi-exchange futures term structure with basis, annualized carry, and contango/backwardation regime detection across Deribit, OKX, and Bybit. Per-maturity breakdown with days-to-expiry. Ed25519 signed.
- GET /oracle/term-structure/{btc,eth,sol}/usd — $0.05 USDC
- GET /oracle/term-structure/{ccy}/usd/preview — free
- GET /oracle/term-structure/catalogue — free

## Options Instrument Discovery Oracle
Multi-exchange options instrument discovery across Deribit, OKX, and Bybit. 2002+ BTC contracts, 106 unique strikes, 11 expiries ($20K–$380K range). Per-expiry breakdown with cross-exchange coverage. Ed25519 signed.
- GET /oracle/instruments/{btc,eth,sol}/options — $0.03 USDC
- GET /oracle/instruments/{ccy}/options/preview — free
- GET /oracle/instruments/catalogue — free

## SVI Volatility Surface Oracle
Gatheral 2004 Stochastic Volatility Inspired (SVI) arbitrage-free IV parameterization. 5 fitted parameters (a, b, rho, m, sigma) per expiry with smooth smile interpolation. Correct negative skew (rho ~ -0.20). Ed25519 signed.
- GET /oracle/svi/{btc,eth,sol}/usd — $0.05 USDC
- GET /oracle/svi/{ccy}/usd/preview — free
- GET /oracle/svi/catalogue — free

## Multi-Exchange IV Surface Oracle
Per-strike implied volatility from 3 exchanges with cross-exchange divergence detection and mispricing alerts. 1040+ strikes across 11 expiries. ATM term structure from near to far DTE. Max divergence signals actionable arbitrage. Ed25519 signed.
- GET /oracle/iv-surface/{btc,eth,sol}/usd — $0.05 USDC
- GET /oracle/iv-surface/{ccy}/usd/preview — free
- GET /oracle/iv-surface/catalogue — free

## DeFi Yield Oracle
On-chain lending rates from 10 protocols (Aave V3, Morpho Blue, Euler v2, Spark, Compound V3, Venus, Benqi, Moonwell, Sky DSR) across 7 chains (Ethereum, Base, Arbitrum, Polygon, Optimism, Avalanche, BNB). Direct smart contract reads, 15-min refresh. Previews 60min delayed.
- GET /oracle/defi/yield/all — $0.05 USDC (all 53 rates)
- GET /oracle/defi/yield/compare — $0.05 USDC (USDC rates ranked across all protocols)
- GET /oracle/defi/yield/best/{asset} — $0.05 USDC (best yield for USDC, USDT, WETH, DAI, WBTC)
- GET /oracle/defi/yield/{protocol}/{chain}/{asset} — $0.05 USDC (specific rate)
- GET /oracle/defi/yield/catalogue — free (list all protocols and chains)
- GET /oracle/defi/yield/*/preview — free (60min delayed)

## GPU Compute Oracle
Real-time GPU pricing aggregated across AWS Spot, Vast.ai, RunPod, Akash Network, Azure, GCP. Normalized to $/GPU-hour. 81 GPU models including H100, A100, H200, RTX 4090, L40S, MI300X. 1341 prices. 5-min refresh. Previews 60min delayed.
- GET /oracle/compute/all — $0.05 USDC (all 1341 prices across 81 models)
- GET /oracle/compute/compare — $0.05 USDC (cheapest price per model, ranked)
- GET /oracle/compute/best/{gpu_model} — $0.05 USDC (best price for H100_SXM, A100_SXM, H200, RTX_4090, L40S, etc)
- GET /oracle/compute/catalogue — free (list all models and sources)
- GET /oracle/compute/*/preview — free (60min delayed)

## LLM Inference Pricing Oracle
Normalized LLM inference pricing across 6 providers (OpenAI, Anthropic, Groq, Together, Fireworks, Cerebras). 26 models, input/output $/M tokens, context windows, tier classification (frontier/efficient/fast/reasoning). Ed25519 signed. Updated weekly.
- GET /oracle/inference/{provider}/pricing — $0.02 USDC (provider: openai, anthropic, groq, together, fireworks, cerebras)
- GET /oracle/inference/all — $0.02 USDC (all 26 models normalized)
- GET /oracle/inference/compare — $0.02 USDC (cheapest per tier across all providers)
- GET /oracle/inference/compare/task/{task} — $0.02 USDC (best model for chat, code, reasoning, long_context, fast)
- GET /oracle/inference/catalogue — free

## Economic Calendar Oracle
Forward-looking macro event calendar from Finnhub. Next 30 days, high/medium impact events for US, EU, GB, JP, CN. Actual vs estimate where released. Surprise index (actual minus consensus). BTC/ETH options expiry from Deribit. Ed25519 signed. 1hr refresh.
- GET /oracle/econ/calendar — $0.05 USDC (next 30 days, all priority events)
- GET /oracle/econ/calendar/today — $0.05 USDC (today's events only)
- GET /oracle/econ/calendar/fomc — $0.05 USDC (next FOMC and upcoming Fed decisions)
- GET /oracle/econ/calendar/country/{country} — $0.05 USDC (events by country code e.g. US, EU, GB, JP, CN)
- GET /oracle/econ/surprises — $0.10 USDC (last 20 releases, actual vs estimate deviation, surprise index)
- GET /oracle/econ/expiry/{btc,eth} — $0.05 USDC (next 8 Deribit expiries tagged weekly/monthly/quarterly)
- GET /oracle/econ/calendar/preview — free (today + 5 high-impact)
- GET /oracle/econ/expiry/{currency}/preview — free (next 2 expiries)

## DeFi Protocol Metrics Oracle
Protocol-level TVL, avg supply APR, and utilization aggregated from DeFiLlama + on-chain reads. 8 protocols ($25B TVL coverage): Aave, Compound, Morpho, Spark, Sky, Euler, Venus, Benqi. 30-min refresh. Ed25519 signed.
- GET /oracle/defi/metrics — $0.05 USDC (all protocols sorted by TVL)
- GET /oracle/defi/metrics/{protocol} — $0.05 USDC (single protocol with full per-asset rate breakdown)
- GET /oracle/defi/metrics/preview — free preview

## Liquidation Flow Oracle
Historical liquidation event flow from live WebSocket logger (94K+ events, 31 days history). Configurable time window. Long/short notional breakdown, dominant side, largest single liquidation, by-exchange split. Ed25519 signed.
- GET /oracle/liq-flow/{btc,eth,sol}?window={1h,4h,24h} — $0.05 USDC
- GET /oracle/liq-flow/{currency}/preview — free preview

## Signed Historical Data Oracle
Cryptographically signed historical data with batch Ed25519 signatures. Index rows include original per-row signatures from collection time — unique cryptographic provenance no other oracle offers.
- GET /oracle/history/spot/{base}/{quote}?from=&to=&interval= — $0.05 USDC (OHLCV, 1m/5m/15m/1h/4h/1d, up to 60 days, max 1440 rows)
- GET /oracle/history/funding/{base}/{quote}?from=&to=&exchange= — $0.05 USDC (per-exchange funding rates, 18 days history)
- GET /oracle/history/index/msxi/{btcusd,ethusd}?from=&to= — $0.10 USDC (MSXI sentiment history, 60 days, per-row signed)
- GET /oracle/history/index/msvi/{btcusd,ethusd}?from=&to= — $0.10 USDC (MSVI volatility history, 63 days, per-row signed)
- GET /oracle/history/index/mssi?from=&to= — $0.10 USDC (MSSI stress history, 56 days, per-row signed)
- GET /oracle/history/index/msti?from=&to= — $0.10 USDC (MSTI contagion history, 56 days, per-row signed)
- GET /oracle/history/*/preview — free (last 3-5 rows)
- GET /oracle/history/catalogue — free

## Market State Synopsis Oracle (NEW S89)
Single-call market state snapshot aggregating 15 signals: all 4 proprietary indices (MSSI/MSTI/MSXI/MSVI), BTC+ETH funding rates, BTC OI deltas, BTC liquidation flow 1h, BTC+ETH spot prices, BTC VWAP, BTC basis regime, economic calendar today, and BTC options expiry proximity. 60s background cache. Single Ed25519 signature over full canonical. Replaces ~15 individual calls at ~$0.85 total.
- GET /oracle/synopsis/market — $0.25 USDC (full 15-signal snapshot, Ed25519 signed)
- GET /oracle/synopsis/market/preview — free (regime + price only, unsigned)
- GET /oracle/synopsis/catalogue — free

## BTC Perp Trading Regime Oracle (NEW S90)
Interpreted perp trading regime for BTC from 10 signals: MSXI sentiment, MSVI volatility, funding rate, OI deltas, basis, liquidation flow, orderbook depth, IV surface, spot price, term structure. Machine-actionable regime classification with directional bias, confidence score, and risk level. 30s cache. Ed25519 signed. [Oracle Regimes layer]
Regimes: BULLISH_MOMENTUM, MILD_BULLISH, NEUTRAL_CHOPPY, MILD_BEARISH, BEARISH_MOMENTUM, BEARISH_FUNDING_EXTREME, SQUEEZE_SETUP, LONG_TRAP, VOLATILITY_SPIKE.
- GET /oracle/perp/btc — $0.15 USDC (full 10-signal classification, Ed25519 signed)
- GET /oracle/perp/btc/preview — free (regime + bias + confidence, unsigned)
- GET /oracle/perp/catalogue — free

## Macro Risk Oracle (NEW S90 — Layer 3 Oracle Intelligence)
Cross-domain macro risk score combining MSSI crypto stress (40%), MSTI contagion (30%), and economic calendar high-impact events (30%). Returns risk_score (0-100) and risk_regime (LOW/MODERATE/ELEVATED/HIGH/CRITICAL). 60s cache. Ed25519 signed. Disclaimer included — regime classification only, not financial advice.
- GET /oracle/intel/macro/risk — $1.00 USDC (full signed risk assessment)
- GET /oracle/intel/macro/risk/preview — free (score + regime, unsigned)
- GET /oracle/intel/catalogue — free

## SOL Perp Trading Regime Oracle (NEW S90 — Layer 2 Oracle Information)
SOL perp trading regime from 8 signals (funding, OI, basis, liq flow, orderbook, IV, price, term structure). Same regime classification as BTC/ETH. 30s cache. Ed25519 signed.
- GET /oracle/perp/sol — $0.15 USDC
- GET /oracle/perp/sol/preview — free

## Perp Setup Scanner (NEW S90 — Layer 3 Oracle Intelligence)
Scans BTC+ETH+SOL perp regimes simultaneously. Returns highest_confidence_setup with signal_alignment (not buy/sell), edge, invalidation_conditions, and market_bias from MSSI. 30s cache. Ed25519 signed. Disclaimer included.
- GET /oracle/intel/perp/setup — $1.00 USDC
- GET /oracle/intel/perp/setup/preview — free
- GET /oracle/intel/perp/catalogue — free

## DeFi Opportunity Oracle (NEW S90 — Layer 3 Oracle Intelligence)
Risk-adjusted DeFi yield across 15+ protocols. Penalizes raw APR by MSSI stress regime (up to -4%) and MSTI contagion for cross-chain protocols. Returns highest_opportunity with raw_apr, stress_penalty, risk_adjusted_apr. 60s cache. Ed25519 signed. Disclaimer included.
- GET /oracle/intel/defi/opportunity — $0.75 USDC
- GET /oracle/intel/defi/opportunity/preview — free
- GET /oracle/intel/defi/catalogue — free

## Equity Indices (NEW S92 — Layer 1 Oracle Data)
Two equity composite indices using free public data (CBOE, Yahoo Finance). 300s cache. Ed25519 signed.

## MESI — Mycelia Equity Stress Index
5-signal equity stress composite: VIX level (30%), IV/RV ratio (20%), VVIX tail risk (20%), credit stress HYG/LQD (15%), DXY momentum (15%). 0-100 scale. Regimes: CALM / MODERATE / ELEVATED / HIGH / EXTREME.
- GET /oracle/stress/equity — $0.05 USDC
- GET /oracle/stress/equity/preview — free

## MNVI — Mycelia NQ Volatility Index
5-signal NQ volatility composite: NDX RV30 (25%), VIX9D/VIX term ratio (20%), NDX/SPX vol beta (20%), VVIX tail risk (20%), NDX price momentum (15%). 0-100 scale.
- GET /oracle/volatility/nq/usd — $0.05 USDC
- GET /oracle/volatility/nq/usd/preview — free

## Perp Regime Change (NEW S91 — Layer 3 Oracle Intelligence)
Detects perp regime transitions vs 2h ago for BTC, ETH, and SOL simultaneously. Queries signed perp_history.db. Returns from_regime, to_regime, bias_changed per currency. Disclaimer included.
- GET /oracle/intel/regime/change — $0.50 USDC
- GET /oracle/intel/regime/change/preview — free

## TradFi Regime Oracle (NEW S94 — Layer 2 Oracle Information)
Classifies traditional finance market regime from MESI equity stress index, MNVI NQ volatility index, and US 10Y-2Y yield curve (FRED T10Y2Y). Returns RISK_ON / NEUTRAL / STRESS / PANIC with confidence score and dominant signal. 300s cache. Ed25519 signed.
- GET /oracle/regime/equity — $0.10 USDC (full signed classification)
- GET /oracle/regime/equity/preview — free (regime + confidence + inputs, unsigned)
- GET /oracle/regime/equity/catalogue — free

## Liquidity Regime Oracle (NEW S94 — Layer 2 Oracle Information)
Classifies BTC crypto market liquidity from five signals: funding rate regime, open interest delta (1h/4h/24h), basis regime, liquidation flow (1h notional), and orderbook spread/imbalance. Returns DEEP / NORMAL / THIN / FRAGILE with stress score and dominant signal. 60s cache. Ed25519 signed.
- GET /oracle/regime/liquidity — $0.10 USDC (full signed classification)
- GET /oracle/regime/liquidity/preview — free (regime + signals + inputs, unsigned)
- GET /oracle/regime/liquidity/catalogue — free

## Cross-Asset Divergence Oracle (NEW S94 — Layer 3 Oracle Intelligence)
Detects disagreement between crypto and TradFi market regimes. Aggregates BTC/ETH/SOL perp regimes, TradFi regime, MSTI contagion, macro risk score, basis regime, funding regime, and active regime transitions into a divergence score. Returns NONE / LOW / MODERATE / HIGH / EXTREME with direction and contagion flag. 60s cache. Ed25519 signed. Disclaimer included.
Directions: aligned, crypto_bullish_tradfi_stressed, crypto_bearish_tradfi_complacent, crypto_leads_recovery, crypto_ignores_risk, tradfi_stressed_crypto_unmoved.
- GET /oracle/intel/divergence — $0.50 USDC (full signed divergence assessment)
- GET /oracle/intel/divergence/preview — free (divergence + direction + signals, unsigned)
- GET /oracle/intel/divergence/catalogue — free

## Regime Consensus Oracle (NEW S94 — Layer 3 Oracle Intelligence)
Aggregates all regime signals into a single weighted alignment score. Inputs: BTC/ETH/SOL perp regimes (1.0 weight each), TradFi regime (1.5), MSSI stress (1.0), MSTI contagion (0.5), Macro Risk (1.5), Regime Change flag, Divergence level. Returns STRONG / MODERATE / WEAK / CONFLICTED with dominant theme and per-category vote breakdown. 60s cache. Ed25519 signed. Disclaimer included.
Dominant themes: BULLISH, STRESSED, BEARISH, NEUTRAL, MIXED.
- GET /oracle/intel/consensus — $0.50 USDC (full signed consensus with votes)
- GET /oracle/intel/consensus/preview — free (consensus + alignment + votes, unsigned)
- GET /oracle/intel/consensus/catalogue — free

## Regime Persistence Oracle (NEW S94 — Layer 3 Oracle Intelligence)
Answers how long the current perp regime has been running and where that sits historically. Queries perp_history.db directly — no upstream paid calls. Returns current_regime, duration_hours, historical_percentile, typical_remaining_hours based on median of all historical runs. BTC/ETH/SOL via ?currency= param. 30s cache. 24h stale preview. Ed25519 signed. Disclaimer included.
- GET /oracle/intel/regime/persistence — $0.15 USDC (full signed persistence context)
- GET /oracle/intel/regime/persistence/preview — free (24h stale, unsigned)
- GET /oracle/intel/regime/persistence/catalogue — free