شروع سریع
اولین مقاله را در حدود ۵ دقیقه بگیرید — کلید بگیرید، یک GET بزنید، آرایه JSON را بخوانید.
نمونه کدها
curl -X GET "https://api.upgate.online/api/v1/crypto/articles/translated/latest-snapshot/?lang=fa&limit=3" \
-H "X-API-Key: your_client_api_key" \
-H "Accept: application/json"پاسخ
[
{
"original_id": 2147,
"language": "fa",
"title": "OKX جفتارزهای IRYS/USD و IRYS/EUR را راهاندازی میکند",
"content": "برای حمایت از رشد اکوسیستم یکپارچه USD و EUR...",
"created_at": "2026-05-27T05:00:00",
"meta": {
"token_mentions": ["IRYS"],
"thumbnail_url": "https://img.upgate.online/crypto/2147",
"source_name": "OKX",
"category": "exchanges",
"sentiment": "positive"
}
}
]کدام Endpoint؟
مطمئن نیستید ScrollBoost یا Snapshot؟ از انتخابگر زیر استفاده کنید.
کدام endpoint مناسب من است؟
کاربرد خود را انتخاب کنید — endpoint مناسب پیشنهاد میشود.
چه چیزی میسازید؟
راهنمای یکپارچهسازی: فید خبری
ScrollBoost را با direction=newer وقتی اپ باز است poll کنید. موقعیت خواندن سمت سرور است — cursor نمیفرستید. مقالات جدید را به UI اضافه کنید؛ [] یعنی بهروز هستید.
نمونه کدها
const API_BASE = "https://api.upgate.online"
const PATH = "/api/v1/crypto/articles/translated/"
async function pollFeed({ apiKey, lang = "fa", limit = 10 }) {
const url = new URL(API_BASE + PATH)
url.searchParams.set("lang", lang)
url.searchParams.set("limit", String(limit))
url.searchParams.set("direction", "newer")
const res = await fetch(url, {
headers: { "X-API-Key": apiKey, Accept: "application/json" },
})
if (!res.ok) {
const err = await res.json().catch(() => ({}))
throw new Error(err.detail || `HTTP ${res.status}`)
}
return res.json() // [] = مقاله جدید نیست (خطا نیست)
}
const apiKey = process.env.UPGATE_API_KEY
setInterval(async () => {
const batch = await pollFeed({ apiKey, lang: "fa", limit: 10 })
for (const article of batch) {
renderCard(article)
}
}, 60_000) // فاصله ≥ frequency_minutes پلن شماراهنمای یکپارچهسازی: Cron و هشدار
Snapshot را از سرور یا cron poll کنید. بدون state — dedup با original_id. مناسب داشبورد، ربات تلگرام و فیلتر توکن (?token=BTC).
نمونه کدها
const API_BASE = "https://api.upgate.online"
const PATH = "/api/v1/crypto/articles/translated/latest-snapshot/"
const seen = new Set()
async function pollSnapshot({ apiKey, lang = "fa", limit = 10, token }) {
const params = { lang, limit: String(limit) }
if (token) params.token = token
const url = new URL(API_BASE + PATH)
Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v))
const res = await fetch(url, {
headers: { "X-API-Key": apiKey, Accept: "application/json" },
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).detail || res.status)
return res.json()
}
function ingestNew(articles) {
return articles.filter((a) => {
if (seen.has(a.original_id)) return false
seen.add(a.original_id)
return true
})
}
async function tick() {
const apiKey = process.env.UPGATE_API_KEY
const fresh = ingestNew(await pollSnapshot({ apiKey, lang: "fa", limit: 10, token: "BTC" }))
for (const article of fresh) await notify(article)
}
setInterval(tick, 5 * 60_000)معرفی
اخبار ترجمهشده کریپتو برای محصول شما — عنوان، متن، تصویر، توکن، دستهبندی و sentiment. خروجی انگلیسی (en) یا فارسی (fa، RTL). دو endpoint GET: یکی برای فید اسکرولی، یکی برای polling سمت سرور.
محتوای هر مقاله
| خروجی | جزئیات |
|---|---|
| عنوان و متن ترجمهشده | فارسی (fa) یا انگلیسی (en)، با پشتیبانی Markdown |
| دستهبندی موضوعی | market_trends، exchanges، regulation_policy و ... |
| احساس بازار | positive، negative یا neutral |
| برچسب توکن | meta.token_mentions — مثلاً BTC، ETH |
| نام منبع | meta.source_name |
| تصویر بندانگشتی | meta.thumbnail_url — بدون احراز هویت جداگانه |
Endpointها
| Endpoint | Stateful | حداکثر limit | کاربرد |
|---|---|---|---|
| GET /articles/translated/ | بله | ۱۰۰ (پیشفرض ۱۰) | فید خبری با اسکرول در اپلیکیشن |
| GET /articles/translated/latest-snapshot/ | خیر | ۵۰ (پیشفرض ۱۰) | Polling از سرور، داشبورد یا cron |
احراز هویت
کلید API را در هدر X-API-Key هر درخواست بفرستید. محدودیتها هنگام صدور کلید تنظیم میشوند.
پارامترها
| نام | نوع | اجباری | توضیحات |
|---|---|---|---|
| X-API-Key | string | بله | کلید API صادرشده توسط UpGate مثال: your_client_api_key |
| Accept | string | خیر | application/json مثال: application/json |
| X-Request-ID | string | خیر | اختیاری؛ برای پشتیبانی در پاسخ برمیگردد مثال: my-trace-id-123 |
نمونه کدها
curl -X GET "https://api.upgate.online/api/v1/crypto/articles/translated/latest-snapshot/?limit=1" \
-H "X-API-Key: your_client_api_key"فید ScrollBoost
صفحهبندی هوشمند با checkpoint سمت سرور. بدون cursor. مقالات در پنجره ۲ روزه.
جریان state در ScrollBoost
اولین درخواست GET ?direction=newer → آخرین مقالات دریافت مقالات جدید GET ?direction=newer → فقط مقالات دیدهنشده [] → مقاله جدیدی نیست اسکرول به مقالات قدیمیتر (پنجره ۲ روز) GET ?direction=older → مقالات قدیمیتر [] → به انتهای تاریخچه رسیدید موقعیت خواندن سمت سرور (per کلید API و زبان) ذخیره میشود. نیازی به ارسال cursor یا offset نیست. در poll فید، همیشه direction=newer بفرستید.
نقطه پایانی
GEThttps://api.upgate.online/api/v1/crypto/articles/translated/پارامترها
| نام | نوع | اجباری | توضیحات |
|---|---|---|---|
| lang | string | خیر | fa یا en. پیشفرض: fa مثال: fa |
| limit | integer | خیر | ۱ تا ۱۰۰، محدود به max_items_per_request مثال: 10 |
| direction | string | خیر | newer (دیدهنشده) یا older (تاریخچه). اگر حذف شود: بدون checkpoint → newer، با checkpoint → older. در poll فید همیشه newer بفرستید. مثال: newer |
| token | string | خیر | فیلتر نماد توکن مثال: BTC |
نمونه کدها
curl -X GET "https://api.upgate.online/api/v1/crypto/articles/translated/?lang=fa&limit=10&direction=newer" \
-H "X-API-Key: your_api_key_here"Snapshot API
آخرین مقالات بدون ردیابی تاریخچه خواندن. مناسب داشبورد، cron و هشدار. dedup با original_id.
نقطه پایانی
GEThttps://api.upgate.online/api/v1/crypto/articles/translated/latest-snapshot/پارامترها
| نام | نوع | اجباری | توضیحات |
|---|---|---|---|
| lang | string | خیر | fa یا en. پیشفرض: fa مثال: fa |
| limit | integer | خیر | ۱ تا ۵۰. پیشفرض: ۱۰ مثال: 10 |
| token | string | خیر | فیلتر توکن مثال: BTC |
نمونه کدها
curl -X GET "https://api.upgate.online/api/v1/crypto/articles/translated/latest-snapshot/?lang=fa&limit=10&token=BTC" \
-H "X-API-Key: your_api_key_here"فرمت پاسخ
هر دو endpoint یک آرایه JSON از مقالات برمیگردانند. wrapper object ندارد.
پاسخ
[{ "original_id": 2147, "title": "...", "meta": { "token_mentions": ["IRYS"], "sentiment": "positive" } }]فیلدهای مقاله
| فیلد | نوع | توضیح |
|---|---|---|
| original_id | integer | شناسه یکتا — برای dedup |
| language | string | fa یا en |
| title | string | عنوان ترجمهشده |
| content | string | متن ترجمه (Markdown؛ RTL برای fa) |
| created_at | string | زمان ایجاد ترجمه (UTC) |
| meta.token_mentions | string[] | نمادهای توکن مثلاً ["BTC"] |
| meta.source_name | string | منبع مثلاً OKX |
| meta.category | string | برچسب موضوعی AI |
| meta.sentiment | string | positive | negative | neutral |
| meta.thumbnail_url | string | آدرس Image Gateway |
| meta.has_watermark | boolean | واترمارک تصویر منبع |
دستهبندیها
| برچسب | توضیح |
|---|---|
| market_trends | حرکت قیمت، تحلیل بازار، ETF |
| regulation_policy | نظارت، قانونگذاری |
| project_updates | ارتقا، نقشه راه، تیم |
| defi | پروتکلهای DeFi |
| nft | بازار NFT |
| memecoin | میمکوینها |
| exchanges | لیستینگ و اخبار صرافی |
| security_hacks | حملات و آسیبپذیری |
| adoption_partnerships | پذیرش و مشارکت |
| technology_innovation | لایه ۲، اجماع، فناوری |
| mining_infrastructure | ماینینگ، استیکینگ |
| macro_economy | عوامل کلان اقتصادی |
| unclassified | اطمینان پایین در دستهبندی |
زبانها
| کد | زبان | پیشفرض |
|---|---|---|
| fa | فارسی | بله |
| en | انگلیسی | خیر |
راهنمای خطاها
در production چه میبینید، یعنی چه، و چه کار کنید.
پاسخ
HTTP 429
{
"detail": "Rate limit exceeded. Please wait 1 minutes between requests."
}
HTTP 200 (عادی)
[]علائم و راهحل
| چه میبینید | معنی | اقدام |
|---|---|---|
| [] (آرایه خالی) | مقاله جدید یا matchشده نیست | عادی است — poll را ادامه دهید. خطا نیست. |
| HTTP 401 + detail | کلید نامعتبر، غیرفعال یا منقضی | X-API-Key را بررسی کنید. [email protected] |
| HTTP 429 + wait N minutes | frequency_minutes — زود بعد از درخواست قبلی | N دقیقه صبر کنید. در cron backoff بگذارید. |
| HTTP 429 + daily limit | daily_limit کلید شما تمام شده | تا روز بعد UTC متوقف کنید یا پلن را ارتقا دهید. |
| HTTP 400 + max items | limit از max_items_per_request بیشتر است | پارامتر limit را کم کنید. |
| HTTP 400 + invalid lang | کد زبان نامعتبر | فقط fa یا en. |
| HTTP 500 | خطای سرور | با backoff retry. X-Request-ID را به [email protected] بفرستید. |
| پیام سقف تست دمو | سقف تستر مشترک docs (نه کلید شما) | با کلید خودتان تست کنید یا فردا دوباره امتحان کنید. |
سوالات متداول
پاسخ رایجترین سوالات یکپارچهسازی.
سوالات متداول
webhook دارید؟
خیر. با polling — ScrollBoost برای فید، Snapshot برای cron.
چه زبانهایی پشتیبانی میشود؟
fa و en. پیشفرض fa است.
sandbox دارید؟
خیر. [email protected] برای دریافت کلید.
فیلتر توکن؟
?token=BTC روی هر دو endpoint (بدون حساسیت به حروف).
محدودیتها و سهمیه
محدودیت per-client هنگام صدور کلید تنظیم میشود.
انواع محدودیت
| محدودیت | توضیح | کد HTTP |
|---|---|---|
| frequency_minutes | حداقل فاصله بین درخواستهای متوالی | 429 |
| daily_limit | حداکثر درخواست در روز | 429 |
| max_items_per_request | حداکثر مقدار پارامتر limit | 400 |
| access_expires_at | تاریخ انقضای کلید | 401 |
پشتیبانی
کمک لازم دارید؟ با [email protected] تماس بگیرید و X-Request-ID، مسیر endpoint و زمان تقریبی درخواست را بفرستید.
