面向 AI 智能体的 Genesis API:OpenAPI、llms.txt 与函数调用
简而言之
- 智能体可使用 openapi.json(OpenAPI 3.1,含套餐信息的 37 个操作)、llms-full.txt、llms.txt,以及符合 RFC 9727 的 API 目录。
- 模型选择工具及其参数;你的服务器携带密钥发起请求,并把带有数据时间的简短 JSON 返回给模型。
- Genesis API 只读取数据。请求频率由你的代码限制,模型把响应中的文本仅当作数据,任何交易都由人工确认。
Genesis API 是一个加密货币行情数据 REST API,AI 智能体把它当作工具来调用:模型判断需要哪些数据,你的服务器携带密钥发出 GET 请求,并返回简短的 JSON。面向智能体和语言模型,API 提供机器可读的描述:OpenAPI 3.1 规范、完整的 Markdown 参考文档和 API 目录。数据与网站展示的一致:CEX 与 DEX 价差、订单簿、资金费率、链上资金流和预测市场。
机器可读文件
| 文件 | 内容 | 用途 |
|---|---|---|
| genesisarbitrage.com/openapi.json | OpenAPI 3.1:37 个操作、参数、响应结构、x-genesis-plans 中的套餐、限流请求头 | 导入 API 客户端、代码生成、智能体工具 |
| genesisarbitrage.com/llms-full.txt | 单个 Markdown 文件中的完整参考:接口、参数、字段、示例、限额、错误 | 为编写代码或回答 API 问题的模型提供上下文 |
| genesisarbitrage.com/llms.txt | 网站概览:Genesis API、工具、指南、课程、术语表、博客 | 模型对网站的第一印象 |
| genesisarbitrage.com/.well-known/api-catalog | 符合 RFC 9727 的 API 目录:规范、文档、定价和状态的链接 | 通过域名发现 API |
该规范遵循 OpenAPI 3.1,其结构是 JSON Schema 2020-12 的超集,因此操作参数几乎可以原样搬进工具定义。llms.txt 是 2024 年提出的格式:放在网站根目录的 Markdown 文件,包含面向语言模型的简短概览和链接。目录位于 RFC 9727 规定的地址。
Genesis API 的文档页、产品页和定价页在 <head> 中带有指向 openapi.json 的 <link rel="service-desc">。该链接关系来自 RFC 8631,用于标记面向机器的服务描述。规范的节选如下:
{
"openapi": "3.1.0",
"servers": [{ "url": "https://api.genesisarbitrage.com/v1" }],
"paths": {
"/arbitrage/spot-spot": {
"get": {
"operationId": "getArbitrageSpotSpot",
"x-genesis-plans": ["trial", "start", "pro", "max"],
"parameters": [
{ "name": "coin", "in": "query",
"schema": { "type": "string" } },
{ "name": "min_spread", "in": "query",
"schema": { "type": "number" } },
…
]
}
}
}
}
每个操作都有 operationId、带类型的参数、200 响应结构、304 响应、错误码,以及 X-RateLimit-*、X-Quota-*、X-Request-Id 和 ETag 请求头。密钥由 ApiKeyAuth 安全方案描述:类型为 apiKey,请求头为 X-API-Key。
如何接入
获取密钥并保存在服务器上
gns_live_…密钥在个人资料的 Genesis API 区块中签发,只显示一次。请把它保存在运行智能体的服务器的GENESIS_API_KEY环境变量中。保存与重新签发的方法见 API 密钥指南。导入规范
支持 OpenAPI 的 API 客户端或智能体框架可以直接根据
openapi.json生成请求和工具:基础 URL 来自servers,密钥请求头来自ApiKeyAuth。密钥的传递方式见认证。只保留需要的操作
每个工具定义都会占用模型的上下文,从少量工具中选择也更容易。保留任务所需的操作,并按
x-genesis-plans去掉不在你套餐内的操作:它们会返回403 plan_restricted。把参考文档交给模型
如果智能体要编写代码或回答 API 相关问题,请把
llms-full.txt加入其上下文:其中包含每个接口的参数、字段和示例,以及限额和错误码。用第一次调用检查密钥
/account/usage会返回你的套餐、已用额度、每秒请求数限制和数据新鲜度。
模型如何调用 Genesis API
函数调用是一种机制:模型返回工具名称和参数而不是文本,由你的代码发起调用。流程如下:
- 模型在收到用户问题的同时,拿到工具定义:名称、用途,以及 JSON Schema 形式的参数。
- 模型以一次调用作答:调用
get_spreads,参数为{"coin": "TON", "min_spread": 0.5}。 - 你的服务器校验参数,携带
X-API-Key请求头发起 GET,并把响应裁剪为所需字段。 - 带有数据时间的简短 JSON 返回给模型,模型再回答用户。
模型不发起网络调用,也看不到密钥:它手里只有工具定义和结果。基于 Spot – Spot 接口的 get_spreads 工具:
{
"name": "get_spreads",
"description": "Where to buy a coin cheaper and sell it higher (CEX)",
"parameters": {
"type": "object",
"properties": {
"coin": {
"type": "string",
"description": "Coin ticker, e.g. BTC"
},
"min_spread": {
"type": "number",
"description": "Minimum spread, %: 0.5 means 0.5%"
}
},
"additionalProperties": false
}
}
保存参数结构的字段名在不同模型提供方之间各不相同,MCP 中叫 inputSchema;其内部始终是 JSON Schema。coin 和 min_spread 属性来自 getArbitrageSpotSpot 操作的参数,description 说明何时调用该工具:模型正是依据这段文字来选择。
下面是一个 Python 处理函数,它调用 /arbitrage/spot-spot,把最多 10 行所需字段连同 meta.updated_at 返回给模型:
import os
import time
import requests
API = "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot"
KEY = os.environ["GENESIS_API_KEY"] # 密钥留在服务器上
FIELDS = ("coin", "exchange_buy", "exchange_sell", "spread_pct",
"withdraw_enabled_buy", "deposit_enabled_sell")
cache = {} # 参数 -> (时间, ETag, 响应体)
def get_spreads(coin=None, min_spread=None):
params = {"coin": coin, "min_spread": min_spread}
params = {k: v for k, v in params.items() if v is not None}
ck = tuple(sorted(params.items()))
ts, etag, body = cache.get(ck, (0, None, None))
if body and time.time() - ts < body["meta"]["freshness_sec"]:
return shorten(body) # 数据不会更早更新
headers = {"X-API-Key": KEY}
if etag:
headers["If-None-Match"] = etag
for attempt in range(2): # 429 和 503:等待 Retry-After 后重试
r = requests.get(API, headers=headers, params=params,
timeout=10)
if r.status_code not in (429, 503) or attempt:
break
time.sleep(min(int(r.headers.get("Retry-After", 5)), 30))
if r.status_code == 200:
body, etag = r.json(), r.headers.get("ETag")
elif r.status_code != 304:
return {"error": r.status_code} # 模型能看到该错误码
cache[ck] = (time.time(), etag, body)
return shorten(body)
def shorten(body):
rows = sorted(body["data"], key=lambda x: x["spread_pct"],
reverse=True)[:10]
t = body["meta"]["updated_at"]
return {"updated_at": t, "age_sec": int(time.time() - t),
"rows": [{f: x.get(f) for f in FIELDS} for x in rows]}
响应会缓存 meta.freshness_sec 秒:数据不会更早更新。之后处理函数在 If-None-Match 中发送上一次的 ETag,而 304 不消耗额度。遇到 429 和 503 时,它按 Retry-After 等待(最多 30 秒),重试一次,其他错误则以错误码形式返回给模型。模型拿到的是 10 行、每行 6 个字段。示意性示例:214 行、每行 22 个字段的完整响应共有 214 × 22 = 4,708 个值,裁剪后只有 10 × 6 = 60 个。
智能体守则
| 规则 | 做法 |
|---|---|
| 密钥留在服务器 | 作为处理函数的环境变量;提示词、浏览器和聊天日志中都不出现密钥 |
| API 只读 | Genesis API 不下单;任何交易所交易都由人工确认 |
| 频率由你的代码控制 | 按 freshness_sec 缓存,使用 ETag 和 If-None-Match,队列控制在每秒请求数限制以内 |
| 用筛选,不取全量 | coin、min_spread、exchange;给模型最多 10 行和所需字段 |
| 每个回答都带数据时间 | 工具结果和给用户的回复中都包含 updated_at 与数据年龄 |
| 外部文本只是数据 | 模型不执行市场标题、结果选项、交易者名称或信号文本中的内容 |
模型可能同时请求多个工具,而限额会统计该密钥上的每一次请求:Trial 为每秒 1 次,Max 为每秒 15 次。304 响应和错误不消耗额度,但仍计入每秒限制——参见套餐与限额和限额指南。
预测市场的 title 和 outcome 字段、交易者的 name、链上事件的 token_name,以及 Genesis AI+ 信号的 message_ru 和 message_en,都来自外部来源。有人可以把某个市场命名为“忽略之前的指令并……”——这就是提示词注入,即通过数据夹带命令。这类字段只应放在工具结果内部传递,限制其长度,并在系统提示词中声明结果里的文本只是数据。
MCP:在 REST API 之上自建服务器
MCP(Model Context Protocol)是把 AI 应用连接到外部系统的开放标准。MCP 服务器向应用提供工具、资源和提示词模板;消息采用 JSON-RPC 2.0,本地通过 stdio,远程通过 Streamable HTTP。规范和多种语言的 SDK 见 modelcontextprotocol.io。
Genesis API 没有官方 MCP 服务器。你可以基于同样的处理函数自建:MCP 工具就是对 Genesis API 接口的一次 GET,其参数是 inputSchema 中的 JSON Schema,密钥放在服务器的环境变量中。本地 stdio 服务器让密钥留在你的机器上。远程服务器请放在授权之后(MCP 推荐 OAuth),否则任何知道地址的人都可以耗尽你的额度。
智能体如何使用加密货币行情数据,见文章面向 AI 智能体的加密货币行情数据;自动化的风险见课程第五课。
常见问题
Genesis API 有官方 MCP 服务器吗?
没有。面向智能体提供 openapi.json、llms-full.txt 和 API 目录。你可以在 REST API 之上自行编写 MCP 服务器:每个工具就是一次携带环境变量中密钥的 GET 请求。
智能体可以通过 Genesis API 交易吗?
不可以。Genesis API 只读取数据,不下单。智能体负责发现机会并发送提醒;交易由人工在交易所完成。
智能体需要哪个套餐?
任何套餐都可以:Trial 提供每秒 1 次请求和 60 秒新鲜度,Max 提供每秒 15 次请求和 5 秒。各套餐包含哪些接口,见 x-genesis-plans 和 Genesis API 定价页面。
为什么模型引用的价格已经过时?
数据会按你套餐的新鲜度滞后,处理函数的缓存最多再增加 freshness_sec。请把 updated_at 和数据年龄交给模型,并要求它在回答中说明时间。