شروع کار

این بخش، مرجع کامل اندپوینت‌های API است. پیش از آن‌که سراغ اندپوینت‌ها بروید، قراردادهای مشترک این صفحه را یک بار مرور کنید؛ همه‌ی صفحات بعدی بر پایه‌ی همین قراردادها نوشته شده‌اند و در آن‌ها تکرار نمی‌شوند.

---

آدرس پایه

همه‌ی مسیرها نسبت به آدرس پایه‌ی سرویس نوشته شده‌اند. در نمونه‌های این مستندات، آدرس پایه با متغیر $BASE_URL نشان داده می‌شود و پیشوند /api/v1 جدا از آن و به‌صورت بخشی از مسیر آمده است.

export BASE_URL="https://api.asacoine.com"
export API_KEY="ak_live_xxxxxxxxxxxxxxxxx"

---

پیشوند مسیرها

همه‌ی اندپوینت‌ها زیر پیشوند /api/v1 قرار دارند. این پیشوند بخشی از مسیر است و در نمونه‌های این مستندات همیشه نوشته شده است.

https://api.asacoine.com/api/v1/<مسیر اندپوینت>

بخش	مقدار
آدرس پایه	https://api.asacoine.com
پیشوند نسخه	/api/v1
نمونه‌ی کامل	GET https://api.asacoine.com/api/v1/market/currencies

❌ نامناسب

curl "$BASE_URL/market/currencies"

✅ مناسب

curl "$BASE_URL/api/v1/market/currencies"

حذف پیشوند، پاسخ 404 برمی‌گرداند. اگر در آینده نسخه‌ی تازه‌ای منتشر شود، با پیشوند جداگانه‌ای عرضه می‌شود و /api/v1 تا اعلام رسمی پابرجا می‌ماند.

---

احراز هویت

احراز هویت در این API با API Key انجام می‌شود. کلید را در هدر X-API-KEY هر درخواست بفرستید:

X-API-KEY: ak_live_xxxxxxxxxxxxxxxxx

اندپوینت‌ها از نظر دسترسی دو دسته‌اند:

دسته	توضیح
عمومی	بدون هدر X-API-KEY هم پاسخ می‌دهد.
احراز هویت‌شده	بدون هدر X-API-KEY معتبر، پاسخ 401 UNAUTHENTICATED می‌گیرید.

در همه‌ی نمونه‌های این مستندات، کلید از متغیر محیطی $API_KEY خوانده می‌شود.

ساخت API Key

کلیدها از بخش API پنل کاربری ساخته می‌شوند. کلید فقط یک بار و در همان لحظه‌ی ساخت نمایش داده می‌شود و پس از آن قابل بازیابی نیست، پس همان موقع آن را در جای امنی ذخیره کنید.

نگهداری از کلید

• کلید را در Frontend قرار ندهید.
• کلید را داخل Git Repository قرار ندهید.
• کلید را در Logها چاپ نکنید.
• کلید را از متغیر محیطی بخوانید، نه از مقدار ثابت در کد.
• در صورت افشا، کلید را فوراً از پنل کاربری غیرفعال کنید و کلید تازه بسازید.

❌ نامناسب

const apiKey = 'ak_live_xxxxxxxxxxxxxxxxx';

✅ مناسب

const apiKey = process.env.ASACOINE_API_KEY;

محدود کردن کلید به IP

هنگام ساخت کلید می‌توانید فهرستی از IPهای مجاز تعیین کنید. در این حالت، درخواست‌هایی که از آدرس دیگری بیایند رد می‌شوند. برای سرویس‌هایی که IP ثابت دارند، این کار را انجام دهید.

نمونه‌ی یک درخواست احراز هویت‌شده

curl "$BASE_URL/api/v1/finance/account/overview/total-balance" \
  -H "X-API-KEY: $API_KEY"

---

دسترسی‌های حساب

بعضی اندپوینت‌ها علاوه بر احراز هویت، به یک دسترسی مشخص روی حساب کاربری نیاز دارند. هر جا چنین شرطی وجود داشته باشد، در ردیف نیاز حساب در جدول مشخصات همان اندپوینت آمده است.

دسترسی	لازم برای
فعال بودن معامله	ثبت و لغو سفارش اسپات
فعال بودن معامله‌ی طلا	خرید و فروش فلزات گرانبها
فعال بودن برداشت	برداشت رمزارز
احراز هویت پریمیوم	خرید و فروش فلزات گرانبها

اگر حساب شما دسترسی لازم را نداشته باشد، پاسخ 403 FORBIDDEN دریافت می‌کنید. این دسترسی‌ها از طریق پنل کاربری و پس از تکمیل احراز هویت حساب فعال می‌شوند.

---

محدودیت نرخ درخواست

