{"openapi":"3.0.3","info":{"title":"Mercury x402 API","version":"1.2.0","description":"Deterministic financial data with cryptographic provenance.\n\nPayment required via x402 protocol (HTTP 402 + USDC on Base).\nAll paid endpoints require the `payment-signature` header in production.\n\n**Payment Flow:**\n1. Call endpoint without auth → receive 402 with Payment-Required header\n2. Pay via x402 protocol (USDC on Base mainnet)\n3. Retry with `payment-signature` → receive 200 + data\n\n**Data Sources:**\n- FRED (Federal Reserve Economic Data): 800k+ economic series\n- U.S. Treasury rates: 11 maturities via FRED DGS series\n","contact":{"name":"Mercury x402 Support","url":"https://mercury402.uk"},"license":{"name":"Proprietary"},"guidance":"Mercury402 provides deterministic financial data (FRED, Treasury rates, macro indicators) via x402 micropayments on Base. Call any endpoint, receive 402, pay via an x402-compatible client, then retry with the payment-signature header."},"x-discovery":{"ownershipProofs":[]},"servers":[{"url":"https://mercury402.uk","description":"Production"},{"url":"http://localhost:4020","description":"Local development"}],"security":[{"x402PaymentSignature":[]}],"tags":[{"name":"FRED","description":"Federal Reserve Economic Data series"},{"name":"Treasury","description":"U.S. Treasury yield curve data"},{"name":"Composite","description":"Multi-series composite dashboards"},{"name":"Discovery","description":"Service discovery and health"},{"name":"Documentation","description":"Documentation and examples"}],"paths":{"/v1/fred/{series_id}":{"get":{"summary":"Fetch FRED economic series data","description":"Returns observations for any FRED series ID (GDP, UNRATE, DGS10, etc.).\n\n**Pricing:**\n- Single date or latest: $0.05\n- Date range (observation_start + observation_end): $0.10\n\n**Common Series:**\n- UNRATE: Unemployment Rate\n- GDP: Gross Domestic Product\n- CPIAUCSL: Consumer Price Index\n- DGS10: 10-Year Treasury Rate\n- FEDFUNDS: Federal Funds Rate\n\nBrowse all series: https://fred.stlouisfed.org/\n","operationId":"getFredSeries","x-payment-info":{"pricingMode":"fixed","price":"0.010000","protocols":["x402","mpp"]},"tags":["FRED"],"security":[{"x402PaymentSignature":[]}],"parameters":[{"name":"series_id","in":"path","required":true,"schema":{"type":"string","example":"UNRATE"},"description":"FRED series ID (case-sensitive)"},{"name":"date","in":"query","schema":{"type":"string","format":"date","example":"2026-01-01"},"description":"Single date observation (YYYY-MM-DD)"},{"name":"observation_start","in":"query","schema":{"type":"string","format":"date","example":"2020-01-01"},"description":"Start date for range query (requires observation_end)"},{"name":"observation_end","in":"query","schema":{"type":"string","format":"date","example":"2023-12-31"},"description":"End date for range query (requires observation_start)"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":1,"example":5},"description":"Max observations to return (ignored if date/range specified)"}],"responses":{"200":{"description":"Successful response with data and provenance","headers":{"X-Mercury-Price":{"schema":{"type":"string","example":"$0.01"},"description":"Price charged for this call"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FREDResponse"},"example":{"data":{"series_id":"UNRATE","title":"Unemployment Rate","units":"Percent","frequency":"Monthly","seasonal_adjustment":"Seasonally Adjusted","last_updated":"2026-02-07T13:03:22.000Z","observation_count":1,"observations":[{"date":"2026-01-01","value":"4.0"}]},"provenance":{"source":"Federal Reserve Economic Data (FRED)","source_url":"https://fred.stlouisfed.org/series/UNRATE","fetched_at":"2026-03-04T18:20:00.000Z","mercury_version":"v1.0","deterministic":true,"signature":"0x42d8f3f315633eaab09da600a89463314a1344da..."}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"description":"Series not found or no data available","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["SERIES_NOT_FOUND","NO_DATA_FOUND"]},"message":{"type":"string"},"series_id":{"type":"string"}}}}},"example":{"error":{"code":"SERIES_NOT_FOUND","message":"Series 'INVALID' not found in FRED database","series_id":"INVALID"}}}}},"429":{"description":"FRED API rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string"},"retry_after":{"type":"integer","example":60}}}}}}}},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/treasury/yield-curve/daily-snapshot":{"get":{"summary":"U.S. Treasury yield curve daily snapshot","description":"Returns daily U.S. Treasury par yield curve rates across 11 maturities.\nData sourced from FRED series (DGS1MO through DGS30).\n\n**Price:** $0.10\n\n**Maturities covered:**\n- 1 Month, 3 Month, 6 Month\n- 1 Year, 2 Year, 3 Year, 5 Year, 7 Year\n- 10 Year, 20 Year, 30 Year\n\n**Data quality:** Returns 404 if fewer than 5 maturities available.\n","operationId":"getTreasuryYieldCurve","x-payment-info":{"pricingMode":"fixed","price":"0.020000","protocols":["x402","mpp"]},"tags":["Treasury"],"security":[{"x402PaymentSignature":[]}],"parameters":[{"name":"date","in":"query","schema":{"type":"string","format":"date","example":"2026-03-01"},"description":"Specific date (defaults to latest available)"},{"name":"v","in":"query","schema":{"type":"string","enum":["0.9","1.0"],"default":"1.0"},"description":"Response format version:\n- 0.9: Legacy format (rates only)\n- 1.0: New format with provenance (default)\n"}],"responses":{"200":{"description":"Treasury yield curve data with provenance","headers":{"X-Mercury-Price":{"schema":{"type":"string","example":"$0.10"}}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/TreasuryResponseV1"},{"$ref":"#/components/schemas/TreasuryResponseV0_9"}]},"examples":{"v1":{"summary":"Version 1.0 (with provenance)","value":{"data":{"record_date":"2026-03-02","rates":{"1_MONTH":3.74,"3_MONTH":3.72,"6_MONTH":3.68,"1_YEAR":3.54,"2_YEAR":3.47,"3_YEAR":3.49,"5_YEAR":3.62,"7_YEAR":3.82,"10_YEAR":4.05,"20_YEAR":4.64,"30_YEAR":4.7}},"provenance":{"source":"Federal Reserve Economic Data (FRED) - U.S. Treasury rates","source_url":"https://fred.stlouisfed.org","fetched_at":"2026-03-04T18:07:49.590Z","mercury_version":"v1.0","deterministic":true,"cache_until":"2026-03-05T18:07:49.590Z","series_coverage":"11/11 maturities","record_date":"2026-03-02","signature":"0x42d8f3f315633eaab09da600a89463314a1344da..."}}},"v0_9":{"summary":"Version 0.9 (legacy)","value":{"record_date":"2026-03-02","rates":{"1_MONTH":3.74,"3_MONTH":3.72,"10_YEAR":4.05,"30_YEAR":4.7}}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"description":"No valid Treasury rate data available","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"NO_DATA_AVAILABLE"},"message":{"type":"string"},"alternatives":{"type":"array","items":{"type":"string"}}}}}},"example":{"error":{"code":"NO_DATA_AVAILABLE","message":"No valid Treasury rate data available for requested date","alternatives":["/v1/fred/DGS10","/v1/fred/DGS2","/v1/fred/DGS30"]}}}}},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/composite/economic-dashboard":{"get":{"summary":"Economic overview dashboard","description":"Composite endpoint returning GDP, CPI, and Unemployment in one call.\n\n**Price:** $0.50\n\n**Includes:**\n- GDP (Gross Domestic Product)\n- CPIAUCSL (Consumer Price Index)\n- UNRATE (Unemployment Rate)\n\nReturns latest observation for each series.\n","operationId":"getEconomicDashboard","x-payment-info":{"pricingMode":"fixed","price":"0.500000","protocols":["x402","mpp"]},"tags":["Composite"],"security":[{"x402PaymentSignature":[]}],"responses":{"200":{"description":"Economic indicators dashboard","headers":{"X-Mercury-Price":{"schema":{"type":"string","example":"$0.50"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompositeResponse"},"example":{"data":{"dashboard":"economic-overview","timestamp":"2026-03-04T18:20:00.000Z","indicators":[{"series_id":"GDP","title":"Gross Domestic Product","value":"28230.532","date":"2025-10-01","units":"Billions of Dollars"},{"series_id":"CPIAUCSL","title":"Consumer Price Index","value":"315.249","date":"2026-01-01","units":"Index 1982-1984=100"},{"series_id":"UNRATE","title":"Unemployment Rate","value":"4.0","date":"2026-01-01","units":"Percent"}]},"provenance":{"source":"Federal Reserve Economic Data (FRED)","source_url":"https://fred.stlouisfed.org/series/composite/economic-dashboard","fetched_at":"2026-03-04T18:20:00.000Z","mercury_version":"v1.0","deterministic":true}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/composite/inflation-tracker":{"get":{"summary":"Inflation metrics dashboard","description":"Composite endpoint returning CPI, PCE, and Core CPI in one call.\n\n**Price:** $0.40\n\n**Includes:**\n- CPIAUCSL (Consumer Price Index - All Items)\n- PCEPI (Personal Consumption Expenditures Price Index)\n- CPILFESL (Core CPI - Less Food & Energy)\n","operationId":"getInflationTracker","x-payment-info":{"pricingMode":"fixed","price":"0.400000","protocols":["x402","mpp"]},"tags":["Composite"],"security":[{"x402PaymentSignature":[]}],"responses":{"200":{"description":"Inflation indicators","headers":{"X-Mercury-Price":{"schema":{"type":"string","example":"$0.40"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompositeResponse"},"example":{"data":{"dashboard":"inflation-tracker","timestamp":"2026-03-04T18:20:00.000Z","indicators":[{"series_id":"CPIAUCSL","title":"Consumer Price Index (All Items)","value":"315.249","date":"2026-01-01","units":"Index 1982-1984=100"},{"series_id":"PCEPI","title":"Personal Consumption Expenditures Price Index","value":"123.456","date":"2026-01-01","units":"Index 2017=100"},{"series_id":"CPILFESL","title":"Core CPI (Less Food & Energy)","value":"320.789","date":"2026-01-01","units":"Index 1982-1984=100"}]},"provenance":{"source":"Federal Reserve Economic Data (FRED)","fetched_at":"2026-03-04T18:20:00.000Z","mercury_version":"v1.0"}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/composite/labor-market":{"get":{"summary":"Labor market health dashboard","description":"Composite endpoint returning unemployment, jobless claims, and payrolls in one call.\n\n**Price:** $0.40\n\n**Includes:**\n- UNRATE (Unemployment Rate)\n- ICSA (Initial Jobless Claims)\n- PAYEMS (Total Nonfarm Payrolls)\n","operationId":"getLaborMarket","x-payment-info":{"pricingMode":"fixed","price":"0.400000","protocols":["x402","mpp"]},"tags":["Composite"],"security":[{"x402PaymentSignature":[]}],"responses":{"200":{"description":"Labor market indicators","headers":{"X-Mercury-Price":{"schema":{"type":"string","example":"$0.40"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompositeResponse"},"example":{"data":{"dashboard":"labor-market","timestamp":"2026-03-04T18:20:00.000Z","indicators":[{"series_id":"UNRATE","title":"Unemployment Rate","value":"4.0","date":"2026-01-01","units":"Percent"},{"series_id":"ICSA","title":"Initial Jobless Claims","value":"210000","date":"2026-03-01","units":"Number"},{"series_id":"PAYEMS","title":"Total Nonfarm Payrolls","value":"158500","date":"2026-01-01","units":"Thousands of Persons"}]},"provenance":{"source":"Federal Reserve Economic Data (FRED)","fetched_at":"2026-03-04T18:20:00.000Z","mercury_version":"v1.0"}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/macro/snapshot/all":{"get":{"summary":"Complete macroeconomic snapshot","description":"Fetches all major economic indicators in a single call:\nGDP, UNRATE, CPI, FEDFUNDS, DGS10, DGS2, T10Y2Y, VIX, Dollar Index, Consumer Sentiment.\n\n**Price:** $0.05\n\n**Indicators (10 total):**\n- GDP: Gross Domestic Product\n- UNRATE: Unemployment Rate\n- CPIAUCSL: Consumer Price Index\n- FEDFUNDS: Federal Funds Rate\n- DGS10: 10-Year Treasury Yield\n- DGS2: 2-Year Treasury Yield\n- T10Y2Y: 10Y-2Y Yield Spread\n- VIXCLS: VIX Volatility Index\n- DTWEXBGS: Trade Weighted U.S. Dollar Index\n- UMCSENT: Consumer Sentiment Index\n","operationId":"getMacroSnapshot","x-payment-info":{"pricingMode":"fixed","price":"0.050000","protocols":["x402","mpp"]},"tags":["Composite"],"security":[{"x402PaymentSignature":[]}],"responses":{"200":{"description":"Macro snapshot with all indicators","headers":{"X-Mercury-Price":{"schema":{"type":"string","example":"$0.05"}},"X-Data-Age":{"schema":{"type":"integer","description":"Seconds since data was cached"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"snapshot_date":{"type":"string","format":"date"},"source":{"type":"string","example":"FRED"},"indicators":{"type":"object","properties":{"gdp":{"$ref":"#/components/schemas/Indicator"},"unemployment_rate":{"$ref":"#/components/schemas/Indicator"},"cpi":{"$ref":"#/components/schemas/Indicator"},"fed_funds_rate":{"$ref":"#/components/schemas/Indicator"},"yield_10y":{"$ref":"#/components/schemas/Indicator"},"yield_2y":{"$ref":"#/components/schemas/Indicator"},"yield_spread_10y2y":{"$ref":"#/components/schemas/Indicator"},"vix":{"$ref":"#/components/schemas/Indicator"},"dollar_index":{"$ref":"#/components/schemas/Indicator"},"consumer_sentiment":{"$ref":"#/components/schemas/Indicator"}}},"deterministic":{"type":"boolean"}}},"provenance":{"$ref":"#/components/schemas/Provenance"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"description":"No data available"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/treasury/yield-curve/historical":{"post":{"summary":"Historical Treasury yield curve data","description":"Returns daily yield curve snapshots for a specified date range.\nFetches all 11 maturities (1M, 3M, 6M, 1Y, 2Y, 3Y, 5Y, 7Y, 10Y, 20Y, 30Y).\n\n**Price:** $0.05\n\n**Constraints:**\n- Maximum date range: 90 days\n- Dates must be in YYYY-MM-DD format\n- start_date must be before end_date\n","operationId":"getTreasuryHistorical","x-payment-info":{"pricingMode":"fixed","price":"0.050000","protocols":["x402","mpp"]},"tags":["Treasury"],"security":[{"x402PaymentSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["start_date","end_date"],"properties":{"start_date":{"type":"string","format":"date","example":"2024-01-01"},"end_date":{"type":"string","format":"date","example":"2024-01-31"}}}}}},"responses":{"200":{"description":"Historical yield curve snapshots","headers":{"X-Mercury-Price":{"schema":{"type":"string","example":"$0.05"}},"X-Data-Age":{"schema":{"type":"integer","description":"Seconds since data was cached"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"source":{"type":"string","example":"FRED (Federal Reserve Economic Data)"},"snapshots":{"type":"array","items":{"type":"object","properties":{"record_date":{"type":"string","format":"date"},"rates":{"type":"object","properties":{"1_MONTH":{"type":"number"},"3_MONTH":{"type":"number"},"6_MONTH":{"type":"number"},"1_YEAR":{"type":"number"},"2_YEAR":{"type":"number"},"3_YEAR":{"type":"number"},"5_YEAR":{"type":"number"},"7_YEAR":{"type":"number"},"10_YEAR":{"type":"number"},"20_YEAR":{"type":"number"},"30_YEAR":{"type":"number"}}}}}}}},"provenance":{"$ref":"#/components/schemas/Provenance"}}}}}},"400":{"description":"Invalid date range","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_PARAMS","RANGE_TOO_LARGE","INVALID_RANGE"]},"message":{"type":"string"}}}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"description":"No data available for date range"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/treasury/auction-results/recent":{"get":{"summary":"Recent Treasury auction results","description":"Returns recent auction results using HQM (High Quality Market Corporate Bond) yields as proxy.\nIncludes last 10 observations for 1Y, 5Y, 10Y, 20Y, 30Y maturities.\n\n**Price:** $0.02\n\n**Note:** Uses FRED HQM series as proxy for actual auction data.\n","operationId":"getTreasuryAuctions","x-payment-info":{"pricingMode":"fixed","price":"0.020000","protocols":["x402","mpp"]},"tags":["Treasury"],"security":[{"x402PaymentSignature":[]}],"responses":{"200":{"description":"Recent auction results","headers":{"X-Mercury-Price":{"schema":{"type":"string","example":"$0.02"}},"X-Data-Age":{"schema":{"type":"integer","description":"Seconds since data was cached"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"source":{"type":"string","example":"FRED/HQM"},"note":{"type":"string","example":"Corporate bond yield proxy (High Quality Market rates)"},"auctions":{"type":"array","items":{"type":"object","properties":{"maturity":{"type":"string","example":"10Y"},"label":{"type":"string","example":"10-Year"},"recent_yields":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"yield":{"type":"number"},"maturity":{"type":"string"}}}}}}}}},"provenance":{"$ref":"#/components/schemas/Provenance"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"description":"No auction data available"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/treasury/tips-rates/current":{"get":{"summary":"Current TIPS rates","description":"Returns current Treasury Inflation-Protected Securities (TIPS) yields for all available maturities.\n\n**Price:** $0.02\n\n**Maturities:**\n- 5-Year (DFII5)\n- 7-Year (DFII7)\n- 10-Year (DFII10)\n- 20-Year (DFII20)\n- 30-Year (DFII30)\n","operationId":"getTreasuryTIPS","x-payment-info":{"pricingMode":"fixed","price":"0.020000","protocols":["x402","mpp"]},"tags":["Treasury"],"security":[{"x402PaymentSignature":[]}],"responses":{"200":{"description":"Current TIPS rates","headers":{"X-Mercury-Price":{"schema":{"type":"string","example":"$0.02"}},"X-Data-Age":{"schema":{"type":"integer","description":"Seconds since data was cached"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"record_date":{"type":"string","format":"date"},"rates":{"type":"object","properties":{"5_YEAR":{"type":"number"},"7_YEAR":{"type":"number"},"10_YEAR":{"type":"number"},"20_YEAR":{"type":"number"},"30_YEAR":{"type":"number"}}},"source":{"type":"string","example":"FRED (Federal Reserve Economic Data)"},"note":{"type":"string","example":"Treasury Inflation-Protected Securities (TIPS) yields"}}},"provenance":{"$ref":"#/components/schemas/Provenance"}}}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"description":"No TIPS rates available"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/.well-known/x402":{"get":{"summary":"x402 protocol discovery document","description":"Returns x402 protocol configuration including:\n- Supported payment schemes (exact)\n- Network (Base mainnet - eip155:8453)\n- Asset (USDC - 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)\n- Merchant wallet (payTo address)\n- Endpoint pricing and descriptions\n\nUsed by x402-compatible clients for automatic payment setup.\n","operationId":"getX402Discovery","tags":["Discovery"],"security":[],"responses":{"200":{"description":"x402 discovery document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Discovery"}}}}}}},"/health":{"get":{"summary":"Service health check","description":"Returns service health status and configuration.\n\n**Fields:**\n- status: \"healthy\" or \"degraded\"\n- timestamp: current server time\n- version: service version\n- signing_address: ECDSA wallet for provenance signatures\n- fred_configured: whether FRED API key is set\n","operationId":"getHealth","tags":["Discovery"],"security":[],"responses":{"200":{"description":"Health status","content":{"application/json":{"schema":{"type":"object","required":["status","timestamp","version"],"properties":{"status":{"type":"string","enum":["healthy","degraded"],"example":"healthy"},"timestamp":{"type":"string","format":"date-time"},"version":{"type":"string","example":"1.0.0"},"signing_address":{"type":"string","nullable":true,"example":"0xe76795db4100E10374d19E91742A392C658f3a43"},"fred_configured":{"type":"boolean"}}}}}}}}},"/":{"get":{"summary":"Landing page or JSON manifest","description":"Returns landing page HTML (if browser) or JSON manifest (if API client).\nContent-Type negotiation via Accept header.\n","operationId":"getRoot","tags":["Documentation"],"security":[],"responses":{"200":{"description":"Landing page or manifest","content":{"text/html":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Mercury x402"},"tagline":{"type":"string"},"version":{"type":"string"},"endpoints":{"type":"object"}}}}}}}}},"/docs":{"get":{"summary":"Quickstart documentation","operationId":"getDocs","tags":["Documentation"],"security":[],"responses":{"200":{"description":"HTML documentation","content":{"text/html":{"schema":{"type":"string"}}}}}}}},"components":{"securitySchemes":{"x402PaymentSignature":{"type":"apiKey","in":"header","name":"payment-signature","description":"Production Mercury expects an x402 payment payload in the `payment-signature` header.\n\n**Format:** `payment-signature: <base64_x402_payment_payload>`\n\n**How to pay:**\n1. Call any paid endpoint without payment headers\n2. Read the `Payment-Required` header (base64url x402 descriptor)\n3. Use an x402-compatible client or payment processor to create a signed payment payload\n4. Retry the request with `payment-signature`\n\n**Legacy bearer compatibility:**\nUnsigned `Authorization: Bearer x402_<token>` flow is disabled in production unless `ALLOW_LEGACY_BEARER=true`.\n"}},"schemas":{"FREDResponse":{"type":"object","required":["data","provenance"],"properties":{"data":{"type":"object","required":["series_id","observations"],"properties":{"series_id":{"type":"string","example":"UNRATE"},"title":{"type":"string","example":"Unemployment Rate"},"units":{"type":"string","example":"Percent"},"frequency":{"type":"string","example":"Monthly"},"seasonal_adjustment":{"type":"string","example":"Seasonally Adjusted"},"last_updated":{"type":"string","format":"date-time"},"observation_count":{"type":"integer","example":1},"observations":{"type":"array","items":{"type":"object","required":["date","value"],"properties":{"date":{"type":"string","format":"date"},"value":{"oneOf":[{"type":"string"},{"type":"null"}],"description":"FRED returns \".\" for missing values (converted to null)","example":"4.0"}}}}}},"provenance":{"$ref":"#/components/schemas/Provenance"}}},"Indicator":{"type":"object","required":["value","date","unit"],"properties":{"value":{"type":"number","example":4.3},"date":{"type":"string","format":"date","example":"2026-01-01"},"unit":{"type":"string","example":"Percent"}}},"TreasuryResponseV1":{"type":"object","required":["data","provenance"],"properties":{"data":{"type":"object","required":["record_date","rates"],"properties":{"record_date":{"type":"string","format":"date"},"rates":{"type":"object","properties":{"1_MONTH":{"type":"number","format":"float"},"3_MONTH":{"type":"number"},"6_MONTH":{"type":"number"},"1_YEAR":{"type":"number"},"2_YEAR":{"type":"number"},"3_YEAR":{"type":"number"},"5_YEAR":{"type":"number"},"7_YEAR":{"type":"number"},"10_YEAR":{"type":"number"},"20_YEAR":{"type":"number"},"30_YEAR":{"type":"number"}},"additionalProperties":false}}},"provenance":{"allOf":[{"$ref":"#/components/schemas/Provenance"},{"type":"object","properties":{"series_coverage":{"type":"string","example":"11/11 maturities"},"cache_until":{"type":"string","format":"date-time"}}}]}}},"TreasuryResponseV0_9":{"type":"object","required":["record_date","rates"],"properties":{"record_date":{"type":"string","format":"date"},"rates":{"type":"object","additionalProperties":{"type":"number"}}}},"CompositeResponse":{"type":"object","required":["data","provenance"],"properties":{"data":{"type":"object","required":["dashboard","timestamp","indicators"],"properties":{"dashboard":{"type":"string","enum":["economic-overview","inflation-tracker","labor-market"]},"timestamp":{"type":"string","format":"date-time"},"indicators":{"type":"array","items":{"type":"object","required":["series_id","value","date"],"properties":{"series_id":{"type":"string"},"title":{"type":"string"},"value":{"oneOf":[{"type":"string"},{"type":"null"}]},"date":{"type":"string","format":"date"},"units":{"type":"string"}}}}}},"provenance":{"$ref":"#/components/schemas/Provenance"}}},"Provenance":{"type":"object","required":["source","source_url","fetched_at","mercury_version","deterministic"],"properties":{"source":{"type":"string","example":"Federal Reserve Economic Data (FRED)"},"source_url":{"type":"string","format":"uri"},"fetched_at":{"type":"string","format":"date-time"},"mercury_version":{"type":"string","example":"v1.0"},"deterministic":{"type":"boolean","description":"Whether this response is deterministic/reproducible"},"signature":{"type":"string","nullable":true,"description":"ECDSA signature of canonical data (hex, with 0x prefix). Optional - only present if signing wallet is configured.","pattern":"^0x[a-fA-F0-9]+$"},"requested_date":{"type":"string","format":"date","description":"Present if date query param was used"},"observation_start":{"type":"string","format":"date","description":"Present if observation_start query param was used"},"observation_end":{"type":"string","format":"date","description":"Present if observation_end query param was used"}}},"X402Discovery":{"type":"object","required":["x402Version","accepts"],"properties":{"x402Version":{"type":"integer","example":2},"accepts":{"type":"array","items":{"type":"object","required":["scheme","network","amount","payTo","maxTimeoutSeconds","asset"],"properties":{"scheme":{"type":"string","enum":["exact"]},"network":{"type":"string","example":"eip155:8453","description":"Base mainnet"},"amount":{"type":"string","example":"150000","description":"Amount in wei (USDC has 6 decimals)"},"payTo":{"type":"string","example":"0xF8d59270cBC746a7593D25b6569812eF1681C6D2","description":"Merchant wallet address"},"maxTimeoutSeconds":{"type":"integer","example":30},"asset":{"type":"string","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"USDC contract address on Base"},"extra":{"type":"object","properties":{"endpoints":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"price":{"type":"number"},"description":{"type":"string"}}}}}}}}},"extensions":{"type":"object","description":"Optional x402 protocol extensions"}}},"PaymentRequired":{"type":"object","required":["x402Version","error","accepts"],"properties":{"x402Version":{"type":"integer","example":1},"error":{"type":"string","enum":["payment required"]},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"base"},"maxAmountRequired":{"type":"string","example":"50000"},"payTo":{"type":"string","example":"0xF8d59270cBC746a7593D25b6569812eF1681C6D2"},"asset":{"type":"string","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},"maxTimeoutSeconds":{"type":"integer","example":30}}}},"status":{"type":"string","description":"Additional status info (present for PAYMENT_VERIFICATION_UNAVAILABLE)"}}}},"responses":{"PaymentRequired":{"description":"Payment required via x402","headers":{"Payment-Required":{"schema":{"type":"string"},"description":"Base64url-encoded x402 payment descriptor"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"},"example":{"x402Version":1,"error":"payment required","accepts":[{"scheme":"exact","network":"base","maxAmountRequired":"50000","payTo":"0xF8d59270cBC746a7593D25b6569812eF1681C6D2","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","maxTimeoutSeconds":30}]}}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"INTERNAL_ERROR"},"message":{"type":"string"}}}}}}}},"ServiceUnavailable":{"description":"Service configuration issue (e.g., missing API key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"SERVICE_UNAVAILABLE"},"message":{"type":"string","example":"FRED API key not configured"}}}}}}}}}}}