Genesis Arbitrage

Genesis Arbitrage · · 阅读约 25 分钟

面向 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"]
      }
    ]
  }
}
  1. 应用把问题和工具定义发给模型:名称、用途,以及用 JSON Schema 写成的参数模式。
  2. 模型返回一个 get_funding 调用,参数为 {"coin": "TON"}。
  3. 你的代码校验参数,带上 X-API-Key 请求头发送 GET /funding/spread?coin=TON,并精简响应。
  4. 结果回到模型,模型回答:Bitget 和 Bybit,每 8 小时 0.05% 和 0.01%,相差 0.04%,数据已有 12 秒。
  5. 如果数据不够,模型会调用下一个工具。

模型不会发出网络请求,也从不接触 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/arbitrageStart、Pro、Max
get_book/orderbooks/bookPro、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 服务器分四步:

  1. 选择操作

    为智能体的任务挑选 3–7 个操作;像上面的脚本那样,根据 OpenAPI 生成工具名称、描述和参数。

  2. 在 tools/list 上返回列表

    服务器为每个工具返回 name、description 和 inputSchema。

  3. 处理 tools/call

    校验参数,使用服务器环境中的密钥发出 GET 请求,并在 content 块中返回精简的 JSON。API 错误用 isError: true 返回:模型据此修正自己的参数。

  4. 选择传输方式

    通过 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。

为智能体发布的内容:

没有官方 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词条。