Spaces:

Really-amin
/

Datasourceforcryptocurrency

Paused

File size: 13,389 Bytes

b190b45

# 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

<!DOCTYPE html>

<html>

<head>

  <title>Crypto Monitor</title>

</head>

<body>

  <div id="news-container"></div>

  

  <script type="module">

    // Load news dynamically

    async function loadNews() {

      const response = await fetch('/api/news?limit=10');

      const data = await response.json();

      

      const container = document.getElementById('news-container');

      container.innerHTML = data.articles.map(article => `

        <div class="news-card">

          <h3>${article.title}</h3>

          <p>${article.content}</p>

          <a href="${article.url}">Read more</a>

        </div>

      `).join('');

    }

    

    loadNews();

  </script>

</body>

</html>

```

#### 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 (

    <div>

      {articles.map(article => (

        <div key={article.url}>

          <h3>{article.title}</h3>

          <p>{article.content}</p>

        </div>

      ))}

    </div>

  );

}

```

#### Vue Component
```vue

<template>

  <div>

    <div v-for="article in articles" :key="article.url">

      <h3>{{ article.title }}</h3>

      <p>{{ article.content }}</p>

    </div>

  </div>

</template>



<script>

export default {

  data() {

    return { articles: [] };

  },

  async mounted() {

    const response = await fetch('/api/news?limit=20');

    const data = await response.json();

    this.articles = data.articles;

  }

}

</script>

```

### 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

<!DOCTYPE html>

<html dir="rtl" lang="fa">

<head>

  <meta charset="UTF-8">

  <title>مانیتور کریپتو</title>

</head>

<body>

  <div id="news-container"></div>

  

  <script type="module">

    // بارگذاری اخبار

    async function loadNews() {

      const response = await fetch('/api/news?limit=10');

      const data = await response.json();

      

      const container = document.getElementById('news-container');

      container.innerHTML = data.articles.map(article => `

        <div class="news-card">

          <h3>${article.title}</h3>

          <p>${article.content}</p>

          <a href="${article.url}">ادامه مطلب</a>

        </div>

      `).join('');

    }

    

    loadNews();

  </script>

</body>

</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 |