Genesis Arbitrage

Genesis Arbitrage · · 阅读约 15 分钟

面向 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.jsonOpenAPI 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。

如何接入

  1. 获取密钥并保存在服务器上

    gns_live_… 密钥在个人资料的 Genesis API 区块中签发,只显示一次。请把它保存在运行智能体的服务器的 GENESIS_API_KEY 环境变量中。保存与重新签发的方法见 API 密钥指南。

  2. 导入规范

    支持 OpenAPI 的 API 客户端或智能体框架可以直接根据 openapi.json 生成请求和工具:基础 URL 来自 servers,密钥请求头来自 ApiKeyAuth。密钥的传递方式见认证。

  3. 只保留需要的操作

    每个工具定义都会占用模型的上下文,从少量工具中选择也更容易。保留任务所需的操作,并按 x-genesis-plans 去掉不在你套餐内的操作:它们会返回 403 plan_restricted。

  4. 把参考文档交给模型

    如果智能体要编写代码或回答 API 相关问题,请把 llms-full.txt 加入其上下文:其中包含每个接口的参数、字段和示例,以及限额和错误码。

  5. 用第一次调用检查密钥

    /account/usage 会返回你的套餐、已用额度、每秒请求数限制和数据新鲜度。

模型如何调用 Genesis API

函数调用是一种机制:模型返回工具名称和参数而不是文本,由你的代码发起调用。流程如下:

  1. 模型在收到用户问题的同时,拿到工具定义:名称、用途,以及 JSON Schema 形式的参数。
  2. 模型以一次调用作答:调用 get_spreads,参数为 {"coin": "TON", "min_spread": 0.5}。
  3. 你的服务器校验参数,携带 X-API-Key 请求头发起 GET,并把响应裁剪为所需字段。
  4. 带有数据时间的简短 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 和数据年龄交给模型,并要求它在回答中说明时间。