# API Usage Guide - How to Use the Crypto Monitor Services ## راهنمای استفاده از API - چگونه از سرویس‌های کریپتو مانیتور استفاده کنیم --- ## English Guide ### Overview This application provides cryptocurrency monitoring services through a web interface and backend APIs. Users can access real-time crypto prices, news, and market data. ### Architecture ``` ┌─────────────────┐ │ User/Browser │ └────────┬────────┘ │ HTTP Requests ▼ ┌─────────────────┐ │ Frontend (UI) │ │ - HTML/CSS/JS │ │ - React/Vue │ └────────┬────────┘ │ API Calls ▼ ┌─────────────────┐ │ Backend Server │ │ - Node.js/Py │ │ - API Routes │ └────────┬────────┘ │ ├─────────────────┐ ▼ ▼ ┌─────────────┐ ┌──────────────┐ │ News API │ │ Crypto APIs │ │ External │ │ CoinGecko │ └─────────────┘ └──────────────┘ ``` ### How to Use the Services #### 1. **News Service** **Access Method**: Web Browser - Navigate to: `http://localhost:PORT/static/pages/news/index.html` - The page automatically loads latest cryptocurrency news **JavaScript API Usage**: ```javascript // The news page uses this internally const newsPage = new NewsPage(); await newsPage.loadNews(); // Get filtered articles newsPage.currentFilters.keyword = 'bitcoin'; newsPage.applyFilters(); ``` **Configuration**: ```javascript // Edit news-config.js export const NEWS_CONFIG = { apiKey: 'YOUR_API_KEY', defaultQuery: 'cryptocurrency OR bitcoin', pageSize: 100 }; ``` #### 2. **Backend API Endpoints** **News Endpoint**: ```http GET /api/news ``` **Query Parameters**: - `source`: Filter by news source - `sentiment`: Filter by sentiment (positive/negative/neutral) - `limit`: Number of articles (default: 100) **Example Request**: ```bash # Using curl curl "http://localhost:3000/api/news?limit=50&sentiment=positive" # Using JavaScript fetch fetch('/api/news?limit=50') .then(response => response.json()) .then(data => console.log(data.articles)); # Using Python requests import requests response = requests.get('http://localhost:3000/api/news?limit=50') articles = response.json()['articles'] ``` **Response Format**: ```json { "articles": [ { "title": "Bitcoin Reaches New High", "content": "Article description...", "source": { "title": "CryptoNews" }, "published_at": "2025-11-30T10:00:00Z", "url": "https://example.com/article", "sentiment": "positive", "category": "market" } ], "total": 50, "fallback": false } ``` #### 3. **Cryptocurrency Data Endpoints** **Get Crypto Prices**: ```http GET /api/crypto/prices ``` **Example**: ```bash curl "http://localhost:3000/api/crypto/prices?symbols=BTC,ETH,ADA" ``` **Get Market Data**: ```http GET /api/crypto/market ``` **Get Historical Data**: ```http GET /api/crypto/history?symbol=BTC&days=30 ``` ### Client-Side Integration #### HTML Page ```html Crypto Monitor
``` #### React Component ```jsx import { useState, useEffect } from 'react'; function NewsComponent() { const [articles, setArticles] = useState([]); useEffect(() => { fetch('/api/news?limit=20') .then(res => res.json()) .then(data => setArticles(data.articles)); }, []); return (
{articles.map(article => (

{article.title}

{article.content}

))}
); } ``` #### Vue Component ```vue ``` ### Error Handling **Handle API Errors**: ```javascript async function fetchNewsWithErrorHandling() { try { const response = await fetch('/api/news'); if (!response.ok) { if (response.status === 401) { throw new Error('Authentication failed'); } else if (response.status === 429) { throw new Error('Too many requests'); } else if (response.status === 500) { throw new Error('Server error'); } } const data = await response.json(); return data.articles; } catch (error) { console.error('Error fetching news:', error); // Show user-friendly error message alert(`Failed to load news: ${error.message}`); return []; } } ``` ### Rate Limiting **API Limits**: - News API: 100 requests/day (free tier) - Backend API: Configurable (default: 1000 requests/hour) **Handle Rate Limits**: ```javascript // Implement caching const cache = new Map(); const CACHE_TTL = 60000; // 1 minute async function fetchWithCache(url) { const cached = cache.get(url); if (cached && Date.now() - cached.timestamp < CACHE_TTL) { return cached.data; } const response = await fetch(url); const data = await response.json(); cache.set(url, { data, timestamp: Date.now() }); return data; } ``` ### WebSocket Integration (Real-time Updates) ```javascript // Connect to WebSocket for real-time crypto prices const ws = new WebSocket('ws://localhost:3000/ws/crypto'); ws.onopen = () => { console.log('Connected to crypto feed'); // Subscribe to specific coins ws.send(JSON.stringify({ action: 'subscribe', symbols: ['BTC', 'ETH', 'ADA'] })); }; ws.onmessage = (event) => { const data = JSON.parse(event.data); console.log('Price update:', data); // Update UI with new prices updatePriceDisplay(data); }; ws.onerror = (error) => { console.error('WebSocket error:', error); }; ws.onclose = () => { console.log('Disconnected from crypto feed'); // Attempt reconnection setTimeout(connectWebSocket, 5000); }; ``` --- ## راهنمای فارسی ### نحوه استفاده از سرویس‌ها #### ۱. **سرویس اخبار** **روش دسترسی**: مرورگر وب - آدرس: `http://localhost:PORT/static/pages/news/index.html` - صفحه به صورت خودکار آخرین اخبار ارز دیجیتال را بارگذاری می‌کند **استفاده از API در جاوااسکریپت**: ```javascript // صفحه اخبار از این کد استفاده می‌کند const newsPage = new NewsPage(); await newsPage.loadNews(); // فیلتر کردن مقالات newsPage.currentFilters.keyword = 'bitcoin'; newsPage.applyFilters(); ``` #### ۲. **نقاط پایانی API سرور** **دریافت اخبار**: ```http GET /api/news ``` **پارامترهای درخواست**: - `source`: فیلتر بر اساس منبع خبر - `sentiment`: فیلتر بر اساس احساسات (مثبت/منفی/خنثی) - `limit`: تعداد مقالات (پیش‌فرض: ۱۰۰) **مثال درخواست**: ```bash # استفاده از curl curl "http://localhost:3000/api/news?limit=50&sentiment=positive" # استفاده از fetch در جاوااسکریپت fetch('/api/news?limit=50') .then(response => response.json()) .then(data => console.log(data.articles)); # استفاده از Python import requests response = requests.get('http://localhost:3000/api/news?limit=50') articles = response.json()['articles'] ``` **فرمت پاسخ**: ```json { "articles": [ { "title": "بیت‌کوین به رکورد جدید رسید", "content": "توضیحات مقاله...", "source": { "title": "اخبار کریپتو" }, "published_at": "2025-11-30T10:00:00Z", "url": "https://example.com/article", "sentiment": "positive" } ], "total": 50 } ``` #### ۳. **نقاط پایانی داده‌های ارز دیجیتال** **دریافت قیمت‌ها**: ```bash curl "http://localhost:3000/api/crypto/prices?symbols=BTC,ETH,ADA" ``` **دریافت داده‌های بازار**: ```bash curl "http://localhost:3000/api/crypto/market" ``` **دریافت داده‌های تاریخی**: ```bash curl "http://localhost:3000/api/crypto/history?symbol=BTC&days=30" ``` ### یکپارچه‌سازی با برنامه کاربردی #### صفحه HTML ```html مانیتور کریپتو
``` ### مدیریت خطاها ```javascript async function fetchNewsWithErrorHandling() { try { const response = await fetch('/api/news'); if (!response.ok) { if (response.status === 401) { throw new Error('احراز هویت ناموفق بود'); } else if (response.status === 429) { throw new Error('تعداد درخواست‌ها زیاد است'); } else if (response.status === 500) { throw new Error('خطای سرور'); } } const data = await response.json(); return data.articles; } catch (error) { console.error('خطا در دریافت اخبار:', error); alert(`خطا در بارگذاری اخبار: ${error.message}`); return []; } } ``` ### محدودیت‌های استفاده **محدودیت‌های API**: - News API: ۱۰۰ درخواست در روز (نسخه رایگان) - Backend API: قابل تنظیم (پیش‌فرض: ۱۰۰۰ درخواست در ساعت) ### به‌روزرسانی‌های زنده (WebSocket) ```javascript // اتصال به WebSocket برای قیمت‌های لحظه‌ای const ws = new WebSocket('ws://localhost:3000/ws/crypto'); ws.onopen = () => { console.log('اتصال برقرار شد'); // اشتراک در سکه‌های خاص ws.send(JSON.stringify({ action: 'subscribe', symbols: ['BTC', 'ETH', 'ADA'] })); }; ws.onmessage = (event) => { const data = JSON.parse(event.data); console.log('به‌روزرسانی قیمت:', data); // به‌روزرسانی رابط کاربری updatePriceDisplay(data); }; ``` --- ## Quick Reference ### Common Queries | Purpose | Endpoint | Example | |---------|----------|---------| | Get all news | `/api/news` | `GET /api/news?limit=50` | | Filter by source | `/api/news?source=X` | `GET /api/news?source=CoinDesk` | | Positive news only | `/api/news?sentiment=positive` | `GET /api/news?sentiment=positive&limit=20` | | Search keyword | Client-side filter | `newsPage.currentFilters.keyword = 'bitcoin'` | | Get BTC price | `/api/crypto/prices?symbols=BTC` | `GET /api/crypto/prices?symbols=BTC` | | Market overview | `/api/crypto/market` | `GET /api/crypto/market` | ### Response Status Codes | Code | Meaning | Action | |------|---------|--------| | 200 | Success | Process data | | 401 | Unauthorized | Check API key | | 429 | Rate limited | Wait and retry | | 500 | Server error | Use fallback data | | 503 | Service unavailable | Retry later |