面向 AI 智能体的加密货币市场数据:API、函数调用、MCP 与 llms.txt
简而言之
- 语言模型只了解训练数据截止日期之前的市场。当前的价格、价差和资金费率要通过工具获取:由模型选择调用及其参数,由你的代码发出 API 请求。
- 基于市场数据 API 的工具应当足够窄:一个 endpoint,过滤条件作为参数,只返回几行带有关键字段的数据,并在结果中附上数据时间戳。工具定义来自 OpenAPI 规范,MCP 则把同样的工具接入任何兼容的客户端。
- 密钥留在你的服务器上,外部数据中的文本只会在工具结果里到达模型,每一笔交易都由人工确认。Genesis API 是只读的,并为智能体发布 openapi.json、llms-full.txt 和 API 目录。
AI 智能体通过工具获取加密货币市场数据:模型判断需要哪些数据,你的代码调用加密货币 API,并返回一段简短的 JSON,其中包含价格、价差和数据生成的时间。工具可以通过模型 API 的函数调用接入,也可以通过 MCP 服务器接入,二者都运行在普通的 REST API 之上。
示例使用 Genesis API,这是一个只读的 REST API,提供 CEX、DEX、链上和预测市场数据。关于加密货币 API 的总体介绍以及如何比较,请参阅加密货币 API:市场数据 API 的类型与选择。
为什么模型不知道当前价格
语言模型用截至某个日期(即知识截止日期)收集的文本训练。对于该日期之后的上币、费率和价格,它一无所知;凭记忆报出的 BTC 价格,只是来自日期不明的训练文本中的一个数字。除非你在请求中传入,否则模型也不知道当前时间。
对套利来说,凭记忆回答毫无用处:交易所之间的价差只存在几分钟,资金费率则在每个结算周期(每 8、4 或 1 小时)变化一次。实时数字只能来自工具:上下文中的 API 参考文档能教会模型路径和参数,却不包含价格。
| 模型需要什么 | 来源 | 示例 |
|---|---|---|
| API 路径、参数和字段 | 上下文中的参考文档 | llms-full.txt、openapi.json |
| 价格、价差、费率 | 工具调用 | GET /funding/spread?coin=TON |
| 当前时间和数据年龄 | 系统提示词和工具结果 | updated_at、age_sec |
函数调用的工作方式
函数调用是一种模式:模型返回工具名称和参数而不是文本,由你的代码执行请求。示意性示例:用户询问 TON 目前资金费率价差最大的地方在哪里。调用与结果的示意如下:
{
"tool_call": {
"name": "get_funding",
"arguments": { "coin": "TON" }
},
"tool_result": {
"updated_at": 1794675860,
"age_sec": 12,
"rows": [
{
"coin": "TON",
"spread_pct": 0.04,
"pair": ["Bitget", "Bybit"],
"funding_pct": [0.05, 0.01],
"interval": ["8h", "8h"]
}
]
}
}
- 应用把问题和工具定义发给模型:名称、用途,以及用 JSON Schema 写成的参数模式。
- 模型返回一个
get_funding调用,参数为{"coin": "TON"}。 - 你的代码校验参数,带上
X-API-Key请求头发送GET /funding/spread?coin=TON,并精简响应。 - 结果回到模型,模型回答:Bitget 和 Bybit,每 8 小时 0.05% 和 0.01%,相差 0.04%,数据已有 12 秒。
- 如果数据不够,模型会调用下一个工具。
模型不会发出网络请求,也从不接触 API 密钥。字段名称取决于模型的 API:在 Claude API 中,模式位于 input_schema,调用以 tool_use 块的形式到达,结果以 tool_result 块返回;而 MCP 把模式称为 inputSchema。两种情况下,它都是 JSON Schema。
如何基于市场数据 API 设计工具
一个工具,一件事
模型根据描述选择工具,所以窄而专的工具比通用的 call_api(path, params) 更可靠。从为智能体任务设计的五到七个工具中选择,比从规范里的 37 个操作中选择容易得多。
| 工具 | Genesis API endpoint | 套餐 |
|---|---|---|
get_spreads | /arbitrage/spot-spot | 全部 |
get_funding | /funding/spread | 全部 |
get_prediction_arbs | /predictions/arbitrage | Start、Pro、Max |
get_book | /orderbooks/book | Pro、Max |
描述中要说明何时调用该工具以及数字的单位:在 Genesis API 中,价差和费率是百分数,所以 0.92 表示 0.92%。
过滤条件作为参数,校验放在代码里
coin、exchange、min_spread 这类 API 过滤条件会变成工具参数。模型根据问题填写,处理函数则对照参数、类型和取值的白名单进行检查,enum 列出允许的取值:对 /orderbooks/book 来说,market 只能是 spot 或 futures。模型从不自己拼接请求路径,模式也会拒绝多余字段(additionalProperties: false)。
带过滤条件的响应不带 ETag,因此每次重复的过滤轮询都要消耗一次调用:没有免费的 304。如果智能体需要几十个币种,更省的做法是在本地保存完整的未过滤数据集,并用 If-None-Match 轮询。
精简的结果
示意性示例:完整、未过滤的 /funding/spread 响应覆盖 1,000 个币种。对于上线 10 家交易所的币种,一行包含 2 + 10 + 8 × 5 = 52 个值:币种、价差、best 中最佳交易对的 10 个字段,以及 others 中其余 8 家交易所各 5 个字段。整个响应共有 1,000 × 52 = 52,000 个值,而回答最佳交易对的问题只需要 5 行、每行 8 个值:5 × 8 = 40。
工具定义和结果在每一步都会进入上下文:Claude API 将其按输入 token 计费。
数据时间与新鲜度
处理函数把 updated_at(来自 meta.updated_at 的数据生成时间,单位为 unix 秒)和 age_sec 放进结果。这样模型就能说“数据已有 12 秒”,而不是把昨天的价差当成当前数据。
数据新鲜度由套餐决定:meta.freshness_sec 从 Trial 的 60 秒到 Max 的 5 秒不等。在这个间隔过去之前,API 返回同一份快照,因此处理函数会把响应缓存 freshness_sec 秒。订单簿有自己的时钟:book_ts、age_sec,以及对超过 30 秒的订单簿设置的 stale 标志。
示例:get_funding 工具
下面的定义使用 MCP 格式;对于 Claude API,相同内容放入 input_schema。limit 由处理函数自行实现:API 并没有这个参数。
{
"name": "get_funding",
"description": "Where funding is higher or lower: best exchange pair",
"inputSchema": {
"type": "object",
"properties": {
"coin": {
"type": "string",
"description": "Coin ticker, e.g. TON"
},
"min_spread": {
"type": "number",
"minimum": 0,
"description": "Minimum spread, %: 0.05 means 0.05%"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"description": "How many rows to return, 5 by default"
}
},
"additionalProperties": false
}
}
Python 处理函数:按 freshness_sec 缓存,遇到 429 和 503 时短暂等待一次,日志中不含密钥,并返回带数据时间的精简结果。
import logging
import os
import time
import requests
URL = "https://api.genesisarbitrage.com/v1/funding/spread"
KEY = os.environ["GENESIS_API_KEY"] # 密钥留在服务器上
cache = {} # 请求参数 -> (接收时间, 响应体)
def get_funding(coin=None, min_spread=None, limit=5):
p = {"coin": coin and coin.upper(), "min_spread": min_spread}
p = {k: v for k, v in p.items() if v}
ck = tuple(sorted(p.items()))
got, body = cache.get(ck, (0, None))
if not body or time.time() - got >= body["meta"]["freshness_sec"]:
for attempt in range(2): # 429、503:短暂等待,重试一次
r = requests.get(URL, params=p, timeout=10,
headers={"X-API-Key": KEY})
wait = int(r.headers.get("Retry-After", "0"))
if attempt or wait > 5 or r.status_code not in (429, 503):
break
time.sleep(wait)
logging.info("get_funding %s -> %s id=%s", p, r.status_code,
r.headers.get("X-Request-Id")) # 日志中不含密钥
if r.status_code != 200:
return {"error": r.status_code} # 401, 403, 429, 503
body = r.json()
cache[ck] = (time.time(), body)
t = body["meta"]["updated_at"]
top = sorted(body["data"], key=lambda x: -x["spread_pct"])
rows = [{"coin": x["coin"], "spread_pct": x["spread_pct"],
"pair": [x["best"]["exchange_1"], x["best"]["exchange_2"]],
"funding_pct": [x["best"]["funding_1_pct"],
x["best"]["funding_2_pct"]],
"interval": [x["best"]["interval_1"],
x["best"]["interval_2"]]}
for x in top[:min(max(int(limit), 1), 10)]]
return {"updated_at": t, "age_sec": int(time.time() - t),
"rows": rows}
处理函数不会等待超过 5 秒的暂停:配额用完后,Retry-After 指向重置时间,那可能是几天之后。模型会拿到状态码,并告诉用户发生了什么:403 表示 plan_restricted,即 endpoint 不在当前套餐内(Genesis API 错误)。
以 OpenAPI 作为工具定义的来源
OpenAPI 是描述 HTTP API 的机器可读标准:一个操作由 operationId、简短的 summary 和带模式的参数来描述。在 3.1 版本中,Schema Object 是 JSON Schema 2020-12 的超集(OpenAPI 3.1 规范),而 MCP 默认把 inputSchema 当作 JSON Schema 2020-12 来读取。因此参数无需转换即可移入工具。
脚本根据 Genesis API 规范生成工具:取出你想要的操作,按 x-genesis-plans 跳过不在你套餐内的操作,并带上 query 和 path 参数。请求头由处理函数负责。
import requests
SPEC = "https://genesisarbitrage.com/openapi.json"
def tools_from_spec(wanted, plan):
"""wanted: operationId -> 工具名称; plan: trial … max."""
spec = requests.get(SPEC, timeout=15).json()
tools, routes = [], {}
for path, item in spec["paths"].items():
op = item.get("get", {})
name = wanted.get(op.get("operationId"))
if not name or plan not in op.get("x-genesis-plans", []):
continue # 不需要或不在套餐内:403 plan_restricted
props, required = {}, []
for prm in op.get("parameters", []):
if "$ref" in prm or prm["in"] not in ("query", "path"):
continue # 处理函数发送 X-API-Key、If-None-Match
props[prm["name"]] = {**prm["schema"],
"description": prm["description"]}
if prm.get("required"):
required.append(prm["name"])
tools.append({
"name": name,
"description": op["description"].split("\n\n")[0],
"inputSchema": {"type": "object", "properties": props,
"required": required,
"additionalProperties": False}})
routes[name] = path # 工具名称 -> endpoint 路径
return tools, routes
tools, routes = tools_from_spec({"getFundingSpread": "get_funding",
"getArbitrageSpotSpot": "get_spreads"},
plan="trial")
getFundingSpread 会变成带有 coin 和 min_spread 参数的 get_funding 工具。如果传入全部操作,Trial 在 37 个操作中保留 11 个,Start 保留 16 个。routes 字典保存每个工具的路径。
MCP:基于 REST API 的自建服务器
MCP(Model Context Protocol)是把 AI 应用连接到数据和工具的开放标准。Anthropic 于 2024 年 11 月 25 日将其开源(Anthropic 公告),并于 2025 年 12 月 9 日把它捐赠给 Agentic AI Foundation,这是 Linux Foundation 旗下的基金会(MCP 博客)。
运行模型的应用,即 host,为每个服务器创建一个 MCP 客户端。服务器通过 JSON-RPC 2.0 提供工具、资源和提示词模板:本地服务器通过 stdio,远程服务器通过 Streamable HTTP,对于后者,MCP 建议通过 OAuth 获取令牌(MCP 架构)。
| 函数调用 | MCP | |
|---|---|---|
| 工具在哪里定义 | 在发给模型 API 的请求中 | 在服务器上;客户端用 tools/list 获取 |
| 谁来执行调用 | 你的应用代码 | MCP 服务器,在收到 tools/call 请求时 |
| 适用范围 | 在你编写了循环的应用中 | 在任何支持 MCP 的客户端中 |
把 REST API 封装成 MCP 服务器分四步:
选择操作
为智能体的任务挑选 3–7 个操作;像上面的脚本那样,根据 OpenAPI 生成工具名称、描述和参数。
在 tools/list 上返回列表
服务器为每个工具返回
name、description和inputSchema。处理 tools/call
校验参数,使用服务器环境中的密钥发出 GET 请求,并在
content块中返回精简的 JSON。API 错误用isError: true返回:模型据此修正自己的参数。选择传输方式
通过 stdio 时,服务器运行在你的机器上,密钥不会离开本机。远程 Streamable HTTP 服务器要放在授权之后,否则任何知道 URL 的人都会消耗你的配额。
官方 MCP SDK 覆盖 10 种语言,从 Python 和 TypeScript 到 Go 和 Rust(SDK 列表)。
llms.txt 与 llms-full.txt
llms.txt 是位于 /llms.txt 的 Markdown 文件,帮助语言模型使用网站。Jeremy Howard 于 2024 年 9 月 3 日提出了这一格式(llmstxt.org):唯一必需的部分是带名称的 H1,其后是引用块形式的摘要,以及带有页面 Markdown 版本链接的各个章节。
该提案并未定义 llms-full.txt:这个名称被用来指把整套文档合并成一个 Markdown 文件,例如 MCP 文档站点就发布了它。模型无需跟随链接,因为整份参考文档都会进入它的上下文。
智能体安全
把密钥保存在服务器的环境变量中:它不能出现在提示词、浏览器或日志里。Genesis API 密钥是只读的,不能下单或提现,泄露只会消耗你的配额。泄露的密钥请在个人资料中通过重新签发来替换(密钥保管)。
提示词注入是藏在数据中、针对模型的指令。代币名称由部署者设定,交易者名称由交易者本人设定,所以某个字段里可能写着“忽略之前的指令”。在 Genesis API 中,外部文本出现在预测市场的 title 和 outcome 字段、交易者的 name、链上的 token_name,以及 Genesis AI+ 信号的 message_ru 和 message_en 中:请在系统提示词中声明,工具结果仅是数据。
MCP 规范要求服务器校验工具输入、对调用进行 rate limit 并清理输出,同时建议客户端对敏感操作进行确认并记录工具的使用(MCP 工具)。请记录 X-Request-Id:凭借它,加上 UTC 时间、endpoint 和状态,客服就能找到这次请求。
自动化的风险在加密货币 API 课程第 5 课中讲解。
成本与限额
只有 200 响应会消耗 Genesis API 配额;304 和错误不收费,但会计入每秒的 rate limit。超出限额时,服务器返回 429,且不扣费。
| 套餐 | 价格 | 配额与速率 | 新鲜度 |
|---|---|---|---|
| Trial | $20/月 | 500,000 次调用,1 次请求/秒 | 60 秒 |
| Start | $50/月 | 200 万次调用,2 次请求/秒 | 30 秒 |
| Pro | $100/月 | 500 万次调用,5 次请求/秒 | 10 秒 |
| Max | $200/月 | 1,000 万次调用,15 次请求/秒 | 5 秒 |
示意性示例:每天 500 个问题、每个问题 3 次工具调用,即每天 500 × 3 = 1,500 次调用,30 天共 1,500 × 30 = 45,000 次,占 Trial 配额的 9%。缓存可以覆盖在 freshness_sec 内参数相同的重复请求,限制每个回答的工具调用次数则能防止循环耗尽配额。
轮询频率高于 meta.freshness_sec 不会带来新的快照。如何借助 ETag 低成本轮询并重试,请参阅如何轮询加密货币 API 而不触及限额,限额本身见 Genesis API 限额指南。如果智能体只需要规则而不需要模型,用 Python 写的加密货币套利机器人更简单。
面向 AI 智能体的 Genesis API
Genesis API 是提供 Genesis Arbitrage 数据的 REST API:CEX 和 DEX 价差、订单簿、资金费率、持仓量、跨链、链上资金流、预测市场、体育博彩套利和 AI 信号。请求是带 X-API-Key 请求头的 HTTP GET,响应是包含 data 和 meta 的 JSON(响应格式),无需 SDK。
为智能体发布的内容:
openapi.json— OpenAPI 3.1:37 个操作、响应模式,以及x-genesis-plans中的套餐;llms-full.txt— 合并为一个 Markdown 文件的完整参考;llms.txt— 面向语言模型的网站概览;/.well-known/api-catalog— 链接到规范、文档和状态页的 RFC 9727 目录。
没有官方 MCP 服务器、WebSocket 和交易 endpoint:智能体读取数据,交易由人工负责。分步设置请见 AI 智能体的 Genesis API指南。
常见问题
AI 智能体可以自己交易加密货币吗?
只有当你给它交易所交易 API 时才可以,而那是你自己的代码和风险。通过 Genesis API 则不行:它只读取数据。MCP 规范指出,人应当始终能够拒绝工具调用;对于交易,请规定每一笔订单都要由人工确认。
AI 智能体需要哪个 Genesis API 套餐?
每月 $20 的 Trial 涵盖 CEX 价差、资金费率和持仓量。Start 增加股票、链上板块,以及 exact 和 dutch 模式的预测套利,而 Pro 和 Max 开放全部内容,包括 DEX 和订单簿。反应速度取决于每秒限制和套餐的新鲜度;各套餐内容见 Genesis API 价格页面。
在哪里获取供智能体使用的 Genesis API 规范?
OpenAPI 3.1 位于 genesisarbitrage.com/openapi.json,供模型使用的参考文档位于 genesisarbitrage.com/llms-full.txt。智能体也可以通过 /.well-known/api-catalog 目录找到这两者。
Genesis API 有 MCP 服务器吗?
没有官方的。你可以用相同的处理函数自建:MCP 工具就是用服务器环境中的密钥对某个 endpoint 发出的 GET 请求。最简的 Python 示例见 MCP词条。