اندپوینت‌های عمومی بازار به ازای هر آدرس IP حداکثر ۶۰۰ درخواست در دقیقه می‌پذیرند. عبور از این سقف، پاسخ 429 RATE_LIMITED برمی‌گرداند.

اگر به داده‌ی چند نماد نیاز دارید، به‌جای چند درخواست جداگانه، پارامتر symbol را چند بار در همان درخواست تکرار کنید.

نامناسب

curl -G "$BASE_URL/api/v1/market/snapshot/ticker" --data-urlencode "symbol=BTC"
curl -G "$BASE_URL/api/v1/market/snapshot/ticker" --data-urlencode "symbol=ETH"
curl -G "$BASE_URL/api/v1/market/snapshot/ticker" --data-urlencode "symbol=USDT"

مناسب

curl -G "$BASE_URL/api/v1/market/snapshot/ticker" \
  --data-urlencode "symbol=BTC" \
  --data-urlencode "symbol=ETH" \
  --data-urlencode "symbol=USDT"

---

صفحه‌بندی

اندپوینت‌های گزارش‌گیری، خروجی را صفحه‌بندی‌شده برمی‌گردانند و این دو پارامتر را می‌پذیرند:

پارامتر	نوع	توضیح
page	number	شماره‌ی صفحه؛ از ۱ شروع می‌شود.
take	number	تعداد آیتم در هر صفحه.

---

خروجی CSV

اندپوینت‌های گزارش‌گیری با افزودن ?format=csv به‌جای JSON، تمام ردیف‌ها را در قالب یک رشته‌ی CSV برمی‌گردانند.

در این حالت صفحه‌بندی نادیده گرفته می‌شود و کل داده یک‌جا ارسال می‌شود؛ بنابراین ارسال هم‌زمان format=csv با page و take بی‌اثر است.

نامناسب

curl -G "$BASE_URL/api/v1/Trade/report/spot" \
  -H "X-API-KEY: $API_KEY" \
  --data-urlencode "format=csv" \
  --data-urlencode "page=1" \
  --data-urlencode "take=50"

مناسب

curl -G "$BASE_URL/api/v1/Trade/report/spot" \
  -H "X-API-KEY: $API_KEY" \
  --data-urlencode "format=csv" \
  -o spot-orders.csv

---

قراردادهای داده

• مقادیر مالی مانند مقدار سفارش، قیمت و موجودی به‌صورت رشته ارسال و دریافت می‌شوند تا دقت اعشار حفظ شود؛ مگر آن‌که در جدول اندپوینت نوع دیگری ذکر شده باشد.
• زمان‌ها در قالب ISO-8601 و بر مبنای UTC هستند.
• شناسه‌ها مانند _id، symbolId و networkId رشته‌های ۲۴ کاراکتری هگزادسیمال هستند.
• ارزهای مظنه‌ی پشتیبانی‌شده USDT و TMN هستند و تبدیل به تومان بر اساس نرخ لحظه‌ای دلار انجام می‌شود.

مقادیر مالی را پیش از محاسبه به عدد اعشاری تبدیل نکنید؛ دقت از دست می‌رود.

نامناسب

const total = parseFloat(order.filledAmount) * parseFloat(order.finalPrice);

مناسب

import { Decimal } from 'decimal.js';

const total = new Decimal(order.filledAmount).mul(order.finalPrice).toString();

---

ساختار خطاها

هر خطا با یک کد وضعیت HTTP و یک کد متنی مشخص برمی‌گردد. کدهای زیر در سراسر API مشترک‌اند:

HTTP	کد	معنی
400	Validation failure	پارامترهای ورودی نامعتبر است.
401	UNAUTHENTICATED	اعتبارنامه ارسال نشده یا معتبر نیست.
403	FORBIDDEN	حساب شما دسترسی لازم برای این عملیات را ندارد.
404	ENT_NOT_FOUND	موجودیت درخواستی پیدا نشد.
429	RATE_LIMITED	سقف تعداد درخواست یا سهمیه‌ی مجاز پر شده است.
500	—	خطای داخلی سرور.

خطاهای اختصاصی هر اندپوینت، در جدول «خطاها»ی همان صفحه آمده است.

---

مراحل بعدی

• فهرست ارزها — نقطه‌ی شروع بیشتر یکپارچه‌سازی‌ها؛ شناسه‌ی نماد و شبکه از اینجا به دست می‌آید.
• قیمت جفت‌ارزها — قیمت لحظه‌ی همه‌ی بازارها در یک درخواست.
• ثبت سفارش اسپات — اولین سفارش خود را ثبت کنید.
• موجودی کل حساب‌ها — وضعیت دارایی‌های حساب.
• خرید فلز گرانبها — معامله‌ی طلا و فلزات گرانبها با تومان.