{"openapi":"3.1.0","info":{"title":"x402-finance-api","version":"1.0.0","description":"Pay-per-call financial intelligence API - 21 endpoints across crypto, stocks, forex, AI analysis, insider trading, and pharma catalysts.","x-logo":{"url":"https://x402-finance-api.vercel.app/logo.png","altText":"x402-finance-api"},"x-guidance":"Pay-per-call API using x402 protocol v2. Use wrapFetchWithPayment from @x402/fetch to pay automatically. Payments in USDC on Base mainnet. All endpoints use POST with JSON body. Coin IDs follow CoinGecko format: bitcoin, ethereum, solana. Stock tickers: AAPL, TSLA, NVDA. Currency codes ISO 4217: USD, EUR, IRR, RUB, CNY, JPY, INR. GET /health (free) verifies the server. GET /openapi.json (free) returns this spec."},"paths":{"/price":{"post":{"summary":"Real-time coin price in 10 currencies including IRR, RUB, INR","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"coin":{"type":"string","description":"CoinGecko coin ID (e.g. bitcoin)","example":"bitcoin"}},"required":["coin"]}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"coin":{"type":"string"},"usd":{"type":"number"},"eur":{"type":"number"},"gbp":{"type":"number"},"jpy":{"type":"number"},"cny":{"type":"number"},"rub":{"type":"number"},"inr":{"type":"number"},"irr":{"type":"number"},"btc":{"type":"number"},"eth":{"type":"number"},"usd_market_cap":{"type":"number"},"usd_24h_change":{"type":"number"}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/market":{"post":{"summary":"Full market data: supply, ATH, price change 24h/7d/30d, market cap rank","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"coin":{"type":"string","description":"CoinGecko coin ID","example":"ethereum"}},"required":["coin"]}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.01"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"symbol":{"type":"string"},"description":{"type":"string"},"market_cap_usd":{"type":"number"},"ath_usd":{"type":"number"},"price_change_24h_pct":{"type":"number"}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/trending":{"post":{"summary":"Top 10 trending coins on CoinGecko right now","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.01"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"trending":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"number"},"id":{"type":"string"},"name":{"type":"string"},"symbol":{"type":"string"},"price_usd":{"type":"number"}}}},"updated_at":{"type":"string"}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/indicators":{"post":{"summary":"[EXPERIMENTAL] Technical indicators: RSI, EMA20/50/200, MACD, ADX, Bollinger Bands. Note: EMA200 may be null for coins not mapped to Binance; 1h interval returns 4h granularity due to CoinGecko free-tier limits.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"coin":{"type":"string","description":"CoinGecko coin ID","example":"bitcoin"},"interval":{"type":"string","enum":["1d","4h","1h"],"default":"1d","description":"Candle interval"}},"required":["coin"]}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.003"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"rsi":{"type":"number"},"ema20":{"type":"number"},"ema50":{"type":"number"},"ema200":{"type":"number"},"macd":{"type":"number"},"macdSignal":{"type":"number"},"macdHistogram":{"type":"number"},"adx":{"type":"number"},"bbUpper":{"type":"number"},"bbMiddle":{"type":"number"},"bbLower":{"type":"number"}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/news":{"post":{"summary":"Latest crypto news headlines for an asset","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"coin":{"type":"string","description":"CoinGecko coin ID","example":"bitcoin"}},"required":["coin"]}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.004"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string"},"source":{"type":"string"},"publishedAt":{"type":"string"}}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/sentiment":{"post":{"summary":"Market sentiment score 0-100 (Fear & Greed index)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.002"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"score":{"type":"number"},"label":{"type":"string"},"source":{"type":"string"},"updated_at":{"type":"string"}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/signal":{"post":{"summary":"Confluence trading signal: BULLISH/BEARISH/NEUTRAL with confidence score","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"coin":{"type":"string","description":"CoinGecko coin ID","example":"bitcoin"},"price":{"type":"number","description":"Current price in USD (optional — auto-fetched from CoinGecko if omitted)","example":65000}},"required":["coin"]}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.015"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"direction":{"type":"string","enum":["BULLISH","BEARISH","NEUTRAL"]},"confidence":{"type":"number"},"score":{"type":"number"},"drivers":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/overview":{"post":{"summary":"Global crypto market: total market cap, BTC dominance, 24h volume","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.002"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"totalMarketCap":{"type":"number"},"totalVolume24h":{"type":"number"},"btcDominance":{"type":"number"},"activeCryptos":{"type":"number"},"marketCapChange24h":{"type":"number"}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/history":{"post":{"summary":"Daily OHLC price history for a coin: up to 365 days","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"coin":{"type":"string","description":"CoinGecko coin ID","example":"bitcoin"},"days":{"type":"number","default":30,"description":"Number of days (1-365)"},"currency":{"type":"string","default":"usd","description":"vs_currency: usd, eur, btc, etc."}},"required":["coin"]}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"coin":{"type":"string"},"days":{"type":"number"},"currency":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"price":{"type":"number"},"market_cap":{"type":"number"},"volume":{"type":"number"}}}}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/portfolio":{"post":{"summary":"[EXPERIMENTAL] Evaluate a multi-asset crypto portfolio with current value and 24h change. Holdings for unknown coin IDs will show price_usd: 0 and include a warning field.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assets":{"type":"array","description":"Array of { coin, amount } holdings","items":{"type":"object","properties":{"coin":{"type":"string","description":"CoinGecko coin ID"},"amount":{"type":"number","description":"Number of coins held"}},"required":["coin","amount"]},"example":[{"coin":"bitcoin","amount":0.5},{"coin":"ethereum","amount":2}]}},"required":["assets"]}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.01"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"total_usd":{"type":"number"},"total_btc":{"type":"number"},"asset_count":{"type":"number"},"evaluated_at":{"type":"string"},"holdings":{"type":"array","items":{"type":"object","properties":{"coin":{"type":"string"},"amount":{"type":"number"},"price_usd":{"type":"number"},"value_usd":{"type":"number"},"value_btc":{"type":"number"},"change_24h_pct":{"type":"number"},"warning":{"type":"string","description":"Present only if price was not found for this coin"}}}}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/report":{"post":{"summary":"AI-generated market analysis report - multi-source data + LLM narrative","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"coin":{"type":"string","description":"CoinGecko coin ID","example":"bitcoin"},"price":{"type":"number","description":"Current price hint (optional)","example":65000},"lang":{"type":"string","default":"en","description":"Report language: en, it, es, fr, de, pt, zh, ja, ar, ru"}},"required":["coin"]}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.025"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"report":{"type":"string"}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/stock/profile":{"post":{"summary":"[EXPERIMENTAL] Stock company profile: sector, industry, description, employees, website. Sourced from Yahoo Finance (informal API) with Alpha Vantage fallback.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ticker":{"type":"string","description":"Stock ticker symbol","example":"AAPL"}},"required":["ticker"]}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.004"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"sector":{"type":"string"},"industry":{"type":"string"},"description":{"type":"string"},"employees":{"type":"number"},"website":{"type":"string"},"country":{"type":"string"}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/stock/overview":{"post":{"summary":"[EXPERIMENTAL] Stock quote and key statistics: price, market cap, PE ratio, 52-week range. Sourced from Yahoo Finance (informal API) with Alpha Vantage fallback.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ticker":{"type":"string","description":"Stock ticker symbol","example":"TSLA"}},"required":["ticker"]}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"price":{"type":"number"},"change":{"type":"number"},"changePercent":{"type":"number"},"marketCap":{"type":"number"},"eps":{"type":"number"},"pe":{"type":"number"},"week52High":{"type":"number"},"week52Low":{"type":"number"}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/forex":{"post":{"summary":"Forex exchange rate between two currencies (200+ including IRR, RUB, CNY)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","description":"Source currency code (ISO 4217)","example":"USD"},"to":{"type":"string","description":"Target currency code (ISO 4217)","example":"EUR"}},"required":["from","to"]}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.002"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"rate":{"type":"number"},"source":{"type":"string"},"fetched_at":{"type":"string"}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/convert":{"post":{"summary":"Convert an amount between any two currencies (200+ including IRR, RUB, crypto)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","description":"Source currency","example":"USD"},"to":{"type":"string","description":"Target currency","example":"IRR"},"amount":{"type":"number","description":"Amount to convert","example":100}},"required":["from","to","amount"]}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.002"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"amount":{"type":"number"},"result":{"type":"number"},"rate":{"type":"number"},"source":{"type":"string"},"fetched_at":{"type":"string"}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/insider":{"post":{"summary":"[EXPERIMENTAL] Insider buy/sell transactions from SEC Form 4 filings. EDGAR parsing is unofficial; results depend on SEC response times.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ticker":{"type":"string","description":"Stock ticker symbol","example":"AAPL"},"days":{"type":"number","default":30,"description":"Lookback window in days (1-365)"}},"required":["ticker"]}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.015"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"insider":{"type":"string"},"role":{"type":"string"},"ticker":{"type":"string"},"type":{"type":"string","enum":["BUY","SELL","OTHER"]},"shares":{"type":"number"},"value":{"type":"number"},"date":{"type":"string"}}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/catalysts":{"post":{"summary":"[EXPERIMENTAL] Upcoming pharma/biotech FDA catalyst events from SEC 8-K filings. EDGAR 8-K parsing is brittle; results may be incomplete or delayed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"number","default":30,"description":"Lookahead window in days (1-180)"}}}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.008"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"company":{"type":"string"},"event":{"type":"string"},"date":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}}}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/snapshot/crypto":{"post":{"summary":"[EXPERIMENTAL] Aggregated crypto signals for BTC/ETH/SOL/BNB. Computed on-demand: first call after cold start may take 15-25s.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.003"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"assets":{"type":"array","items":{"type":"object"}},"updatedAt":{"type":"string"}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/snapshot/market":{"post":{"summary":"[EXPERIMENTAL] Aggregated stock overview for top 7 equities (AAPL, MSFT, NVDA, TSLA, GOOGL, AMZN, META). Computed on-demand; depends on Yahoo Finance informal API and Alpha Vantage free tier.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.003"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"stocks":{"type":"array","items":{"type":"object"}},"updatedAt":{"type":"string"}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/dominance":{"post":{"summary":"BTC/ETH/stablecoin dominance and global crypto market stats","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.002"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"btc_dominance":{"type":"number"},"eth_dominance":{"type":"number"},"stablecoin_dominance":{"type":"number"},"total_market_cap_usd":{"type":"number"},"total_volume_24h_usd":{"type":"number"},"active_cryptocurrencies":{"type":"number"},"market_cap_change_24h":{"type":"number"},"updated_at":{"type":"string"}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/dex/price":{"post":{"summary":"Real-time DEX price for any on-chain token by contract address (all major chains)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"Token contract address (0x...)","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},"chain":{"type":"string","description":"Chain filter: base, ethereum, arbitrum, bsc, polygon (optional)","example":"base"}},"required":["token"]}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"symbol":{"type":"string"},"name":{"type":"string"},"price_usd":{"type":"number"},"price_change_24h":{"type":"number"},"volume_24h_usd":{"type":"number"},"liquidity_usd":{"type":"number"},"chain":{"type":"string"},"dex":{"type":"string"},"pair_address":{"type":"string"},"fetched_at":{"type":"string"}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/broker/audit":{"post":{"summary":"AI broker statement audit: detect hidden fees, spreads, FX markups vs IB/Degiro","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"statementData":{"type":"string","description":"Raw broker statement text (max 10000 chars)"}},"required":["statementData"]}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.10"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"total_fees_usd":{"type":"number","description":"Total detected fees in USD"},"hidden_costs_percentage":{"type":"number","description":"% of trade value lost to hidden costs"},"comparison":{"type":"object","properties":{"current_cost_usd":{"type":"number"},"interactive_brokers_estimate_usd":{"type":"number"},"degiro_estimate_usd":{"type":"number"}}},"detected_transactions":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"asset":{"type":"string"},"type":{"type":"string","enum":["buy","sell","dividend","fee"]},"amount_usd":{"type":"number"},"explicit_fee_usd":{"type":"number"},"estimated_spread_usd":{"type":"number"},"fx_markup_usd":{"type":"number"},"red_flags":{"type":"array","items":{"type":"string"}}}}}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}},"/social/sentiment":{"post":{"summary":"AI sentiment analysis on social/news text: bullish/bearish score + investment signal","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ticker":{"type":"string","description":"Stock ticker or coin symbol","example":"AAPL"},"text":{"type":"string","description":"Text to analyze (max 20000 chars)"}},"required":["ticker","text"]}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.08"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ticker":{"type":"string"},"bullish_score":{"type":"number","description":"Bullish intensity 0-100"},"bearish_score":{"type":"number","description":"Bearish intensity 0-100"},"last_100_mentions_summary":{"type":"string"},"key_volatile_events":{"type":"array","items":{"type":"string"}},"investment_signal":{"type":"string","enum":["buy","sell","hold","strong_buy","strong_sell","neutral"]},"signal_confidence":{"type":"number","description":"Confidence score 0-100"}}}}}},"400":{"description":"Bad Request"},"402":{"description":"Payment Required"},"502":{"description":"Upstream error"}}}}}}