کلید Genesis API: چگونه بگیریم، کجا نگه داریم و چگونه دوباره صادر یا باطل کنیم
به طور خلاصه
- کلید
gns_live_…در پروفایل شما با دکمه «دریافت کلید» ساخته میشود و فقط یک بار نمایش داده میشود. ما فقط هش آن را نگه میداریم؛ کلید گمشده بازیابی نمیشود و فقط دوباره صادر میشود. - کلید در هدر
X-API-Keyاز سرور خودتان ارسال میشود. کد آن را از متغیر محیطیGENESIS_API_KEYمیخواند و هرگز در آدرس درخواست یا کد وبسایت قرار نمیگیرد. - اگر کلید نشت کرد، «صدور مجدد» را بزنید: کلید قبلی بیدرنگ از کار میافتد و شما آن را در همه برنامهها عوض میکنید. هر حساب یک کلید دارد.
کلید API برای Genesis API رشتهای به شکل gns_live_… است که مثل رمز عبور کار میکند: سرور با آن حساب و پلن شما را تشخیص میدهد. آن را با هر درخواست در هدر HTTP به نام X-API-Key میفرستید؛ بدون کلید یا با کلید نادرست، API خطای 401 invalid_key برمیگرداند. هر حساب یک کلید دارد و آن را در پروفایل Genesis Arbitrage میگیرید، دوباره صادر میکنید و باطل میکنید.
کلید کجاست
کلید را در پروفایل، در بخش «Genesis API» مدیریت میکنید؛ بخشهای دیگر پروفایل در راهنمای پروفایل حساب آمدهاند. این بخش اشتراک API و وضعیت کلید را نشان میدهد:
| آنچه میبینید | معنی |
|---|---|
| «اشتراک غیرفعال»، دکمه «خرید اشتراک» | هنوز پلن API ندارید؛ دکمه صفحهٔ پلنها را باز میکند |
| «اشتراک فعال»، «فعال تا …»، دکمه «تمدید» | پلن تا این تاریخ معتبر است |
| «اشتراک منقضی شد»، دکمه «تمدید» | مدت تمام شده است: کلید رد میشود و دکمههای کلید تا تمدید پنهاناند |
| «هنوز کلیدی ساخته نشده»، دکمه «دریافت کلید» | پلن دارید اما هنوز کلید ندارید |
«کلید API» و gns_live_… | ابتدای کلید فعال؛ کلید کامل دیگر نشان داده نمیشود |
| «ساختهشده …» · «استفادهشده …» | زمان ساخت کلید و زمان آخرین درخواست آن |
| «فراخوانیهای مصرفشده»، «req/s»، «freshness»، «بازنشانی …» | سهمیهٔ مصرفشده، سقف درخواست در ثانیه، تأخیر داده و تاریخ بازنشانی شمارنده |
پیوند «مستندات» در گوشهٔ این بخش مستندات Genesis API را باز میکند. سهمیه و محدودیتها در راهنمای محدودیتهای Genesis API توضیح داده شدهاند.
چگونه کلید بگیریم
اشتراک پلن API بگیرید
در صفحهٔ قیمتهای Genesis API یکی از Trial، Start، Pro یا Max و یک دوره را انتخاب کنید، «خرید اشتراک» را بزنید و فاکتور را با ارز دیجیتال بپردازید. وضعیت در پروفایل شما به «اشتراک فعال» تغییر میکند.
«دریافت کلید» را بزنید
تا وقتی کلیدی ندارید، این دکمه در بخش «Genesis API» دیده میشود. کلید بلافاصله ساخته میشود.
کلید را از پنجرهٔ «کلید API شما» ذخیره کنید
پنجره کلید کامل را یک بار نشان میدهد. «کپی» را بزنید و کلید را در مدیر رمز عبور یا مستقیم در متغیرهای محافظتشدهٔ سرورتان بگذارید. پس از «تمام» دیگر کلید کامل را نمیبینید: ما فقط هش آن را نگه میداریم.
کلید را با یک درخواست آزمایش کنید
/account/usageرا مثل نمونههای زیر فراخوانی کنید. پاسخ200با پلن شما درdata.planیعنی کلید پذیرفته شده است.
چگونه کلید را بفرستیم
کلید فقط در هدر X-API-Key میرود. سرور کلید را از پارامترهای آدرس یا از هدر Authorization نمیخواند و 401 میدهد. نمونهها کلید را از متغیر محیطی GENESIS_API_KEY میخوانند؛ آدرس پایه https://api.genesisarbitrage.com/v1 است.
curl:
# the key comes from an environment variable
curl "https://api.genesisarbitrage.com/v1/account/usage" \
-H "X-API-Key: $GENESIS_API_KEY"
Python 3.10+ با کتابخانهٔ requests:
import os
import requests
# os.environ[...] fails right away if the variable is not set
key = os.environ["GENESIS_API_KEY"]
r = requests.get(
"https://api.genesisarbitrage.com/v1/account/usage",
headers={"X-API-Key": key},
timeout=10,
)
r.raise_for_status()
print(r.json()["data"]["plan"])
JavaScript، Node.js 18+ با fetch داخلی:
// .mjs file: modules allow top-level await
const key = process.env.GENESIS_API_KEY;
if (!key) throw new Error('GENESIS_API_KEY is not set');
const res = await fetch(
'https://api.genesisarbitrage.com/v1/account/usage',
{ headers: { 'X-API-Key': key } },
);
const body = await res.json();
console.log(res.status, body.data?.plan);
هر سه درخواست یک پاسخ برمیگردانند (مقادیر نمونه):
{
"success": true,
"data": {
"plan": "pro",
"calls_used": 184201,
"calls_limit": 5000000,
"rps_limit": 5,
"freshness_sec": 10,
"period_resets_at": 1786492800
},
"meta": { … }
}
فیلدهای پاسخ در بخش مصرف مستندات شرح داده شدهاند.
کلید را کجا نگه داریم
کلید Genesis API فقط داده میخواند: با آن نمیتوان معامله کرد یا پول برداشت. اما نشت آن چیز دیگری از شما میگیرد: برنامههای دیگران سهمیه و سقف درخواست در ثانیهٔ شما را مصرف میکنند.
| مکان | مناسب است | چرا |
|---|---|---|
| متغیر محیطی روی سرور | بله | کلید بیرون از کد و مخزن میماند |
فایل .env در .gitignore | بله | python-dotenv (load_dotenv()) و node --env-file=.env در Node.js 20.6+ آن را بارگذاری میکنند |
| رازهای هاستینگ و CI | بله | پلتفرم هنگام اجرا کلید را به برنامه میدهد؛ در GitHub Actions، راز مخزن که از طریق env گام پاس داده میشود |
| مدیر رمز عبور | بله | نسخهٔ پشتیبان برای انسان |
| آدرس درخواست | خیر | آدرسها در لاگ سرور و پروکسی و تاریخچهٔ مرورگر میمانند |
| کد وبسایت، افزونه یا اپ موبایل | خیر | هر کس سورس صفحه را ببیند یا اپ را باز کند، کلید را میبیند |
| مخزن عمومی | خیر | کلید حتی پس از حذف فایل در تاریخچهٔ commitها میماند |
| اسکرینشات، چت، تیکت پشتیبانی | خیر | پیامها و تصاویر دستبهدست میشوند |
اگر داده باید به مرورگر برسد، مثلاً در داشبورد یا افزونه، سرور شما Genesis API را فراخوانی میکند و مرورگر نتیجهٔ آماده را از سرور شما میگیرد. پشتیبانی به X-Request-Id پاسخ، زمان درخواست به UTC، endpoint و وضعیت نیاز دارد، هرگز به کلید. کلیدهای صرافی با دسترسی معامله پرخطرترند؛ نحوهٔ محدود کردن آنها در امنیت حساب صرافی ارز دیجیتال آمده است.
صدور مجدد و ابطال
| دکمه | چه میشود | کی استفاده کنیم |
|---|---|---|
| «صدور مجدد» | کلید قبلی بیدرنگ از کار میافتد و پنجرهٔ «کلید API شما» کلید جدید را نشان میدهد | کلید نشت کرده یا گم شده، یا کسی که آن را داشت رفته است |
| «ابطال» | کلید بدون جایگزین خاموش میشود و دسترسی به API بسته میشود؛ بخش دوباره «دریافت کلید» را نشان میدهد | دیگر به کلید نیاز ندارید |
هر دو دکمه اول تأیید میخواهند. متن پنجرهها این است: «کلید دوباره صادر شود؟ کلید فعلی بیدرنگ از کار میافتد.» و «کلید باطل شود؟ بیدرنگ از کار میافتد و دسترسی به API بسته میشود.» با گزینههای «انصراف» و «تأیید». اگر کلید نشت کرد:
کلید را دوباره صادر کنید
«صدور مجدد» و سپس «تأیید» را بزنید و کلید جدید را از پنجرهٔ «کلید API شما» ذخیره کنید. از آن لحظه درخواستهای با کلید قبلی
401میگیرند.کلید را در همه برنامهها عوض کنید
متغیرهای محیطی، فایلهای
.envو رازهای CI و هاستینگ را بهروز کنید و برنامهها را دوباره راه بیندازید: فرایند محیطش را هنگام شروع میخواند. اگر برنامهای هنوز کلید قبلی را میفرستد، بررسی کنید کهGENESIS_API_KEYاز قبل در محیط تنظیم نشده باشد: python-dotenv وnode --env-fileمتغیری را که از قبل تنظیم شده با مقدار.envجایگزین نمیکنند.مصرف فراخوانیها را بررسی کنید
سطر «فراخوانیهای مصرفشده» در پروفایل یا درخواست به
/account/usageنشان میدهد در این دوره چند فراخوانی مصرف شده است. صدور مجدد شمارنده را صفر نمیکند.
401 invalid_key: چه چیزهایی را بررسی کنیم
سرور وقتی کلید نیست، نادرست یا باطل شده است، یا اشتراک منقضی شده، با کد invalid_key پاسخ 401 میدهد:
{
"success": false,
"error": {
"code": "invalid_key",
"message": "Missing X-API-Key header."
}
}
- هدر نرسیده است. «Missing X-API-Key header.» یعنی درخواست اصلاً کلیدی نداشته است. نام هدر را بررسی کنید و اینکه متغیر در جایی که برنامه اجرا میشود تنظیم شده باشد: روی سرور، در کانتینر، در کار زمانبندیشده.
- کلید خراب شده است. یک فاصلهٔ اضافه، گیومه داخل مقدار یا انتهای بریدهشده
401میدهد: کلید باید کاراکتر به کاراکتر یکی باشد. - کلید دوباره صادر یا باطل شده است. ابتدای کلید در برنامهتان را با ابتدای کلیدی که پروفایل زیر «کلید API» نشان میدهد مقایسه کنید.
- اشتراک منقضی شده است. پروفایل «اشتراک منقضی شد» را نشان میدهد. پس از «تمدید» همان کلید دوباره کار میکند و نیازی به صدور مجدد نیست.
اگر هدر رسیده اما کلید رد شده، message همهٔ دلایل ممکن را یکجا فهرست میکند. پاسخ 403 plan_restricted یعنی چیز دیگری: کلید پذیرفته شده، اما endpoint جزو پلن شما نیست. کدهای دیگر در بخش خطاها و راهنمای پاسخها و خطاهای Genesis API آمدهاند.
فرم «امتحان کنید» در مستندات
هر endpoint در مستندات فرم «امتحان کنید» دارد. کلید را در فیلد «کلید API شما (gns_live_…)» بچسبانید و «ارسال درخواست» را بزنید: کد وضعیت، زمان پاسخ و پاسخ کوتاهشده زیر فرم ظاهر میشود. کلید فقط در مرورگر شما ذخیره میشود و جایی جز API فرستاده نمیشود.
مرورگر کلید را به خاطر میسپارد و دفعهٔ بعد فیلد را پر میکند؛ پس از فرم روی رایانهٔ دیگران استفاده نکنید. درخواست از فرم یک فراخوانی عادی API است: مثل درخواست از کد، سهمیه و سقف درخواست در ثانیه را مصرف میکند. نخستین درخواست شما از کد، با توضیح پاسخ، در شروع سریع Genesis API است.
پرسش و پاسخ
آیا برای هر ربات میتوان کلید جدا داشت؟
خیر، هر حساب یک کلید دارد. همهٔ برنامههایی که از آن استفاده میکنند سهمیهٔ فراخوانی و سقف درخواست در ثانیه را بین خود تقسیم میکنند. اگر محدودیتها تنگ است، پلن را ارتقا دهید: باز کردن چند حساب برای دور زدن محدودیتها قوانین را نقض میکند.
آیا صدور مجدد شمارندهٔ فراخوانی را صفر میکند؟
خیر. «فراخوانیهای مصرفشده» به اشتراک حساب تعلق دارد، نه به کلید: کلید جدید همان دورهٔ 30 روزه را ادامه میدهد.
آیا میتوان هدر را با حروف کوچک x-api-key نوشت؟
بله. نام هدرهای HTTP به بزرگی و کوچکی حروف حساس نیست؛ این قاعده را RFC 9110، بخش 5.1 تعیین کرده است. خود کلید باید بدون تغییر ارسال شود.
آیا پس از تمدید کلید جدید لازم است؟
خیر. تا وقتی اشتراک منقضی است کلید 401 میگیرد و پس از «تمدید» همان کلید دوباره کار میکند.