مرجع API ارز دیجیتال CoinMarketCap

این اسکیل، اندپوینت‌های ارز دیجیتال CoinMarketCap را پوشش می‌دهد: داده قیمت، فهرست‌های بازار، قیمت‌های تاریخی، ارزهای ترند و متادیتای توکن.

■ احراز هویت
همه درخواست‌ها به کلید API در هدر نیاز دارند:

curl -X GET "https://pro-api.coinmarketcap.com/v1/cryptocurrency/listings/latest" \
  -H "X-CMC_PRO_API_KEY: کلید-شما"

کلید از https://pro.coinmarketcap.com/login گرفته می‌شود.

■ آدرس پایه
https://pro-api.coinmarketcap.com

■ کاربردهای رایج
۱. گرفتن قیمت فعلی یک توکن
۲. یافتن شناسه CMC از نماد یا نام
۳. گرفتن توکن با آدرس قرارداد
۴. صد ارز برتر بر اساس ارزش بازار
۵. یافتن ارزها در یک بازه قیمتی
۶. قیمت تاریخی در یک تاریخ مشخص
۷. ساخت نمودار قیمت (داده OHLCV)
۸. یافتن اینکه یک ارز کجا معامله می‌شود
۹. سقف تاریخی و فاصله فعلی از آن
۱۰. بیشترین رشدهای امروز
۱۱. کشف ارزهای تازه‌فهرست‌شده
۱۲. همه توکن‌های یک دسته (مثلاً دیفای)

■ فهرست اندپوینت‌ها

| اندپوینت | توضیح |
| GET /v1/cryptocurrency/categories | فهرست همه دسته‌ها با سنجه‌های بازار |
| GET /v1/cryptocurrency/category | جزئیات یک دسته |
| GET /v1/cryptocurrency/listings/historical | تصویر تاریخی فهرست‌ها |
| GET /v1/cryptocurrency/listings/latest | فهرست فعلی با داده بازار |
| GET /v1/cryptocurrency/listings/new | ارزهای تازه‌افزوده |
| GET /v1/cryptocurrency/map | نگاشت نام و نماد به شناسه CMC |
| GET /v1/cryptocurrency/trending/gainers-losers | بیشترین رشد و افت |
| GET /v1/cryptocurrency/trending/latest | ارزهای ترند فعلی |
| GET /v1/cryptocurrency/trending/most-visited | پربازدیدترین‌ها در CMC |
| GET /v2/cryptocurrency/info | متادیتای ثابت (لوگو، توضیح، لینک‌ها) |
| GET /v2/cryptocurrency/market-pairs/latest | جفت‌های معاملاتی یک ارز |
| GET /v2/cryptocurrency/ohlcv/historical | کندل‌های تاریخی |
| GET /v2/cryptocurrency/ohlcv/latest | آخرین داده OHLCV |
| GET /v2/cryptocurrency/price-performance-stats/latest | آمار عملکرد قیمت |
| GET /v2/cryptocurrency/quotes/latest | آخرین قیمت‌ها |
| GET /v3/cryptocurrency/quotes/historical | قیمت‌های تاریخی |

■ گردش کارهای رایج

گرفتن قیمت توکن با نماد:
۱. نماد را با /v1/cryptocurrency/map به شناسه CMC تبدیل کن.
۲. قیمت را با /v2/cryptocurrency/quotes/latest بگیر.

# گام ۱: گرفتن شناسه ETH
curl -X GET "https://pro-api.coinmarketcap.com/v1/cryptocurrency/map?symbol=ETH" -H "X-CMC_PRO_API_KEY: کلید"
# گام ۲: گرفتن قیمت (شناسه ۱۰۲۷ برای ETH)
curl -X GET "https://pro-api.coinmarketcap.com/v2/cryptocurrency/quotes/latest?id=1027" -H "X-CMC_PRO_API_KEY: کلید"

صد ارز برتر بر اساس ارزش بازار:
curl -X GET "https://pro-api.coinmarketcap.com/v1/cryptocurrency/listings/latest?limit=100&sort=market_cap" -H "X-CMC_PRO_API_KEY: کلید"

داده تاریخی:
curl -X GET "https://pro-api.coinmarketcap.com/v3/cryptocurrency/quotes/historical?id=1&time_start=2024-01-01&time_end=2024-01-31&interval=daily" -H "X-CMC_PRO_API_KEY: کلید"

متادیتای توکن:
curl -X GET "https://pro-api.coinmarketcap.com/v2/cryptocurrency/info?id=1,1027" -H "X-CMC_PRO_API_KEY: کلید"

■ مدیریت خطا

کدهای وضعیت:
۲۰۰ موفق | ۴۰۰ درخواست نامعتبر | ۴۰۱ کلید نامعتبر | ۴۰۳ اندپوینت در پلن شما نیست | ۴۲۹ عبور از محدودیت نرخ | ۵۰۰ خطای سرور

محدودیت نرخ:
به پلن اشتراک بستگی دارد. هدرهای پاسخ شامل این‌هاست:
X-CMC_PRO_API_KEY_CREDITS_USED — اعتبار مصرف‌شده در این فراخوانی
X-CMC_PRO_API_KEY_CREDITS_LEFT — اعتبار باقی‌مانده

خطاهای رایج:
- شناسه نامعتبر: از شناسه‌های معتبر اندپوینت map استفاده کن؛ جستجو با نماد ممکن است چند نتیجه بدهد.
- پارامتر اجباری غایب: برخی اندپوینت‌ها حداقل یک شناسه (id، slug یا symbol) می‌خواهند.
- محدودیت پلن: اندپوینت‌های تاریخی و برخی امکانات نیازمند پلن پولی هستند.

قالب پاسخ خطا:
{ "status": { "timestamp": "...", "error_code": 400, "error_message": "Invalid value for 'id'", "credit_count": 0 } }

■ قالب پاسخ موفق
{ "status": { "timestamp": "...", "error_code": 0, "error_message": null, "credit_count": 1 }, "data": { ... } }

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