# 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 81 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/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), $0.05 (MSVI/MSXI/MSSI), $1.00 (econ/commodities/COT), $0.10 (weather), $7.00 (DLC threshold/enum/numeric).
 
## 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 81 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 v2.1.0, 173 paths) covering all endpoints, request/response schemas, canonical attestation format, and payment protocol details
 
## Supported Endpoints (78 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
 
Most paid endpoints have a free `/preview` path returning unsigned data (up to 5 minutes stale) for development and testing. COT (weekly data) and marine/weather coordinate-based endpoints are exceptions — see their dedicated sections.
 
## 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) — 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 — 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 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 23 intents, 11 skills
- `GET /.well-known/x402` — x402 payment discovery document listing all 81 paid endpoints
- `GET /openapi.json` — full OpenAPI 3.1.0 specification (v2.1.0, 173 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