Genesis API 密钥:如何获取、存放、重新生成与撤销
简而言之
gns_live_…密钥在个人资料中点击“获取密钥”创建,只显示一次。我们只保存它的哈希,所以丢失的密钥无法找回,只能重新生成。- 密钥通过
X-API-Key请求头从你自己的服务器发送。代码从环境变量GENESIS_API_KEY读取密钥;密钥绝不能出现在请求 URL 或网站代码中。 - 密钥一旦泄露,点击“重新生成”:旧密钥立即失效,你需要在每个程序中替换它。每个账户只有一个密钥。
Genesis API 的 API 密钥是一串 gns_live_… 字符,作用类似密码:服务器靠它识别你的账户和套餐。每次请求都要通过 X-API-Key HTTP 请求头发送密钥;缺少密钥或密钥错误时,API 返回 401 invalid_key。每个账户只有一个密钥,你可以在 Genesis Arbitrage 个人资料中获取、重新生成和撤销它。
密钥在哪里管理
密钥在个人资料的“Genesis API”区块中管理;个人资料的其他区块见账户个人资料指南。该区块显示你的 API 订阅和密钥状态:
| 你看到的内容 | 含义 |
|---|---|
| “订阅未生效”,“订阅”按钮 | 还没有 API 套餐;按钮会打开套餐列表 |
| “订阅有效”,“有效期至 …”,“续订”按钮 | 套餐在该日期前有效 |
| “订阅已过期”,“续订”按钮 | 期限已结束:密钥会被拒绝,续订前密钥按钮隐藏 |
| “尚未创建密钥”,“获取密钥”按钮 | 已有套餐,但还没有密钥 |
“API 密钥”和 gns_live_… | 当前密钥的开头部分;完整密钥不会再次显示 |
| “创建于 …”·“最近使用 …” | 密钥的创建时间和最近一次发出请求的时间 |
| “已用调用次数”,“次/秒”,“数据延迟”,“重置时间 …” | 已用额度、每秒请求数限制、数据延迟,以及计数器重置的日期 |
区块角落的“文档”链接会打开 Genesis API 文档。额度和限制见 Genesis API 限制指南。
如何获取密钥
订阅 API 套餐
在 Genesis API 价格页面选择 Trial、Start、Pro 或 Max 以及订阅周期,点击“订阅”,并用加密货币支付账单。个人资料中的状态会变为“订阅有效”。
点击“获取密钥”
在你还没有密钥时,按钮会出现在“Genesis API”区块中。密钥会立即创建。
在“你的 API 密钥”窗口中保存密钥
窗口只显示一次完整密钥。点击“复制”,把密钥放进密码管理器,或直接放进服务器受保护的变量。点击“完成”后就无法再看到完整密钥:我们只保存它的哈希。
用一次请求测试密钥
按下面的示例调用
/account/usage。如果返回200,并且data.plan中是你的套餐,说明密钥已被接受。
如何发送密钥
密钥只能放在 X-API-Key 请求头中。服务器不会从 URL 参数或 Authorization 请求头读取密钥,并会返回 401。示例从环境变量 GENESIS_API_KEY 读取密钥;基础 URL 为 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 密钥只能读取数据:用它无法交易或提币。泄露的代价在别处:别人的程序会耗尽你的额度和每秒请求数限制。
| 位置 | 是否可以 | 原因 |
|---|---|---|
| 服务器上的环境变量 | 可以 | 密钥不进入代码和代码仓库 |
列入 .gitignore 的 .env 文件 | 可以 | 由 python-dotenv(load_dotenv())加载,Node.js 20.6+ 中也可用 node --env-file=.env |
| 托管平台和 CI 的机密变量 | 可以 | 平台在程序启动时提供密钥;在 GitHub Actions 中,通过步骤的 env 传入仓库机密 |
| 密码管理器 | 可以 | 供人查看的备份 |
| 请求 URL | 不可以 | URL 会进入服务器和代理日志以及浏览器历史记录 |
| 网站、扩展或移动应用的代码 | 不可以 | 任何人查看页面源码或解包应用都能看到密钥 |
| 公开仓库 | 不可以 | 即使删除文件,密钥仍留在提交历史中 |
| 截图、聊天、客服工单 | 不可以 | 消息和图片会被转发 |
如果数据需要送到浏览器,例如仪表盘或扩展,就由你的服务器调用 Genesis API,浏览器从你的服务器获取处理好的结果。联系支持时需要提供响应中的 X-Request-Id、UTC 请求时间、接口和状态,永远不要提供密钥。带交易权限的交易所密钥风险更高;如何限制它们见如何保护你的加密货币交易所账户。
重新生成与撤销
| 按钮 | 会发生什么 | 何时使用 |
|---|---|---|
| “重新生成” | 旧密钥立即失效,“你的 API 密钥”窗口显示新密钥 | 密钥泄露或丢失,或持有它的人已离开 |
| “撤销” | 密钥被关闭且没有替代,API 访问被关闭;区块再次显示“获取密钥” | 你不再需要这个密钥 |
两个按钮都会先要求确认。对话框内容为“重新生成密钥?当前密钥将立即失效。”和“撤销密钥?密钥将立即失效,API 访问将被关闭。”,并提供“取消”和“确认”。如果密钥泄露:
重新生成密钥
点击“重新生成”,再点击“确认”,然后从“你的 API 密钥”窗口保存新密钥。从这一刻起,使用旧密钥的请求会得到
401。在每个程序中替换密钥
更新环境变量、
.env文件以及 CI 和托管平台的机密,然后重启程序:进程在启动时读取环境变量。如果某个程序仍在发送旧密钥,请检查环境中是否已经设置了GENESIS_API_KEY:python-dotenv 和node --env-file不会用.env中的值覆盖已设置的变量。检查调用用量
个人资料中的“已用调用次数”一行,或对
/account/usage的请求,会显示本周期已用了多少次调用。重新生成密钥不会重置计数器。
401 invalid_key:检查什么
当密钥缺失、错误或已被撤销,或订阅已过期时,服务器会返回 401 和 invalid_key 代码:
{
"success": false,
"error": {
"code": "invalid_key",
"message": "Missing X-API-Key header."
}
}
- 请求头没有送达。 “Missing X-API-Key header.” 表示请求根本没带密钥。检查请求头名称,以及程序运行的位置是否设置了该变量:服务器、容器、定时任务。
- 密钥被改坏。 多余的空格、值里的引号或被截断的末尾都会导致
401:密钥必须逐字符一致。 - 密钥已被重新生成或撤销。 把程序中密钥的开头与个人资料“API 密钥”下显示的开头对比。
- 订阅已过期。 个人资料显示“订阅已过期”。点击“续订”后,同一个密钥会重新可用,无需重新生成。
如果请求头已送达但密钥被拒绝,message 会一次列出所有可能的原因。403 plan_restricted 的含义不同:密钥已被接受,但该接口不在你的套餐内。其他代码见错误部分和 Genesis API 响应与错误指南。
文档中的“在线试用”表单
文档中的每个接口都有“在线试用”表单。把密钥粘贴到“你的 API 密钥(gns_live_…)”字段,点击“发送请求”:状态码、响应时间和截断后的响应会显示在表单下方。密钥仅保存在你的浏览器中,除 API 外不会发送到任何地方。
浏览器会记住密钥,并在你下次访问时自动填入字段,所以不要在别人的电脑上使用该表单。表单发出的请求就是普通的 API 调用:和代码发出的请求一样,会占用额度和每秒请求数限制。你从代码发出的第一个请求及响应说明见 Genesis API 快速入门。
常见问题
可以给每个机器人单独一个密钥吗?
不可以,每个账户只有一个密钥。使用该密钥的所有程序共享调用额度和每秒请求数限制。如果限制太紧,请升级套餐:开多个账户来绕过限制违反规则。
重新生成密钥会重置调用计数器吗?
不会。“已用调用次数”属于账户的订阅,而不是密钥:新密钥沿用同一个 30 天周期。
请求头可以用小写的 x-api-key 吗?
可以。HTTP 请求头名称不区分大小写,这是 RFC 9110 第 5.1 节规定的规则。密钥本身必须原样发送。
续订后需要新密钥吗?
不需要。订阅过期期间密钥会得到 401,点击“续订”后同一个密钥会重新可用。