{ "answer": "Bitcoin rose 10% [1] after the SEC approved spot ETFs [2]...", "sources": [ { "title": "Bitcoin Surges Post-ETF", "source": "CoinDesk", "url": "..." } ], "confidence": { "overall": 0.87, "level": "high" }, "suggestedQuestions": [ { "question": "How did other cryptocurrencies react?", "type": "expansion" } ], "citations": { "claims": [{ "claim": "Bitcoin rose 10%", "sourceIndex": 1 }] } } ``` 📖 **Full RAG documentation:** [docs/RAG.md](docs/RAG.md) | **Roadmap:** [docs/RAG-ROADMAP.md](docs/RAG-ROADMAP.md) ### 📊 Analytics & Intelligence | Endpoint | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------ | | `/api/analytics/anomalies` | Detect unusual patterns (volume spikes/coordinated publishing/sentiment shifts/ticker surges/source outages) | | `/api/analytics/credibility` | Source credibility scoring with accuracy/timeliness metrics | | `/api/analytics/headlines` | Headline mutation tracking with sentiment shift detection | | `/api/analytics/causality` | Causal inference (Granger/diff-in-diff/event study methods) | | `/api/regulatory` | Multi-jurisdictional regulatory tracking (15 jurisdictions, 30+ agencies) | | `/api/influencers` | Influencer reliability scoring with accuracy rates | | `/api/predictions` | Prediction tracking with outcome resolution & leaderboards | | `/api/citations` | Academic citation network with bibliometric metrics | ### 🔗 Relationship & Entity Analysis | Endpoint | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/relationships` | Extract entity relationships (11 types: partnership/competition/investment/acquisition/collaboration/conflict/regulation/development/market_impact/mention/association) | | `/api/predictions` | Prediction registry with timestamped predictions & accuracy scoring | | `/api/onchain/events` | Link news to on-chain events | ### 💼 Portfolio Tools | Endpoint | Description | | ---------------------------- | ------------------------------------- | | `/api/portfolio` | Portfolio-based news + prices | | `/api/portfolio/performance` | Performance charts, P&L, risk metrics | | `/api/portfolio/tax` | Tax report generation (Form 8949) | ### � Research & Backtesting | Endpoint | Description | | ------------------------ | ---------------------------------------------- | | `/api/research/backtest` | Strategy backtesting with historical news data | | `/api/academic` | Academic access program registration | | `/api/citations` | Academic citation network analysis | | `/api/predictions` | Prediction tracking with accuracy scoring | **Backtest Example:** ```bash # Backtest a sentiment-based strategy curl -X POST "https://fcn.dev/api/research/backtest" \ -H "Content-Type: application/json" \ -d '{"strategy": "sentiment_momentum", "asset": "BTC", "period": "1y"}' ``` ### 📡 Social Monitoring | Endpoint | Description | | ------------------------------ | -------------------------------------------------- | | `/api/social/monitor` | Discord & Telegram channel monitoring via webhooks | | `/api/social/influencer-score` | Influencer reliability scoring | **Social Monitor Example:** ```bash # Ingest messages via webhook integration curl -X POST "https://fcn.dev/api/social/monitor" \ -H "Content-Type: application/json" \ -d '{"platform": "discord", "channel": "alpha-chat", "content": "BTC bullish"}' ``` ### 🗄️ Data Storage & Export | Endpoint | Description | | ------------------- | ------------------------------------------------ | | `/api/storage/cas` | Content-addressable storage (IPFS-style hashing) | | `/api/export` | Export data in CSV/JSON/Parquet formats | | `/api/exports` | Bulk export job management | | `/api/exports/[id]` | Download export file | ### �🔔 Real-Time & Infrastructure | Endpoint | Description | | --------------------------- | -------------------------------------------- | | `/api/sse` | Server-Sent Events for real-time news stream | | `/api/ws` | WebSocket connection info & SSE fallback | | `/api/webhooks` | Webhook registration & management | | `/api/push` | Web Push notification registration | | `/api/newsletter/subscribe` | Newsletter subscription | | `/api/alerts` | Price & news alerts | | `/api/cache` | Cache management | | `/api/views` | Article view tracking | | `/api/keys` | API key management | | `/api/gateway` | Unified API gateway | | `/api/billing` | Subscription & billing management | | `/api/billing/usage` | Current billing usage | | `/api/upgrade` | API key tier upgrades (x402) | | `/api/register` | User registration | **SSE Real-Time Stream:** ```javascript const events = new EventSource("/api/sse?sources=coindesk,theblock"); events.onmessage = (e) => console.log(JSON.parse(e.data)); ``` ### 🐦 Social Intelligence | Endpoint | Description | | ------------------------- | ---------------------------------------- | | `/api/social/discord` | Discord channel monitoring | | `/api/social/x/lists` | Manage X/Twitter influencer lists | | `/api/social/x/sentiment` | X sentiment from custom influencer lists | ### 🐦 X/Twitter Sentiment (No API Key!) Automated X/Twitter sentiment analysis without paid API: ```bash # Get sentiment from default crypto influencers curl https://fcn.dev/api/social/x/sentiment # Create custom influencer list curl -X POST https://fcn.dev/api/social/x/lists \ -H "Content-Type: application/json" \ -d '{ "name": "ETH Builders", "users": [ {"username": "VitalikButerin", "category": "founder", "weight": 0.9}, {"username": "sassal0x", "category": "influencer", "weight": 0.8} ] }' # Get sentiment from your list curl https://fcn.dev/api/social/x/sentiment?list=list_xxx ``` **Features:** - ✅ **No API key required** - Uses Nitter RSS feeds - ✅ **Automated cron** - Updates every 30 minutes - ✅ **Custom lists** - Track your own influencers - ✅ **AI analysis** - Groq-powered sentiment scoring - ✅ **Webhook alerts** - Discord/Slack/Telegram notifications ### 📈 Market Data | Endpoint | Description | | ------------------------------- | --------------------------------------------- | | `/api/market/coins` | List all coins with market data | | `/api/market/trending` | Trending cryptocurrencies | | `/api/market/categories` | Market categories | | `/api/market/exchanges` | Exchange listings | | `/api/market/search` | Search coins | | `/api/market/compare` | Compare multiple coins | | `/api/market/history/[coinId]` | Historical price data | | `/api/market/ohlc/[coinId]` | OHLC candlestick data | | `/api/market/snapshot/[coinId]` | Real-time coin snapshot | | `/api/market/social/[coinId]` | Social metrics for coin | | `/api/market/tickers/[coinId]` | Trading pairs for coin | | `/api/market/defi` | DeFi market overview | | `/api/market/derivatives` | Derivatives market data | | `/api/charts` | Chart data for visualizations | | `/api/fear-greed` | Crypto Fear & Greed Index with 30-day history | ### 🏗️ DeFi Tools | Endpoint | Description | | -------------------------------------------- | ------------------------------- | | `/api/defi` | DeFi news and protocol coverage | | `/api/defi/protocol-health` | Protocol health & risk scoring | | `/api/defi/protocol-health?action=ranking` | Protocol safety rankings | | `/api/defi/protocol-health?action=incidents` | Security incident tracker | **Protocol Health Example:** ```bash # Get AAVE v3 health score curl "https://fcn.dev/api/defi/protocol-health?protocol=aave-v3" # Get top lending protocols by safety curl "https://fcn.dev/api/defi/protocol-health?action=ranking&category=lending" # Get recent security incidents curl "https://fcn.dev/api/defi/protocol-health?action=incidents&limit=20" ``` ### 📺 Integrations | Endpoint | Description | | ------------------------------- | -------------------------------------------- | | `/api/integrations/tradingview` | TradingView widgets & Pine Script generation | | `/api/tradingview` | TradingView webhook receiver | **TradingView Example:** ```bash # Get chart widget embed code curl "https://fcn.dev/api/integrations/tradingview?action=widget&type=chart&symbol=BTC" # Generate Pine Script indicator curl "https://fcn.dev/api/integrations/tradingview?action=indicator&name=newsAlert" ``` ### 📊 Trading Tools | Endpoint | Description | | ------------------------ | ---------------------------------------------------------- | | `/api/arbitrage` | Cross-exchange arbitrage scanner with triangular arb | | `/api/trading/arbitrage` | Real-time arbitrage opportunities (spot + triangular) | | `/api/funding` | Funding rate dashboard (Binance, Bybit, OKX, Hyperliquid) | | `/api/options` | Options flow, volatility surface, max pain, gamma exposure | | `/api/trading/options` | Options dashboard from Deribit, OKX, Bybit | | `/api/liquidations` | Real-time liquidations feed (CoinGlass integration) | | `/api/orderbook` | Multi-exchange order book aggregation | | `/api/trading/orderbook` | Aggregated orderbook with slippage & liquidity analysis | **Supported Exchanges:** - **Arbitrage:** Binance, Bybit, OKX, Kraken, Coinbase, KuCoin - **Options:** Deribit, OKX, Bybit - **Order Book:** Binance, Bybit, OKX, Kraken, Coinbase (aggregated) - **Funding Rates:** Binance, Bybit, OKX, Hyperliquid **Arbitrage Features:** - Cross-exchange spot arbitrage - Triangular arbitrage detection - Real-time spread monitoring - Profit estimation with fees - Volume analysis **Options Analytics:** - Unusual options activity detection - Volatility surface visualization - Max pain analysis - Gamma exposure tracking - Block trade monitoring **Order Book Analysis:** - Multi-exchange aggregation - Slippage estimation for orders - Liquidity depth visualization - Order book imbalance detection - Support/resistance levels **Supported Exchanges:** - **Arbitrage:** Binance, Bybit, OKX, Kraken, Coinbase, KuCoin - **Options:** Deribit, OKX, Bybit - **Order Book:** Binance, Bybit, OKX, Kraken, Coinbase (aggregated) - **Funding Rates:** Binance, Bybit, OKX, Hyperliquid **Arbitrage Features:** - Cross-exchange spot arbitrage - Triangular arbitrage detection - Real-time spread monitoring - Profit estimation with fees - Volume analysis **Options Analytics:** - Unusual options activity detection - Volatility surface visualization - Max pain analysis - Gamma exposure tracking - Block trade monitoring **Order Book Analysis:** - Multi-exchange aggregation - Slippage estimation for orders - Liquidity depth visualization - Order book imbalance detection - Support/resistance levels **Arbitrage Scanner Example:** ```bash # Get cross-exchange arbitrage opportunities curl "https://fcn.dev/api/arbitrage?minProfit=0.5&limit=20" # Get triangular arbitrage opportunities curl "https://fcn.dev/api/trading/arbitrage?type=triangular&minSpread=0.3" ``` **Options Flow Example:** ```bash # Get options dashboard curl "https://fcn.dev/api/options?view=dashboard&underlying=BTC" # Get max pain analysis curl "https://fcn.dev/api/trading/options?view=maxpain&underlying=ETH" # Get volatility surface curl "https://fcn.dev/api/trading/options?view=surface" ``` **Order Book Example:** ```bash # Get aggregated order book curl "https://fcn.dev/api/orderbook?symbol=BTC&market=spot" # Estimate slippage for $100k order curl "https://fcn.dev/api/trading/orderbook?symbol=BTCUSDT&view=slippage&size=100000" ``` ### 🐋 Whale Intelligence | Endpoint | Description | | ------------------- | ---------------------------------------------------- | | `/api/whale-alerts` | Monitor large transactions across blockchains | | `/api/influencers` | Influencer reliability tracking & prediction scoring | **Whale Alerts Example:** ```bash # Get recent whale transactions curl "https://fcn.dev/api/whale-alerts?limit=50" # Filter by blockchain curl "https://fcn.dev/api/whale-alerts?blockchain=ethereum&minUsd=1000000" ``` ### 🏛️ Regulatory Intelligence | Endpoint | Description | | -------------------------------------- | --------------------------------------------------- | | `/api/regulatory` | Regulatory news with jurisdiction & agency tracking | | `/api/regulatory?action=jurisdictions` | Jurisdiction profiles | | `/api/regulatory?action=agencies` | Agency information | | `/api/regulatory?action=deadlines` | Upcoming compliance deadlines | | `/api/regulatory?action=summary` | Intelligence summary | ### 📰 Coverage & Research | Endpoint | Description | | ------------------- | --------------------------------------------- | | `/api/coverage-gap` | Analyze under-covered topics and assets | | `/api/extract` | Full article content extraction from URLs | | `/api/academic` | Academic access program for researchers | | `/api/citations` | Citation network analysis for academic papers | ### 💎 Premium API (x402 Micropayments) Premium endpoints powered by x402 USDC micropayments. Pay per request or get access passes. | Endpoint | Description | Price | | ---------------------------------- | ----------------------------------- | ----- | | `/api/premium` | Premium API documentation & pricing | Free | | `/api/premium/ai/sentiment` | Advanced AI sentiment analysis | $0.02 | | `/api/premium/ai/analyze` | Deep article analysis | $0.03 | | `/api/premium/ai/signals` | Premium trading signals | $0.05 | | `/api/premium/ai/summary` | Extended summaries | $0.02 | | `/api/premium/ai/compare` | Multi-asset AI comparison | $0.03 | | `/api/premium/whales/alerts` | Real-time whale alerts | $0.05 | | `/api/premium/whales/transactions` | Whale transaction history | $0.03 | | `/api/premium/smart-money` | Smart money flow tracking | $0.05 | | `/api/premium/screener/advanced` | Advanced coin screener | $0.03 | | `/api/premium/analytics/screener` | Analytics screener | $0.03 | | `/api/premium/market/coins` | Premium market data | $0.02 | | `/api/premium/market/history` | Extended price history | $0.02 | | `/api/premium/defi/protocols` | DeFi protocol analytics | $0.03 | | `/api/premium/streams/prices` | Real-time price streams | $0.01 | | `/api/premium/portfolio/analytics` | Portfolio analytics | $0.03 | | `/api/premium/export/portfolio` | Portfolio data export | $0.05 | | `/api/premium/alerts/whales` | Whale alert configuration | $0.02 | | `/api/premium/alerts/custom` | Custom alert rules | $0.02 | | `/api/premium/api-keys` | API key management | Free | **Access Passes:** | Pass | Price | Duration | |------|-------|----------| | 1 Hour Pass | $0.25 | 1 hour | | 24 Hour Pass | $2.00 | 24 hours | | Weekly Pass | $10.00 | 7 days | **How to Pay:** ```bash # 1. Make request, receive 402 with payment requirements curl https://fcn.dev/api/premium/ai/sentiment # 2. Pay with USDC using x402-compatible wallet # 3. Include payment proof in header curl -H "X-Payment: " https://fcn.dev/api/premium/ai/sentiment ``` ### 🔐 Admin API ### 🔢 Versioned API (v1) Stable versioned API with x402 micropayment support for production integrations. | Endpoint | Description | | ---------------------------------- | ------------------------------ | | `/api/v1` | API documentation & pricing | | `/api/v1/coins` | Coin listings with market data | | `/api/v1/coin/[coinId]` | Individual coin details | | `/api/v1/market-data` | Global market data | | `/api/v1/trending` | Trending coins | | `/api/v1/search` | Search coins | | `/api/v1/exchanges` | Exchange listings | | `/api/v1/defi` | DeFi protocols data | | `/api/v1/gas` | Gas price tracker | | `/api/v1/global` | Global crypto market stats | | `/api/v1/assets` | Asset listings | | `/api/v1/assets/[assetId]/history` | Asset price history | | `/api/v1/historical/[coinId]` | Historical data | | `/api/v1/alerts` | Price alerts | | `/api/v1/export` | Data export | | `/api/v1/usage` | API usage stats | | `/api/v1/x402` | x402 payment info | > 💡 AI endpoints require `GROQ_API_KEY` (free at [console.groq.com](https://console.groq.com/keys)) --- ## 🖥️ Web App Pages The web app includes **95+ pages** for market data, portfolio management, AI tools, and more: **Page Breakdown:** 52 server components + 43 client components across 14 major categories. ### Market Data | Page | Description | | -------------------- | ------------------------------------------------- | | `/markets` | Market overview with global stats and coin tables | | `/markets/gainers` | 🆕 Top gaining coins (24h) | | `/markets/losers` | 🆕 Top losing coins (24h) | | `/markets/trending` | 🆕 Trending coins by volume & social | | `/markets/new` | 🆕 Newly listed cryptocurrencies | | `/markets/exchanges` | 🆕 Exchange directory with volumes | | `/trending` | Trending cryptocurrencies | | `/movers` | Top gainers and losers (24h) | ### Market Tools | Page | Description | | --------------- | ---------------------------------------- | | `/calculator` | Crypto calculator with conversion & P/L | | `/gas` | Ethereum gas tracker with cost estimates | | `/heatmap` | Market heatmap visualization | | `/screener` | Advanced coin screener with filters | | `/correlation` | Price correlation matrix (7/30/90 days) | | `/dominance` | Market cap dominance chart | | `/liquidations` | Real-time liquidations feed | | `/buzz` | Social buzz & trending sentiment | | `/charts` | TradingView-style charts | ### Trading Tools | Page | Description | | ------------ | ---------------------------------- | | `/arbitrage` | Cross-exchange arbitrage scanner | | `/options` | Options flow & analytics dashboard | | `/orderbook` | Multi-exchange order book view | ### Coin Details | Page | Description | | ---------------- | ------------------------------------------------ | | `/coin/[coinId]` | Comprehensive coin page with charts, stats, news | | `/compare` | Compare multiple cryptocurrencies side-by-side | ### AI & Analytics | Page | Description | | ---------------------- | --------------------------------- | | `/ai/oracle` | The Oracle - AI crypto assistant | | `/ai/brief` | AI-generated market brief | | `/ai/debate` | AI Bull vs Bear debate generator | | `/ai/counter` | AI counter-argument generator | | `/sentiment` | Sentiment analysis dashboard | | `/analytics` | News analytics overview | | `/analytics/headlines` | 🆕 Headline tracking & mutations | | `/predictions` | Prediction tracking & leaderboard | | `/digest` | AI-generated daily digest | ### Social & Influencers | Page | Description | | -------------- | ---------------------------------- | | `/influencers` | Influencer reliability leaderboard | | `/whales` | Whale alerts & tracking | | `/buzz` | Social buzz & trending sentiment | ### Research & Intelligence | Page | Description | | ------------------ | --------------------------------- | | `/regulatory` | Regulatory intelligence dashboard | | `/coverage-gap` | Coverage gap analysis | | `/protocol-health` | DeFi protocol health monitor | ### User Features | Page | Description | | ------------ | ------------------------------------------- | | `/portfolio` | Portfolio management with holdings tracking | | `/watchlist` | Watchlist with price alerts | | `/bookmarks` | 🆕 Saved articles & reading list | | `/settings` | User preferences and notifications | | `/install` | 🆕 PWA installation guide | ### Content | Page | Description | | ---------------------- | ------------------------------- | | `/search` | Search news articles | | `/topic/[topic]` | Topic-specific news | | `/topics` | Browse all topics | | `/source/[source]` | Source-specific news | | `/sources` | All news sources | | `/category/[category]` | Category-specific news | | `/article/[id]` | Individual article view | | `/read/[id]` | 🆕 Distraction-free reader mode | | `/share/[id]` | 🆕 Share & embed articles | | `/defi` | DeFi news section | | `/blog` | Blog posts | ### Administration | Page | Description | | ------------- | --------------------------------- | | `/billing` | Billing & subscription management | | `/pricing` | Pricing plans | | `/developers` | Developer documentation | --- ## SDKs & Components ### 📊 Component & Library Overview **Total Components:** 185+ React components organized in 10 directories **Total Library Functions:** 298+ exported functions across 90+ library files **Custom Hooks:** 5 React hooks for state management **Component Distribution:** - Root Level: 133 components (~65 Client, ~68 Server) - cards/: 10 article display variants - charts/: 4 TradingView integrations - portfolio/: 7 portfolio management components - watchlist/: 4 watchlist features - alerts/: 4 price alert components - billing/: 3 subscription management - sidebar/: 4 sidebar widgets **Library Categories:** - AI/ML: 12 files, 45 functions (sentiment, summarization, NER, signals) - Market Data: 10 files, 60 functions (prices, OHLC, exchanges, DeFi) - Social Intelligence: 3 files, 20 functions (Twitter, Discord, Telegram) - Analytics: 10 files, 40 functions (backtesting, predictions, anomalies) - Database: 2 files, 25 functions (storage abstraction, CAS) - Auth & Security: 4 files, 15 functions (API keys, rate limiting) - x402 Payments: 9 files, 35 functions (payment protocol, verification) - Utilities: 12 files, 50 functions (validation, logging, translation) ### 📦 Official SDKs | Package | Description | Version | | ----------------------------------- | --------------------------------------- | ------- | | [React](sdk/react/) | `` drop-in components | v0.1.0 | | [TypeScript](sdk/typescript/) | Full TypeScript SDK with type safety | v0.1.0 | | [Python](sdk/python/) | Zero-dependency Python client | v0.1.0 | | [JavaScript](sdk/javascript/) | Browser & Node.js SDK | v0.1.0 | | [Go](sdk/go/) | Go client library | v0.1.0 | | [PHP](sdk/php/) | PHP SDK | v0.1.0 | | [Ruby](sdk/ruby/) | Ruby gem with async support | v0.2.0 | | [Rust](sdk/rust/) | Rust crate with async/sync clients | v0.2.0 | | [UI Components](docs/components.md) | Internal navigation & search components | - | ### 🔌 Platform Integrations **Total Integrations:** 8 official SDKs + 5 platform integrations + 200+ code examples | Integration | Description | Documentation | Status | | ------------------------------ | ----------------------------------------- | --------------------------------------- | --------------- | | [ChatGPT](chatgpt/) | Custom GPT with OpenAPI schema | [Guide](docs/integrations/chatgpt.md) | ✅ Production | | [MCP Server](mcp/) | Model Context Protocol (stdio + HTTP/SSE) | [Guide](docs/integrations/mcp.md) | ✅ Production | | [Chrome Extension](extension/) | Browser extension (Manifest V3) | [Guide](docs/integrations/extension.md) | ✅ Chrome Ready | | [Alfred Workflow](alfred/) | macOS Alfred 4+ integration | [Guide](docs/integrations/alfred.md) | ✅ Production | | [Raycast](raycast/) | Raycast extension (6 commands) | [Guide](docs/integrations/raycast.md) | ✅ Production | | [Widgets](widget/) | 3 embeddable widget types | [Guide](docs/integrations/widgets.md) | ✅ Production | | [CLI](cli/) | Command-line interface | [README](cli/README.md) | ✅ Production | | [Postman](postman/) | Postman collection (182 endpoints) | [README](postman/README.md) | ✅ Complete | **Widget Types:** | Widget | Type | Use Case | | ----------- | ---------- | ----------------------- | | Main Widget | iframe | Full news feed embed | | Ticker | JavaScript | Scrolling header ticker | | Carousel | JavaScript | Featured news rotator | ### 📡 Nostr Integration Decentralized news distribution via the Nostr protocol (NIP-23 long-form content): ```bash # Publish latest news to Nostr relays curl -X POST https://cryptocurrency.cv/api/nostr \ -H "Content-Type: application/json" \ -d '{"action": "publish", "limit": 10}' # Get Nostr event IDs for published articles curl https://cryptocurrency.cv/api/nostr?action=events ``` Articles are published as NIP-23 long-form events to configured Nostr relays, enabling censorship-resistant news distribution. ### 🧩 Knowledge Graph API Explore entity relationships across the crypto news landscape: ```bash # Get entity graph for Bitcoin curl "https://cryptocurrency.cv/api/knowledge-graph?entity=Bitcoin&depth=2" # Filter by relationship type curl "https://cryptocurrency.cv/api/knowledge-graph?entity=Ethereum&type=partnership" # Get full graph snapshot curl "https://cryptocurrency.cv/api/knowledge-graph?action=snapshot" ``` Returns entities (people, companies, protocols, exchanges) and their relationships (partnerships, investments, acquisitions, competitions) as a traversable graph. ### 🎙️ AI Podcast Generation Generate AI-narrated crypto news podcasts on demand: ```bash # Generate flash briefing (2 min) curl "https://cryptocurrency.cv/api/podcast?format=flash" # Deep-dive analysis (10 min) curl "https://cryptocurrency.cv/api/podcast?format=deep-dive&topic=BTC" # Market open briefing curl "https://cryptocurrency.cv/api/podcast?format=market-open" # Weekly recap curl "https://cryptocurrency.cv/api/podcast?format=weekly-recap" # Subscribe via podcast RSS curl "https://cryptocurrency.cv/api/podcast/feed" ``` **Formats:** `flash` (2 min), `deep-dive` (10 min), `market-open` (5 min), `weekly-recap` (15 min) **Voices:** 3 voice options (professional, casual, technical) ### 🗣️ Alexa Skill Voice-activated crypto news for Amazon Echo devices: > "Alexa, ask Crypto News for the latest headlines" > "Alexa, ask Crypto News about Bitcoin" > "Alexa, ask Crypto News for DeFi updates" ```bash # Alexa skill handler curl -X POST https://cryptocurrency.cv/api/alexa \ -H "Content-Type: application/json" \ -d '{"request": {"type": "IntentRequest", "intent": {"name": "GetNewsIntent"}}}' ``` ### 🖼️ Farcaster Frames Interactive news frames for Warpcast and Farcaster clients: ```bash # Get interactive news frame curl "https://cryptocurrency.cv/api/frames" # Frame with specific topic curl "https://cryptocurrency.cv/api/frames?topic=bitcoin" ``` Frames support inline article previews, sentiment badges, and action buttons directly within the Farcaster social feed. ### 🔍 Vector Search Semantic search across the article archive using vector embeddings: ```bash # Semantic search (finds conceptually similar articles) curl "https://cryptocurrency.cv/api/vector-search?q=institutional+adoption+impact+on+market" # With filters curl "https://cryptocurrency.cv/api/vector-search?q=defi+security+vulnerabilities&source=coindesk&limit=20" ``` ### 🔬 Anomaly Detection Advanced anomaly detection across the news landscape: ```bash # Detect all anomalies curl "https://cryptocurrency.cv/api/anomalies" # Specific anomaly types curl "https://cryptocurrency.cv/api/anomalies?type=sentiment-acceleration" curl "https://cryptocurrency.cv/api/anomalies?type=price-narrative-divergence" curl "https://cryptocurrency.cv/api/anomalies?type=news-velocity" ``` **Anomaly Types:** - **News Velocity** — Unusual spike in article volume for a topic - **Sentiment Acceleration** — Rapid sentiment shifts in short timeframes - **Price-Narrative Divergence** — When news sentiment diverges from price action - **Coordinated Publishing** — Multiple sources publishing similar content simultaneously - **Source Outage** — Expected source goes silent ### 🎮 Gaming & Chain-Specific APIs | Endpoint | Description | |----------|-------------| | `/api/gaming` | Blockchain gaming market data with chain breakdown | | `/api/sui` | Sui blockchain data (balances, objects, transactions) | | `/api/aptos` | Aptos blockchain data (events, resources, transactions) | | `/api/hyperliquid` | Hyperliquid DEX trading data | ### 🎓 Academic Research Portal Full-featured academic access program for researchers and institutions: ```bash # Register institution curl -X POST https://cryptocurrency.cv/api/academic \ -H "Content-Type: application/json" \ -d '{ "institution": "MIT Media Lab", "email": "researcher@mit.edu", "purpose": "Crypto market microstructure research", "irb_approval": "IRB-2026-0142" }' # Add co-investigators curl -X POST https://cryptocurrency.cv/api/academic \ -H "Content-Type: application/json" \ -d '{"action": "add_investigator", "email": "postdoc@mit.edu", "role": "co-pi"}' ``` **Benefits:** Unlimited API access, historical data exports, citation network access, priority support, co-investigator management, IRB approval tracking. --- ### 🤖 AI Agent Skills 7 pre-built AI agent skills following the [agentskills.io](https://agentskills.io) standard, compatible with **Claude Code** and **Codex**: | Skill | Description | |-------|-------------| | `crypto-news-briefing` | Generate comprehensive news briefings | | `market-sentiment` | Analyze market sentiment across sources | | `coin-research` | Deep-dive research on any cryptocurrency | | `rug-pull-news-check` | Scan news for rug pull warning signs | | `historical-trend-analysis` | Analyze historical news trends | | `scale-to-1m` | Scale the system to 1M+ requests/day | | `add-data-sources` | Add new RSS/API data sources | Skills are located in [`/skills/`](./skills/) and can be loaded by AI coding agents for autonomous development tasks. ### 🖥️ GitHub Copilot Extension Crypto news directly in your VS Code editor via Copilot Chat: ``` @crypto-news /breaking — Breaking crypto news @crypto-news /market — Market overview @crypto-news /prices — Top coin prices @crypto-news /feargreed — Fear & Greed Index @crypto-news /whale — Recent whale alerts @crypto-news /trending — Trending topics ``` Also supports natural language queries: *"@crypto-news What's happening with Ethereum?"* Install from the VS Code Marketplace or build from source: [`/copilot-extension/`](./copilot-extension/) ### 🖥️ Terminal Dashboard Full-screen terminal dashboard with real-time news updates: ```bash # Launch terminal dashboard node terminal/dashboard.js # With custom API URL API_URL=http://localhost:3000 node terminal/dashboard.js ``` **Features:** - Real-time SSE streaming updates - ASCII art dashboard layout with blessed UI - Keyboard shortcuts for navigation and filtering - Multiple view modes (all news, breaking only, by source) - Works over SSH — perfect for headless servers See [`/terminal/`](./terminal/) for details. --- ### 🧠 RAG AI System Production-grade **Retrieval-Augmented Generation** for intelligent crypto news Q&A. | Feature | Description | |---------|-------------| | **Hybrid Search** | BM25 + semantic search with reciprocal rank fusion | | **Multi-hop Reasoning** | Agentic RAG for complex questions requiring multiple articles | | **Conversation Memory** | Multi-turn chat with context tracking | | **Advanced Reranking** | LLM scoring, time decay, source credibility, MMR diversity | | **Query Understanding** | Intent classification, decomposition, HyDE | | **Streaming API** | Real-time SSE responses with step-by-step updates | **Quick Start:** ```typescript import { ragService } from '@/lib/rag'; // Simple question answering const response = await ragService.ask("What happened to Bitcoin last week?"); console.log(response.answer); // Multi-hop reasoning for complex questions const reasoning = await ragService.askWithReasoning( "How did the ETF approval affect Bitcoin compared to Ethereum?" ); ``` **API Endpoints:** ```bash # Standard RAG query curl -X POST /api/rag -d '{"query": "Latest Bitcoin news"}' # Streaming with progress updates curl -N -X POST /api/rag/stream -d '{"query": "Why did crypto crash?"}' # Search without answer generation curl -X POST /api/rag/search -d '{"query": "DeFi hacks", "limit": 10}' ``` 📚 **[Full RAG Documentation](src/lib/rag/README.md)** — Architecture, API reference, configuration, and advanced features. ### 🚀 Code Examples & SDKs (200+ Examples) Complete examples for all 184 API endpoints across 5 languages: | Language | Files | Functions | Description | |----------|-------|-----------|-------------| | [Python](examples/python/) | 12 files | 150+ | Full SDK with all endpoints | | [JavaScript](examples/javascript/) | 11 files | 120+ | Node.js & browser examples | | [TypeScript](examples/typescript/) | 3 files | 80+ | Type-safe SDK | | [Go](examples/go/) | 1 file | 60+ | Go client library | | [cURL](examples/curl/) | 1 file | 100+ | Shell script examples | **Python Example Files:** - `news.py` - News feeds, search, categories (13 functions) - `ai.py` - Sentiment, summarization, NLP (20 functions) - `market.py` - Coins, OHLC, exchanges (16 functions) - `trading.py` - Arbitrage, signals, funding (10 functions) - `social.py` - Twitter, Reddit, Discord (15 functions) - `blockchain.py` - DeFi, NFT, on-chain (17 functions) - `regulatory.py` - ETF, SEC, regulations (14 functions) - `analytics.py` - Trends, correlations (15 functions) - `feeds.py` - RSS, exports, webhooks (13 functions) - `portfolio.py` - Alerts, watchlists (15 functions) - `premium.py` - Premium tier features (12 functions) **Quick Start (Python):** ```python import requests BASE_URL = "https://cryptocurrency.cv" # Get latest news news = requests.get(f"{BASE_URL}/api/news?limit=10").json() # Get Bitcoin sentiment sentiment = requests.get(f"{BASE_URL}/api/ai/sentiment?asset=BTC").json() print(f"BTC: {sentiment['label']} ({sentiment['score']:.2f})") # Get Fear & Greed fg = requests.get(f"{BASE_URL}/api/market/fear-greed").json() print(f"Market: {fg['classification']} ({fg['value']})") ``` **Quick Start (JavaScript):** ```javascript const BASE_URL = 'https://cryptocurrency.cv'; // Get latest news const news = await fetch(`${BASE_URL}/api/news?limit=10`).then(r => r.json()); // Stream real-time updates const events = new EventSource(`${BASE_URL}/api/stream`); events.onmessage = (e) => console.log('New:', JSON.parse(e.data).title); ``` 📚 **[Full Examples Documentation](examples/README.md)** | **[API Tutorial](docs/EXAMPLES.md)** **Bot Integration Examples:** | Example | Language | File | Purpose | | ---------------- | ---------- | ----------------------------- | ------------------------- | | AI Analysis | Python | `examples/ai-analysis.py` | Sentiment & summarization | | LangChain Tool | Python | `examples/langchain-tool.py` | AI agent integration | | Discord Bot | JavaScript | `examples/discord-bot.js` | Channel posting | | Telegram Bot | Python | `examples/telegram-bot.py` | Command handler | | Telegram Digest | Python | `examples/telegram-digest.py` | Scheduled digests | | Slack Bot | JavaScript | `examples/slack-bot.js` | Webhook posting | | Real-time Stream | JavaScript | `examples/realtime-stream.js` | SSE streaming | | curl Examples | Shell | `examples/curl.sh` | API testing | | x402 Python | Python | `examples/x402-client.py` | Payment protocol | | x402 TypeScript | TypeScript | `examples/x402-client.ts` | Payment protocol | | x402 Go | Go | `examples/x402-client.go` | Payment protocol | ### 📖 Complete API Tutorials Step-by-step tutorials with full working code for every API endpoint: | Tutorial | Endpoints Covered | Description | |----------|-------------------|-------------| | [News Basics](docs/tutorials/news-basics.md) | `/api/news`, `/api/latest`, `/api/breaking`, `/api/trending` | Fetching, filtering, and paginating news articles | | [Search & Filtering](docs/tutorials/search-filtering.md) | `/api/search`, `/api/news?source=`, `/api/categories` | Full-text search, source filtering, category browsing | | [Archive & Export](docs/tutorials/archive-export.md) | `/api/archive`, `/api/export`, `/api/rss`, `/api/atom` | Historical data access, bulk exports, RSS/Atom feeds | | [International News](docs/tutorials/international-news.md) | `/api/news/international`, `/api/sources/international`, `/api/languages`, `/api/regions` | Multi-language news with auto-translation | | [AI Sentiment](docs/tutorials/ai-sentiment.md) | `/api/ai/sentiment`, `/api/ai/sentiment/history`, `/api/ai/sentiment/market` | Real-time sentiment analysis for any asset | | [AI Features](docs/tutorials/ai-features.md) | `/api/ask`, `/api/summarize`, `/api/digest`, `/api/entities`, `/api/narratives`, `/api/signals` | Q&A, summarization, NER, narratives, trading signals | | [Trading Signals](docs/tutorials/trading-signals.md) | `/api/trading/arbitrage`, `/api/trading/signals`, `/api/trading/funding` | Arbitrage opportunities, AI signals, funding rates | | [Market Data](docs/tutorials/market-data.md) | `/api/market/coins`, `/api/market/ohlc`, `/api/market/fear-greed`, `/api/market/dominance` | Price data, OHLCV, market indicators | | [DeFi & NFT](docs/tutorials/defi-nft.md) | `/api/defi`, `/api/defi/protocols`, `/api/defi/yields`, `/api/nft`, `/api/nft/collections` | DeFi protocols, yield farming, NFT analytics | | [Analytics & Research](docs/tutorials/analytics-research.md) | `/api/analytics/trends`, `/api/analytics/correlations`, `/api/research` | Market analytics, correlation analysis, research tools | | [Social Intelligence](docs/tutorials/social-intelligence.md) | `/api/social/twitter`, `/api/social/reddit`, `/api/social/discord` | Social media monitoring and sentiment | | [Portfolio & Watchlist](docs/tutorials/portfolio-watchlist.md) | `/api/portfolio`, `/api/watchlist`, `/api/alerts` | Portfolio tracking, watchlists, price alerts | | [Premium Features](docs/tutorials/premium-features.md) | `/api/premium/*`, `/api/x402/*` | Premium API access, x402 micropayments | | [Real-time SSE](docs/tutorials/realtime-sse.md) | `/api/stream`, `/api/prices/stream` | Server-Sent Events for live updates | | [User Alerts](docs/tutorials/user-alerts.md) | `/api/alerts`, `/api/notifications` | Push notifications, price alerts, webhooks | | [Webhooks & Integrations](docs/tutorials/webhooks-integrations.md) | `/api/webhooks`, `/api/webhooks/events` | Webhook management, event subscriptions | | [Utility Endpoints](docs/tutorials/utility-endpoints.md) | `/api/health`, `/api/status`, `/api/sources`, `/api/categories`, `/api/config` | Health checks, system status, metadata | | [Article Extraction](docs/tutorials/article-extraction.md) | `/api/extract`, `/api/extract/batch`, `/api/ai/detect` | Full article content, batch extraction, AI detection | 📚 **[View All Tutorials](docs/tutorials/index.md)** — Complete documentation covering 150+ endpoints with Python, JavaScript, TypeScript, and cURL examples. **MCP Server Modes:** - **stdio:** For Claude Desktop (local) - **HTTP/SSE:** For ChatGPT Developer Mode (remote) - **Tools:** 40 tools available for AI assistants ### 📚 Documentation | Document | Description | | ---------------------------------------------------- | ---------------------------------- | | [API Reference](docs/API.md) | Full API documentation | | [**Tutorials**](docs/tutorials/index.md) | **19 step-by-step guides with code** | | [AI Features](docs/AI-FEATURES.md) | AI endpoint documentation | | [**RAG System**](docs/RAG.md) | **Question answering over news** | | [RAG Roadmap](docs/RAG-ROADMAP.md) | RAG future enhancements | | [Architecture](docs/CDA-ARCHITECTURE-COMPLETE.md) | System architecture | | [Developer Guide](docs/DEVELOPER-GUIDE.md) | Contributing & development | | [Quickstart](docs/QUICKSTART.md) | Getting started guide | | [User Guide](docs/USER-GUIDE.md) | End-user documentation | | [Internationalization](docs/INTERNATIONALIZATION.md) | i18n & localization | | [Real-Time](docs/REALTIME.md) | SSE & WebSocket guide | | [x402 Payments](docs/X402-IMPLEMENTATION.md) | Micropayments implementation | | [Testing](docs/TESTING.md) | Test coverage & strategies | | [Deployment](DEPLOYMENT.md) | Deployment guide | **Base URL:** `https://cryptocurrency.cv` **Failsafe Mirror:** `https://nirholas.github.io/free-crypto-news/` ### Query Parameters | Parameter | Endpoints | Description | | ----------- | ----------------------- | ----------------------- | | `limit` | All news endpoints | Max articles (1-50) | | `source` | `/api/news` | Filter by source | | `from` | `/api/news` | Start date (ISO 8601) | | `to` | `/api/news` | End date (ISO 8601) | | `page` | `/api/news` | Page number | | `per_page` | `/api/news` | Items per page | | `hours` | `/api/trending` | Time window (1-72) | | `topic` | `/api/analyze` | Filter by topic | | `sentiment` | `/api/analyze` | bullish/bearish/neutral | | `feed` | `/api/rss`, `/api/atom` | all/defi/bitcoin | ### AI Endpoint Parameters | Parameter | Endpoints | Description | | ---------------- | ----------------- | ------------------------------ | | `q` | `/api/ask` | Question to ask about news | | `style` | `/api/summarize` | brief/detailed/bullet | | `period` | `/api/digest` | 6h/12h/24h | | `type` | `/api/entities` | ticker/person/company/protocol | | `threshold` | `/api/clickbait` | Min clickbait score (0-100) | | `asset` | `/api/sentiment` | Filter by ticker (BTC, ETH) | | `emerging` | `/api/narratives` | true = only new narratives | | `min_confidence` | `/api/signals` | Min confidence (0-100) | | `date` | `/api/ai/brief` | Date for brief (YYYY-MM-DD) | | `format` | `/api/ai/brief` | full/summary | --- ## Response Format ```json { "articles": [ { "title": "Bitcoin Hits New ATH", "link": "https://coindesk.com/...", "description": "Bitcoin surpassed...", "pubDate": "2025-01-02T12:00:00Z", "source": "CoinDesk", "timeAgo": "2h ago" } ], "totalCount": 150, "fetchedAt": "2025-01-02T14:30:00Z" } ``` --- ## 🤖 AI Endpoint Examples **Ask questions about crypto news:** ```bash curl "https://cryptocurrency.cv/api/ask?q=What%20is%20happening%20with%20Bitcoin%20today" ``` **Get AI-powered summaries:** ```bash curl "https://cryptocurrency.cv/api/summarize?limit=5&style=brief" ``` **Daily digest:** ```bash curl "https://cryptocurrency.cv/api/digest?period=24h" ``` **Deep sentiment analysis:** ```bash curl "https://cryptocurrency.cv/api/sentiment?asset=BTC" ``` **Extract entities (people, companies, tickers):** ```bash curl "https://cryptocurrency.cv/api/entities?type=person" ``` **Identify market narratives:** ```bash curl "https://cryptocurrency.cv/api/narratives?emerging=true" ``` **News-based trading signals:** ```bash curl "https://cryptocurrency.cv/api/signals?min_confidence=70" ``` **Fact-check claims:** ```bash curl "https://cryptocurrency.cv/api/factcheck?type=prediction" ``` **Detect clickbait:** ```bash curl "https://cryptocurrency.cv/api/clickbait?threshold=50" ``` ### 🆕 AI Products **Daily Brief** - Comprehensive crypto news digest: ```bash curl "https://cryptocurrency.cv/api/ai/brief?format=full" ``` **Bull vs Bear Debate** - Generate balanced perspectives: ```bash curl -X POST "https://cryptocurrency.cv/api/ai/debate" \ -H "Content-Type: application/json" \ -d '{"topic": "Bitcoin reaching $200k in 2026"}' ``` **Counter-Arguments** - Challenge any claim: ```bash curl -X POST "https://cryptocurrency.cv/api/ai/counter" \ -H "Content-Type: application/json" \ -d '{"claim": "Ethereum will flip Bitcoin by market cap"}' ``` --- ## 🏗️ Technical Architecture ### Runtime & Performance **Edge Runtime:** 140+ endpoints optimized for Edge runtime **Target Metrics:** - TTFB: <200ms (actual ~150ms on Edge) - FCP: <1.8s (actual ~1.2s) - LCP: <2.5s (actual ~2.0s) - CLS: <0.1 (actual ~0.05) - TTI: <3.8s (actual ~2.8s) ### Caching Strategy (4-Layer) | Layer | Technology | TTL | Purpose | | ----------- | ------------------- | -------- | ------------------- | | L1 - Memory | In-memory Map | 180-300s | Hot data | | L2 - Redis | Vercel KV / Upstash | Variable | Persistent cache | | L3 - ISR | Next.js | 60-300s | Static regeneration | | L4 - CDN | Vercel Edge | Custom | Global distribution | ### Database Backends **Supported Storage:** - ✅ Vercel KV (Primary - Production) - ✅ Upstash Redis (Alternative - Production) - 🔧 Memory (Development only) - 🔧 File System (Local testing) **Features:** - Document-based operations with versioning - TTL support for automatic expiration - Batch operations (mget, mset) - Pattern matching for keys - Statistics and monitoring - Content-addressable storage (CAS) ### Data Architecture **Database Schema Patterns:** | Pattern | Example | Purpose | | ------------------------- | -------------------- | ------------------- | | `feed:{source}` | `feed:coindesk` | Cached RSS feeds | | `article:{id}` | `article:abc123` | Individual articles | | `user:{userId}:watchlist` | `user:123:watchlist` | User watchlists | | `portfolio:{userId}` | `portfolio:123` | User portfolios | | `alert:{id}` | `alert:xyz789` | Price alerts | | `apikey:{hash}` | `apikey:sha256...` | API key hashing | ### Real-time Updates | Method | Use Case | Implementation | | --------- | ----------------------------- | -------------- | | WebSocket | Live prices, liquidations | Binance stream | | SSE | News updates, breaking alerts | `/api/sse` | | Polling | Portfolio updates | Client-side | --- ## 🔐 Authentication & Security ### API Key System **Key Format:** `cda_{tier}_{random}` **Tiers & Limits:** | Tier | Daily Limit | Rate Limit | Price | | ---------- | --------------- | ---------- | ------- | | Free | 100 requests | 10/min | $0/mo | | Pro | 10,000 requests | 100/min | $29/mo | | Enterprise | Unlimited | 1,000/min | $299/mo | **Features:** - SHA-256 key hashing for security - Per-key rate limiting - Usage tracking and analytics - Automatic expiration support - Tier upgrades via x402 payments - API key management endpoints **Create API Key:** ```bash curl -X POST https://cryptocurrency.cv/api/register \ -H "Content-Type: application/json" \ -d '{"email": "your@email.com", "tier": "free"}' ``` **Use API Key:** ```bash curl -H "X-API-Key: cda_free_abc123" \ https://cryptocurrency.cv/api/news ``` ### Security Headers | Header | Value | | ------------------------- | ------------------------------- | | X-Content-Type-Options | nosniff | | X-Frame-Options | SAMEORIGIN | | X-XSS-Protection | 1; mode=block | | Strict-Transport-Security | max-age=63072000 | | Referrer-Policy | strict-origin-when-cross-origin | ### x402 Payment Security **Protocol:** x402 v2 **Network:** Base Mainnet (eip155:8453) **Token:** USDC (0x833589...) **Verification Steps:** 1. Parse payment signature from `PAYMENT-SIGNATURE` header 2. Validate signature format and structure 3. Verify payment amount matches endpoint price 4. Check facilitator confirmation 5. Verify wallet signature cryptographically 6. Grant access if all checks pass **Discovery:** `/.well-known/x402` provides machine-readable pricing --- ## 🧪 Testing & Quality Assurance ### Test Coverage **Test Suites:** - **E2E Tests:** 9 Playwright test files covering critical user paths - **Component Tests:** 8 Storybook stories for key UI components - **API Tests:** Postman collection with 182 endpoint tests - **Unit Tests:** Vitest for core utility functions **E2E Test Coverage:** | Suite | File | Tests | | ------------- | --------------------------- | ------------------------- | | API | `e2e/api.spec.ts` | API endpoint validation | | Home | `e2e/home.spec.ts` | Homepage functionality | | i18n | `e2e/i18n.spec.ts` | Internationalization | | Order Book | `e2e/orderbook.spec.ts` | Trading order book | | TradingView | `e2e/tradingview.spec.ts` | Chart integrations | | x402 | `e2e/x402.spec.ts` | Payment protocol | | Exports | `e2e/exports.spec.ts` | Data export functionality | | Article Slugs | `e2e/article-slugs.spec.ts` | URL routing | | Regulatory | `e2e/regulatory.spec.ts` | Regulatory tracking | **Run Tests:** ```bash # E2E tests npm run test:e2e # Component tests npm run storybook # Unit tests npm run test ``` --- ## 🏗️ Technical Architecture ### Runtime & Performance **Edge Runtime:** 140+ endpoints optimized for Edge runtime **Target Metrics:** - TTFB: <200ms (actual ~150ms on Edge) - FCP: <1.8s (actual ~1.2s) - LCP: <2.5s (actual ~2.0s) - CLS: <0.1 (actual ~0.05) - TTI: <3.8s (actual ~2.8s) ### Caching Strategy (4-Layer) | Layer | Technology | TTL | Purpose | | ----------- | ------------------- | -------- | ------------------- | | L1 - Memory | In-memory Map | 180-300s | Hot data | | L2 - Redis | Vercel KV / Upstash | Variable | Persistent cache | | L3 - ISR | Next.js | 60-300s | Static regeneration | | L4 - CDN | Vercel Edge | Custom | Global distribution | ### Database Backends **Supported Storage:** - ✅ Vercel KV (Primary - Production) - ✅ Upstash Redis (Alternative - Production) - 🔧 Memory (Development only) - 🔧 File System (Local testing) **Features:** - Document-based operations with versioning - TTL support for automatic expiration - Batch operations (mget, mset) - Pattern matching for keys - Statistics and monitoring - Content-addressable storage (CAS) ### Data Architecture **Database Schema Patterns:** | Pattern | Example | Purpose | | ------------------------- | -------------------- | ------------------- | | `feed:{source}` | `feed:coindesk` | Cached RSS feeds | | `article:{id}` | `article:abc123` | Individual articles | | `user:{userId}:watchlist` | `user:123:watchlist` | User watchlists | | `portfolio:{userId}` | `portfolio:123` | User portfolios | | `alert:{id}` | `alert:xyz789` | Price alerts | | `apikey:{hash}` | `apikey:sha256...` | API key hashing | ### Real-time Updates | Method | Use Case | Implementation | | --------- | ----------------------------- | -------------- | | WebSocket | Live prices, liquidations | Binance stream | | SSE | News updates, breaking alerts | `/api/sse` | | Polling | Portfolio updates | Client-side | --- ## 🔐 Authentication & Security ### API Key System **Key Format:** `cda_{tier}_{random}` **Tiers & Limits:** | Tier | Daily Limit | Rate Limit | Price | | ---------- | --------------- | ---------- | ------- | | Free | 100 requests | 10/min | $0/mo | | Pro | 10,000 requests | 100/min | $29/mo | | Enterprise | Unlimited | 1,000/min | $299/mo | **Features:** - SHA-256 key hashing for security - Per-key rate limiting - Usage tracking and analytics - Automatic expiration support - Tier upgrades via x402 payments - API key management endpoints **Create API Key:** ```bash curl -X POST https://cryptocurrency.cv/api/register \ -H "Content-Type: application/json" \ -d '{"email": "your@email.com", "tier": "free"}' ``` **Use API Key:** ```bash curl -H "X-API-Key: cda_free_abc123" \ https://cryptocurrency.cv/api/news ``` ### Security Headers | Header | Value | | ------------------------- | ------------------------------- | | X-Content-Type-Options | nosniff | | X-Frame-Options | SAMEORIGIN | | X-XSS-Protection | 1; mode=block | | Strict-Transport-Security | max-age=63072000 | | Referrer-Policy | strict-origin-when-cross-origin | ### x402 Payment Security **Protocol:** x402 v2 **Network:** Base Mainnet (eip155:8453) **Token:** USDC (0x833589...) **Verification Steps:** 1. Parse payment signature from `PAYMENT-SIGNATURE` header 2. Validate signature format and structure 3. Verify payment amount matches endpoint price 4. Check facilitator confirmation 5. Verify wallet signature cryptographically 6. Grant access if all checks pass **Discovery:** `/.well-known/x402` provides machine-readable pricing --- ## ✨ Advanced Features ### 📦 Content-Addressable Storage (CAS) IPFS-style content addressing for articles: ```bash # Store content with automatic hash curl -X POST https://cryptocurrency.cv/api/storage/cas \ -H "Content-Type: application/json" \ -d '{"content": "Article content here"}' # Returns: {"hash": "bafybei..."} # Retrieve by hash curl https://cryptocurrency.cv/api/storage/cas?hash=bafybei... ``` ### 📊 Data Export Formats Export news data in multiple formats: **Supported Formats:** - JSON (structured) - CSV (spreadsheet-compatible) - Parquet (analytics/big data) ```bash # Create export job curl -X POST https://cryptocurrency.cv/api/export \ -H "Content-Type: application/json" \ -d '{ "format": "csv", "dateFrom": "2026-01-01", "dateTo": "2026-01-31", "sources": ["coindesk", "theblock"] }' # Returns: {"exportId": "exp_123"} # Download export curl https://cryptocurrency.cv/api/exports/exp_123 -o news.csv ``` **Bulk Export Management:** ```bash # List all exports curl https://cryptocurrency.cv/api/exports # Get export status curl https://cryptocurrency.cv/api/exports/exp_123 # Delete export curl -X DELETE https://cryptocurrency.cv/api/exports/exp_123 ``` ### 🏛️ Regulatory Intelligence Multi-jurisdictional regulatory tracking: **Coverage:** - **15 jurisdictions** (US, EU, UK, CN, JP, KR, SG, etc.) - **30+ agencies** (SEC, CFTC, FCA, ESMA, etc.) - **Compliance deadlines** tracking - **Regulatory change detection** ```bash # Get regulatory news curl https://cryptocurrency.cv/api/regulatory # Get jurisdiction profiles curl https://cryptocurrency.cv/api/regulatory?action=jurisdictions # Get agency information curl https://cryptocurrency.cv/api/regulatory?action=agencies # Get upcoming deadlines curl https://cryptocurrency.cv/api/regulatory?action=deadlines # Get intelligence summary curl https://cryptocurrency.cv/api/regulatory?action=summary ``` ### 🏥 DeFi Protocol Health Monitoring **Features:** - Protocol health & risk scoring - Security incident tracking - TVL monitoring - Smart contract risk assessment - Protocol safety rankings ```bash # Get protocol health score curl "https://cryptocurrency.cv/api/defi/protocol-health?protocol=aave-v3" # Get safety rankings by category curl "https://cryptocurrency.cv/api/defi/protocol-health?action=ranking&category=lending" # Get recent security incidents curl "https://cryptocurrency.cv/api/defi/protocol-health?action=incidents&limit=20" ``` ### 🐋 Whale Alert Features **Capabilities:** - Large transaction monitoring - Multi-blockchain support (ETH, BTC, SOL, etc.) - Exchange flow tracking - Wallet address identification - Historical whale activity ```bash # Get recent whale transactions curl "https://cryptocurrency.cv/api/whale-alerts?limit=50" # Filter by blockchain and minimum value curl "https://cryptocurrency.cv/api/whale-alerts?blockchain=ethereum&minUsd=1000000" ``` ### 🎯 Prediction Tracking System **Features:** - Timestamped prediction registry - Accuracy scoring and leaderboards - Influencer reliability tracking - Outcome resolution - Historical performance analysis ```bash # Get predictions curl https://cryptocurrency.cv/api/predictions # Get prediction leaderboard curl https://cryptocurrency.cv/api/predictions?action=leaderboard # Get influencer track record curl https://cryptocurrency.cv/api/influencers?username=crypto_analyst ``` ### 📈 Strategy Backtesting Backtest news-based trading strategies: **Available Strategies:** - Sentiment momentum - News volume signals - Narrative tracking - Entity mention correlation - Breaking news reaction ```bash curl -X POST https://cryptocurrency.cv/api/research/backtest \ -H "Content-Type: application/json" \ -d '{ "strategy": "sentiment_momentum", "asset": "BTC", "period": "1y", "capital": 10000 }' ``` **Returns:** - Total return & annualized return - Sharpe ratio & max drawdown - Win rate & profit factor - Trade-by-trade breakdown ### 🔍 Coverage Gap Analysis Identify under-covered topics and assets: ```bash # Analyze coverage gaps curl https://cryptocurrency.cv/api/coverage-gap # Returns: # - Under-covered assets # - Emerging topics with low coverage # - Source diversity metrics # - Recommended coverage expansions ``` ### 🎓 Academic Access Program Free access for researchers: ```bash # Register for academic access curl -X POST https://cryptocurrency.cv/api/academic \ -H "Content-Type: application/json" \ -d '{ "institution": "University Name", "email": "researcher@university.edu", "purpose": "Research on crypto market sentiment" }' ``` **Benefits:** - Unlimited API access - Historical data exports - Citation network access - Priority support --- # Integration Examples Pick your platform. Copy the code. Ship it. --- ## 🐍 Python **Zero dependencies.** Just copy the file. ```bash curl -O https://raw.githubusercontent.com/nirholas/free-crypto-news/main/sdk/python/crypto_news.py ``` ```python from crypto_news import CryptoNews news = CryptoNews() # Get latest news for article in news.get_latest(5): print(f"📰 {article['title']}") print(f" {article['source']} • {article['timeAgo']}") print(f" {article['link']}\n") # Search for topics eth_news = news.search("ethereum,etf", limit=5) # DeFi news defi = news.get_defi(5) # Bitcoin news btc = news.get_bitcoin(5) # Breaking (last 2 hours) breaking = news.get_breaking(5) ``` **One-liner:** ```python import urllib.request, json news = json.loads(urllib.request.urlopen("https://cryptocurrency.cv/api/news?limit=5").read()) print(news["articles"][0]["title"]) ``` --- ## 🟨 JavaScript / TypeScript **Works in Node.js and browsers.** ### TypeScript SDK (npm) ```bash npm install @nirholas/crypto-news ``` ```typescript import { CryptoNews } from "@nirholas/crypto-news"; const client = new CryptoNews(); // Fully typed responses const articles = await client.getLatest(10); const health = await client.getHealth(); ``` ### Vanilla JavaScript ```bash curl -O https://raw.githubusercontent.com/nirholas/free-crypto-news/main/sdk/javascript/crypto-news.js ``` ```javascript import { CryptoNews } from "./crypto-news.js"; const news = new CryptoNews(); // Get latest const articles = await news.getLatest(5); articles.forEach((a) => console.log(`${a.title} - ${a.source}`)); // Search const eth = await news.search("ethereum"); // DeFi / Bitcoin / Breaking const defi = await news.getDefi(5); const btc = await news.getBitcoin(5); const breaking = await news.getBreaking(5); ``` **One-liner:** ```javascript const news = await fetch( "https://cryptocurrency.cv/api/news?limit=5", ).then((r) => r.json()); console.log(news.articles[0].title); ``` --- ## 🤖 ChatGPT (Custom GPT) Build a crypto news GPT in 2 minutes. 1. Go to [chat.openai.com](https://chat.openai.com) → Create GPT 2. Click **Configure** → **Actions** → **Create new action** 3. Paste this OpenAPI schema: ```yaml openapi: 3.1.0 info: title: Free Crypto News version: 1.0.0 servers: - url: https://cryptocurrency.cv paths: /api/news: get: operationId: getNews summary: Get latest crypto news parameters: - name: limit in: query schema: type: integer default: 10 /api/search: get: operationId: searchNews summary: Search crypto news parameters: - name: q in: query required: true schema: type: string /api/defi: get: operationId: getDefiNews summary: Get DeFi news /api/bitcoin: get: operationId: getBitcoinNews summary: Get Bitcoin news /api/breaking: get: operationId: getBreakingNews summary: Get breaking news ``` 4. No authentication needed 5. Save and test: _"What's the latest crypto news?"_ Full schema: [`chatgpt/openapi.yaml`](chatgpt/openapi.yaml) --- ## 🔮 MCP Server (Claude Desktop & ChatGPT Developer Mode) The MCP server provides **40 tools** for AI assistants to access crypto news. ### Available Tools | Tool | Description | | ----------------------- | ------------------------------ | | `get_crypto_news` | Latest news from 130+ sources | | `search_crypto_news` | Search by keywords | | `get_defi_news` | DeFi-specific news | | `get_bitcoin_news` | Bitcoin-specific news | | `get_breaking_news` | Breaking news (last 2 hours) | | `get_news_sources` | List all sources | | `get_api_health` | API health check | | `get_trending_topics` | Trending topics with sentiment | | `get_crypto_stats` | Analytics & statistics | | `analyze_news` | News with sentiment analysis | | `get_archive` | Historical news archive | | `get_archive_stats` | Archive statistics | | `find_original_sources` | Original source tracking | | `get_portfolio_news` | Portfolio news with prices | ### Option 1: Claude Desktop (stdio) **1. Clone & install:** ```bash git clone https://github.com/nirholas/free-crypto-news.git cd free-crypto-news/mcp && npm install ``` **2. Add to config** **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "crypto-news": { "command": "node", "args": ["/path/to/free-crypto-news/mcp/index.js"] } } }

mcp-server-crypto-news

Installation