شفاف، غیرامانی، در کنترل تو

آموزش توسعه‌دهندگان وب۳؛ اولین درخواست به API بازار

Q: برای API بازار باید کلید بسازم؟

نمونههای عمومی این راهنما برای خواندن بازار به کلید کاربر نیاز ندارند. جزئیات هر مسیر و مرزهای دسترسی را در /api/openapi.json بررسی کن.

Q: آیا API قیمت یا uptime را تضمین میکند؟

نه. داده به سرویسهای بالادستی و کش وابسته است و uptime یا SLA تضمینشدهای اعلام نشده. خطا و دادهٔ ناموجود را در برنامهٔ خودت صریح نمایش بده.

راهنمای عملی توسعه‌دهندگان برای API عمومی بازار FBT: نمونهٔ واقعی curl و JavaScript، نمودار و کندل، کنترل خطا و نگهداری امن کلیدها.

باز کردن برنامه دیدن جزئیات

        نوع داده
        عمومی و فقط‌خواندنی در endpointهای نمونه
      
        احراز هویت
        برای endpointهای بازار این راهنما لازم نیست
      
        نمودار
        تاریخچهٔ قیمت و OHLC از مسیرهای جداگانه

FBT Swap

چیزی که باید بدانی

این آموزش برای ساخت کلاینتی است که دادهٔ عمومی بازار را می‌خواند؛ نه برای امضای تراکنش یا جابه‌جایی دارایی کاربر. هر دو نمونه از endpoint بازار استفاده می‌کنند و کلید API خصوصی لازم ندارند.

پاسخ‌های API می‌توانند به محدودیت منبع بالادستی، کش یا اختلال شبکه وابسته باشند. وضعیت HTTP را بررسی کن، پاسخ را cache کن و در صورت محدودشدن، backoff داشته باش. این سرویس قرارداد uptime یا SLA برای برنامهٔ تو ارائه نمی‌دهد.

برای هرپارامتر و endpoint تازه، قرارداد ماشین‌خوان را پیش از توسعه بخوان. مستندات اجرایی باید با پاسخ واقعی سرویس یکی باشد؛ اگر چیزی در OpenAPI نیست، فرض نکن که پشتیبانی می‌شود.

۱. API عمومی را با یک درخواست امن شروع کن

GET /api/markets?per_page=5 فهرست بازار را از همان دامنه می‌خواند. برای مسیرهای عمومی این راهنما کلید کاربر لازم نیست. پاسخ را JSON فرض کن، اما همیشه response.ok و شکل داده را بررسی کن؛ upstream ممکن است موقتاً در دسترس نباشد.

در رابط وب، از مسیر نسبی /api استفاده کن تا مرورگر همان دامنه را صدا بزند. برای سرویس بیرونی از آدرس عمومی https://fbtswap.ir/api استفاده کن و محدودیت CORS و شرایط استفاده را از OpenAPI و پاسخ سرور بررسی کن.

۲. نمودار خطی و کندل را از endpoint درست بگیر

GET /api/chart/bitcoin?days=7 تاریخچهٔ قیمت را برمی‌گرداند. برای نمودار شمعی، GET /api/ohlc/bitcoin?days=30 دادهٔ باز، سقف، کف و بسته‌شدن (OHLC) را می‌دهد. هر دو مسیر دادهٔ تاریخی‌اند و تضمین نمی‌کنند قیمت آینده چه می‌شود.

برای فهرست ۳۰ دارایی، یک درخواست /api/markets?per_page=30 کافی است؛ همان پاسخ سری sparkline هفت‌روزه را همراه اطلاعات بازار می‌آورد. برای ساخت جدول، از ۳۰ درخواست جداگانهٔ نمودار استفاده نکن.

۳. خطا، cache و کلیدها را جدی بگیر

پاسخ‌های 4xx و 5xx را از دادهٔ معتبر جدا کن و درخواست ناموفق را به‌عنوان قیمت صفر ذخیره نکن. نتایج را متناسب با نوع داده cache کن، retryها را با فاصلهٔ افزایشی انجام بده و در برابر 429 یا Retry-After مطابق پاسخ سرور رفتار کن.

کلید ارائه‌دهندهٔ داده یا مدل را در متغیری با پیشوند VITE_، کد فرانت‌اند یا APK نگذار؛ این متغیرها عمومی می‌شوند. کلید خصوصی فقط در محیط سرور نگهداری شود. API بازار FBT برای استفادهٔ عمومی کلید کاربر نمی‌خواهد.

۴. از قرارداد API ماشین‌خوان استفاده کن

فهرست endpointهای خواندنی، پارامترها و مرزهای سرویس در /api/openapi.json است. از همان مستندات برای ساخت typeها و اعتبارسنجی ورودی استفاده کن و مسیرهای write یا داخلی را به‌عنوان API عمومی فرض نکن.

قبل از انتشار integration، سناریوی دادهٔ خالی، timeout، پاسخ نامعتبر، rate limit و قطع منبع را آزمایش کن. اگر برنامه‌ات برای تصمیم مالی یا نمایش قیمت به feed نیاز دارد، وضعیت «داده در دسترس نیست» را به‌جای مقدار ساختگی نشان بده.

API

نمونهٔ درخواست

درخواست curl

curl -fsS "https://fbtswap.ir/api/markets?per_page=5" \
  -H "accept: application/json"

خواندن همان API در JavaScript

const response = await fetch("/api/markets?per_page=5", {
  headers: { accept: "application/json" }
});
if (!response.ok) throw new Error("HTTP " + response.status);
const markets = await response.json();
console.table(markets.slice(0, 5));

در یک نگاه

نوع داده

عمومی و فقط‌خواندنی در endpointهای نمونه

احراز هویت

برای endpointهای بازار این راهنما لازم نیست

نمودار

تاریخچهٔ قیمت و OHLC از مسیرهای جداگانه

قابلیت اطمینان

پاسخ upstream را cache و خطا را صریح مدیریت کن

FAQ

پرسش‌های رایج

پاسخ‌های کوتاه و روشن، پیش از اینکه تصمیم بگیری.

برای API بازار باید کلید بسازم؟

نمونه‌های عمومی این راهنما برای خواندن بازار به کلید کاربر نیاز ندارند. جزئیات هر مسیر و مرزهای دسترسی را در /api/openapi.json بررسی کن.

آیا API قیمت یا uptime را تضمین می‌کند؟

نه. داده به سرویس‌های بالادستی و کش وابسته است و uptime یا SLA تضمین‌شده‌ای اعلام نشده. خطا و دادهٔ ناموجود را در برنامهٔ خودت صریح نمایش بده.

آیا باید هر توکن را با یک درخواست نمودار بخوانم؟

برای جدول ۳۰ دارایی از /api/markets?per_page=30 استفاده کن؛ پاسخ فهرست، دادهٔ sparkline هفت‌روزه هم دارد. درخواست بیشتر از نیاز، سهمیهٔ مشترک را مصرف می‌کند.

هشدار ریسک

دارایی‌های کریپتو پرنوسان‌اند و تراکنش روی زنجیره برگشت‌ناپذیر است؛ ممکن است همهٔ پولت را از دست بدهی. هیچ‌چیز این‌جا توصیهٔ مالی نیست.