# Mycelia Signal
 
> 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, Marine Oracle (sea state, vessel tracking, voyage forecast), CME BTC COT institutional positioning, and parametric weather/climate oracle data across 78 paid endpoints. 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.
 
## 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|TIMESTAMP|NONCE|SOURCES|METHOD`
- [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).
- [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), $0.05 (MSVI/MSXI/MSSI), $1.00 (econ/commodities/COT), $0.10 (weather), $7.00 (DLC threshold).
 
## 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 72 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://myceliasignal.com/openapi.json): Machine-readable API specification (OpenAPI 3.1.0 v1.7.0) covering all endpoints, request/response schemas, canonical attestation format, and payment protocol details
 
## Supported Endpoints (72 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 indices** (500 sats / $0.05): MSVI BTC/USD, MSVI ETH/USD, MSXI BTC/USD, MSXI ETH/USD, MSSI Market
 
All paid endpoints have a free `/preview` path returning unsigned data (up to 5 minutes stale) for development and testing.
 
## 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 (Binance+Bybit, 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 (Binance+Bybit, 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 5 exchanges (10%). Output: -100 to +100 index. Regimes: EXTREMEBULLISH, BULLISH, NEUTRAL, BEARISH, EXTREMEBEARISH. 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. Three components: Volatility Regime via MSVI average BTC+ETH (35%), Stablecoin Stress — max absolute deviation of USDT/USDC from $1.00 (30%), Funding Extremity — absolute z-score of OI-weighted funding rate (35%). Output: 0-100 index. Regimes: CALM, ELEVATED, HIGH, EXTREME. 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}|REGIME:{regime}|CONFIDENCE:{c}|METHOD:v1|{timestamp}|{nonce}`
 
## 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}`

## DLC Oracle (Discreet Log Contracts)
 
Mycelia Signal operates the only production HTTP DLC oracle — delivering cryptographically signed attestations for Bitcoin Discreet Log Contract settlement over standard HTTP, payable natively in Lightning sats or USDC. The oracle public key is stable and published for independent verification.
 
**Free endpoints (no payment required):**
- `GET /dlc/oracle/pubkey` — secp256k1 oracle public key for Schnorr attestation verification
- `GET /dlc/oracle/status` — oracle status: announcement counts, supported pairs, active threshold contracts
- `GET /dlc/oracle/announcements` — list all active DLC announcements (numeric + threshold contracts)
- `GET /dlc/oracle/announcements/{eventid}` — single announcement by event ID including rpoints
- `GET /dlc/oracle/attestations/{event_id}` — BIP-340 Schnorr attestation for a settled event (HTTP 425 if not yet attested)
- `GET /dlc/oracle/threshold` — list all active threshold contracts currently being monitored
 
**Paid endpoints:**
- `POST /dlc/oracle/threshold` — register a threshold contract (10,000 sats L402 / $7.00 USDC x402). Fields: `pair` (e.g. BTCUSD), `strike` (price level), `direction` (above or below), `expiry` (Unix timestamp). Oracle monitors and attests on breach or expiry.
- `DELETE /dlc/oracle/threshold/{eventid}` — cancel an active threshold contract, oracle attests `safe` immediately (10,000 sats / $7.00 USDC).
 
**Supported DLC pairs:** BTCUSD, BTCUSDVWAP, BTCEUR, BTCEURVWAP, BTCJPY, ETHUSD, ETHEUR, ETHJPY, SOLUSD, SOLEUR, SOLJPY, XAUUSD, XAUEUR, XAUJPY, XRPUSD, ADAUSD, DOGEUSD
 
- [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 — 123 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 66 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 66 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 11 intents, 8 skills
- `GET /.well-known/x402` — x402 payment discovery document listing all 78 paid endpoints
- `GET /openapi.json` — redirects to full OpenAPI 3.1.0 specification (v1.8.0, 155 paths)
- `GET /llms.txt` — redirects to this document
- `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