Genesis Arbitrage

Genesis Arbitrage · · 阅读约 12 分钟

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 限制指南。

如何获取密钥

  1. 订阅 API 套餐

    在 Genesis API 价格页面选择 Trial、Start、Pro 或 Max 以及订阅周期,点击“订阅”,并用加密货币支付账单。个人资料中的状态会变为“订阅有效”。

  2. 点击“获取密钥”

    在你还没有密钥时,按钮会出现在“Genesis API”区块中。密钥会立即创建。

  3. 在“你的 API 密钥”窗口中保存密钥

    窗口只显示一次完整密钥。点击“复制”,把密钥放进密码管理器,或直接放进服务器受保护的变量。点击“完成”后就无法再看到完整密钥:我们只保存它的哈希。

  4. 用一次请求测试密钥

    按下面的示例调用 /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 访问将被关闭。”,并提供“取消”和“确认”。如果密钥泄露:

  1. 重新生成密钥

    点击“重新生成”,再点击“确认”,然后从“你的 API 密钥”窗口保存新密钥。从这一刻起,使用旧密钥的请求会得到 401。

  2. 在每个程序中替换密钥

    更新环境变量、.env 文件以及 CI 和托管平台的机密,然后重启程序:进程在启动时读取环境变量。如果某个程序仍在发送旧密钥,请检查环境中是否已经设置了 GENESIS_API_KEY:python-dotenv 和 node --env-file 不会用 .env 中的值覆盖已设置的变量。

  3. 检查调用用量

    个人资料中的“已用调用次数”一行,或对 /account/usage 的请求,会显示本周期已用了多少次调用。重新生成密钥不会重置计数器。

401 invalid_key:检查什么

当密钥缺失、错误或已被撤销,或订阅已过期时,服务器会返回 401 和 invalid_key 代码:

{
  "success": false,
  "error": {
    "code": "invalid_key",
    "message": "Missing X-API-Key header."
  }
}

如果请求头已送达但密钥被拒绝,message 会一次列出所有可能的原因。403 plan_restricted 的含义不同:密钥已被接受,但该接口不在你的套餐内。其他代码见错误部分和 Genesis API 响应与错误指南。

文档中的“在线试用”表单

文档中的每个接口都有“在线试用”表单。把密钥粘贴到“你的 API 密钥(gns_live_…)”字段,点击“发送请求”:状态码、响应时间和截断后的响应会显示在表单下方。密钥仅保存在你的浏览器中,除 API 外不会发送到任何地方。

浏览器会记住密钥,并在你下次访问时自动填入字段,所以不要在别人的电脑上使用该表单。表单发出的请求就是普通的 API 调用:和代码发出的请求一样,会占用额度和每秒请求数限制。你从代码发出的第一个请求及响应说明见 Genesis API 快速入门。

常见问题

可以给每个机器人单独一个密钥吗?

不可以,每个账户只有一个密钥。使用该密钥的所有程序共享调用额度和每秒请求数限制。如果限制太紧,请升级套餐:开多个账户来绕过限制违反规则。

重新生成密钥会重置调用计数器吗?

不会。“已用调用次数”属于账户的订阅,而不是密钥:新密钥沿用同一个 30 天周期。

请求头可以用小写的 x-api-key 吗?

可以。HTTP 请求头名称不区分大小写,这是 RFC 9110 第 5.1 节规定的规则。密钥本身必须原样发送。

续订后需要新密钥吗?

不需要。订阅过期期间密钥会得到 401,点击“续订”后同一个密钥会重新可用。