Genesis Arbitrage

Genesis Arbitrage · · 阅读约 23 分钟

用 Python 编写价差与资金费率监控

简而言之

  • 监控程序是一个控制台程序:每隔 meta.freshness_sec 秒完整拉取 /arbitrage/spot-spot 和 /funding/spread 两个数据集,按阈值筛选行,打印表格并追加到 CSV 文件。
  • 两个数据集都不带筛选参数请求,因此都带有 ETag:在下一次快照之前带 If-None-Match 重复请求会返回 304,不消耗配额。遇到 429 和 503 时,客户端等待 Retry-After 秒。
  • 按每条腿 0.1% 的假设 taker 手续费,扣费后剩余为价差减去 0.2 个百分点。在 Pro 和 Max 上,监控程序会用 $1,000 的订单簿复核前三个交易对。
  • 上限是:Trial 每 30 天 86,400 次调用,占配额的 17.28%;带订单簿检查的 Pro 为 1,296,000 次,占 25.92%。

价差与资金费率监控是一个循环拉取跨交易所价差和资金费率价差的程序,它保留高于你设定阈值的行,并在控制台中以表格形式打印。本课的监控程序约 170 行 Python:数据来自 Genesis API,历史记录写入 CSV 文件,不会开任何仓位,也不发送提醒;带 Telegram 消息的机器人见 用 Python 编写加密货币套利机器人。

轮询方案:endpoint、频率与调用量

请求返回内容时机
/account/usage套餐、freshness_sec、rps_limit启动时,不消耗配额
/arbitrage/spot-spotSpot – Spot 交易对每一轮,完整数据集
/funding/spread按资金费率排序的最佳交易所组合每一轮,完整数据集
/orderbooks/spreads/spot-spot$1,000 的订单簿 ΔPro 和 Max,每轮三个交易对

频率由 meta.freshness_sec 决定:你的套餐每隔一段时间获得新快照,Trial 为 60 秒,Start 为 30 秒,Pro 为 10 秒,Max 为 5 秒。更快地轮询只会得到 meta.updated_at 相同的同一份快照。两个数据集的字段见 Spot — Spot 和 资金费率价差 文档。

套餐与配额间隔每轮请求数30 天调用数
Trial,500K60 秒286,400
Start,2M30 秒2172,800
Pro,5M10 秒51,296,000
Max,10M5 秒52,592,000

Trial:2 × 86,400 / 60 × 30 = 86,400 次调用,占配额的 17.28%。Pro 上,两个数据集之外再加三次订单簿检查:5 × 86,400 / 10 × 30 = 1,296,000 次调用,占 5M 的 25.92%。配额规则见 Genesis API 限额指南。

监控程序在两次请求之间等待 1.1 / rps_limit 秒,以遵守每秒请求数限制:Trial 为 1.1 秒,Pro 为 0.22 秒。Pro 上一轮五个请求大约需要一秒。

设置与支持 ETag 和 Retry-After 的客户端

本课的七个代码块合起来就是完整的 monitor.py 文件:按顺序依次保存到同一个文件中。设置中的阈值仅作示例,请按你的手续费和交易规模调整。

import csv
import os
import time
from datetime import datetime, timezone

import requests

API = "https://api.genesisarbitrage.com/v1"
MIN_SPREAD = 1.0     # 价差不低于 1%
MIN_VOLUME = 50_000  # 两家交易所 24 小时成交量均不低于 $50,000
MIN_FUNDING = 0.05   # 资金费率价差不低于 0.05%
FEE = 0.1            # 假设每条腿的 taker 手续费,%
TOP = 10             # 每个表格的行数
BOOK_TOP = 3         # 每轮用订单簿复核的交易对数,Pro/Max
BOOK_USD = 1000      # 订单簿检查金额,USD
CSV_FILE = "monitor.csv"

api = requests.Session()
api.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {}                # 请求 -> (ETag, 响应体)
stats = {200: 0, 304: 0}  # 收到的 200 和 304 响应数量
pace = {"gap": 1.1, "last": 0.0}  # 请求间隔,秒

密钥来自环境变量 GENESIS_API_KEY,放在每个请求的 X-API-Key 请求头中,绝不放进 URL。cache 保存每个请求最近一次响应的 ETag 和响应体,stats 统计 200 和 304 响应,pace 记录上一次请求发出的时间。

def get(path, params=None):
    """向 Genesis API 发 GET:控制间隔,处理 ETag 和 Retry-After 重试。"""
    key = (path, tuple(sorted((params or {}).items())))
    for _ in range(4):  # 一次请求,最多重试三次
        wait = pace["last"] + pace["gap"] - time.monotonic()
        if wait > 0:
            time.sleep(wait)  # 每秒最多 rps_limit 个请求
        pace["last"] = time.monotonic()
        hdr = {"If-None-Match": cache[key][0]} if key in cache else {}
        r = api.get(API + path, params=params, headers=hdr,
                    timeout=15)
        if r.status_code == 304:  # 快照没有变化
            stats[304] += 1
            return cache[key][1]
        if r.status_code in (429, 503):
            wait = int(r.headers.get("Retry-After", "5"))
            if wait > 60:  # 配额用尽时就是这个样子
                raise SystemExit(f"配额已用尽:请等待 {wait} 秒")
            time.sleep(wait)
            continue
        r.raise_for_status()  # 400、401、403:重试无济于事
        stats[200] += 1
        body = r.json()
        if "ETag" in r.headers:  # 只有完整数据集才带有
            cache[key] = (r.headers["ETag"], body)
        return body
    raise RuntimeError("API 繁忙,下一轮重试")

ETag 是快照的版本标签。get 把它放在 If-None-Match 请求头中发回,快照不变时服务器返回不带响应体的 304:不消耗配额,函数返回之前的响应体。遇到 429 和 503 时,它等待 Retry-After 秒后重试;等待超过一分钟说明本周期配额已用尽,监控程序随之停止。错误码和重试规则见 Genesis API 响应与错误指南。

价差与资金费率:加载、阈值与排序

def spot_rows():
    """高于阈值的 Spot – Spot 交易对,币种可转账。"""
    body = get("/arbitrage/spot-spot")  # 无筛选:带 ETag
    rows = []
    for x in body["data"]:
        vol = min(x["volume_24h_buy"] or 0, x["volume_24h_sell"] or 0)
        if (x["spread_pct"] >= MIN_SPREAD and vol >= MIN_VOLUME
                and x["withdraw_enabled_buy"]
                and x["deposit_enabled_sell"]):
            rows.append({**x, "net": net(x["spread_pct"])})
    rows.sort(key=lambda x: x["spread_pct"], reverse=True)
    return rows[:TOP], body["meta"]


def funding_rows():
    """资金费率价差最大的币种。"""
    body = get("/funding/spread")  # 无筛选:带 ETag
    rows = [x for x in body["data"] if x["spread_pct"] >= MIN_FUNDING]
    rows.sort(key=lambda x: x["spread_pct"], reverse=True)
    return rows[:TOP], body["meta"]

两个数据集都不带参数请求:带 min_spread、coin 或其他筛选条件的请求,其响应是为该请求单独生成的,不带 ETag。阈值由监控程序自己应用:价差不低于 MIN_SPREAD,两家交易所 24 小时成交量均不低于 MIN_VOLUME,买入交易所开放提币,卖出交易所开放充值。null 成交量按零处理,因此这样的行不会通过。

行按 spread_pct 降序排列,前 TOP 行进入表格。在 /funding/spread 中,MIN_FUNDING 阈值与最佳交易对的 spread_pct 比较。

扣费后的剩余与订单簿检查

def net(spread_pct):
    """扣除两笔 taker 手续费后的剩余,约数,%。"""
    return round(spread_pct - 2 * FEE, 4)


def book_net(row):
    """扣除 BOOK_USD 订单簿成交和手续费后的剩余。Pro 和 Max。"""
    body = get("/orderbooks/spreads/spot-spot",
               {"coin": row["coin"], "volume": BOOK_USD})
    pair = (row["exchange_buy"], row["exchange_sell"])
    for x in body["data"]:
        if (x["exchange_buy"], x["exchange_sell"]) != pair:
            continue
        od = x["order_delta"]
        if od["status"] != "ok":
            return od["status"]  # no_book 或 exhausted
        return net(od["spread_pct"])
    return "gone"  # 该交易对已不在数据集中

买入 0.1% 加卖出 0.1% 的假设 taker 手续费,会让价差减少约 0.2 个百分点:1.62% 的交易对剩下 1.62 − 2 × 0.1 = 1.42%。请把你所用交易所的手续费填入 FEE(maker 与 taker)。提币手续费不在 API 响应中,监控程序也不计入。

在 Pro 和 Max 上,book_net 用订单簿复核前三个交易对:用该交易对的币种和 volume=1000 请求 /orderbooks/spreads/spot-spot,会返回该币种带 order_delta 对象的行,函数取出交易所组合相同的那一行(订单簿 Δ)。如果没有订单簿或订单簿已被耗尽,得到的是 no_book 或 exhausted 状态,而不是数字。带 coin 的请求没有 ETag,每次都消耗一次调用,所以每轮只发出三次,由 BOOK_TOP 设定。

控制台表格

def show(spot, s_meta, fund, f_meta):
    now = time.time()
    s_age = now - s_meta["updated_at"]
    f_age = now - f_meta["updated_at"]
    print(f"\nSpot – Spot,快照年龄 {s_age:.0f} 秒")
    print(f"{'币种':<8}{'买入 → 卖出':<20}"
          f"{'价差':>7}{'扣费后':>9}{'订单簿':>11}")
    for x in spot:
        pair = f'{x["exchange_buy"]} → {x["exchange_sell"]}'
        book = x.get("book", "—")
        if isinstance(book, float):
            book = f"{book:.2f}"
        print(f'{x["coin"]:<8}{pair:<20}{x["spread_pct"]:>7.2f}'
              f'{x["net"]:>9.2f}{book:>11}')
    print(f"\n资金费率,快照年龄 {f_age:.0f} 秒")
    for x in fund:
        b = x["best"]
        legs = (f'{b["exchange_1"]} {b["interval_1"] or "?"} / '
                f'{b["exchange_2"]} {b["interval_2"] or "?"}')
        print(f'{x["coin"]:<8}{legs:<27}{x["spread_pct"]:>8.4f} %')
    print(f"200 响应:{stats[200]},304:{stats[304]}")

第一张表显示币种、交易所组合、spread_pct、扣费后剩余和扣订单簿后剩余;短横线表示没有检查订单簿。第二张表显示按资金费率排序的最佳交易所组合,含结算周期和 spread_pct。表格上方是快照年龄,即当前时间减去 meta.updated_at,下方是启动以来 200 和 304 响应的数量。

CSV 历史记录

def save(spot, fund):
    """把本轮结果追加到 CSV:时间、数据集、交易对、价差。"""
    new = not os.path.exists(CSV_FILE)
    ts = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
    with open(CSV_FILE, "a", newline="", encoding="utf-8") as f:
        w = csv.writer(f)
        if new:
            w.writerow(["time_utc", "dataset", "coin", "leg_1",
                        "leg_2", "spread_pct", "net_pct", "book"])
        for x in spot:
            w.writerow([ts, "spot-spot", x["coin"], x["exchange_buy"],
                        x["exchange_sell"], x["spread_pct"], x["net"],
                        x.get("book")])  # None 会写成空单元格
        for x in fund:
            b = x["best"]
            w.writerow([ts, "funding", x["coin"], b["exchange_1"],
                        b["exchange_2"], x["spread_pct"], None, None])

控制台表格只保留到下一轮,而 monitor.csv 保存每一轮:从中可以看出一个交易对能持续多久、在哪些时段出现。csv 模块属于 Python 标准库。按模块文档的要求用 newline="" 打开文件;否则在使用 \r\n 换行的系统上,文件里会多出一个 \r。

book 列保存扣订单簿后的剩余百分比,或 exhausted、no_book 状态。模块把 None 写成空单元格,所以资金费率行和未检查的交易对在该列为空。时间为 UTC。

主循环

def main():
    usage = get("/account/usage")["data"]  # does not use quota
    books = usage["plan"] in ("pro", "max")
    pace["gap"] = 1.1 / usage["rps_limit"]
    print("套餐", usage["plan"], "| 快照间隔",
          usage["freshness_sec"], "秒 | 订单簿:",
          "是" if books else "否")
    pause = usage["freshness_sec"]
    while True:
        try:
            spot, s_meta = spot_rows()
            fund, f_meta = funding_rows()
            if books:
                for x in spot[:BOOK_TOP]:
                    x["book"] = book_net(x)
            show(spot, s_meta, fund, f_meta)
            save(spot, fund)
            pause = s_meta.get("freshness_sec", pause)
        except requests.HTTPError as e:
            if e.response.status_code < 500:
                raise  # 密钥、套餐或参数问题:重试无济于事
            print("服务器错误,重试中:", e)
        except (requests.RequestException, RuntimeError) as e:
            print("无响应,重试中:", e)
        time.sleep(pause)  # 比 freshness_sec 更快 = 拿到同一份快照


if __name__ == "__main__":
    try:
        main()
    except KeyboardInterrupt:
        print("\n监控已停止,历史记录在", CSV_FILE)

启动时,监控程序调用 /account/usage:该请求不消耗配额,返回套餐、freshness_sec 和 rps_limit(用量)。套餐决定监控程序是否检查订单簿,rps_limit 决定请求间隔。网络故障和 5xx 错误会被忽略,等到下一轮再试,而 4xx 错误(密钥错误、订阅过期、套餐不含该 endpoint)会让它停止。

如何运行与解读输出

python3 --version   # 需要 Python 3.10 或更高版本
python3 -m pip install requests
export GENESIS_API_KEY="gns_live_XXXXXXXXXXXXXXXX"
python3 monitor.py

Pro 套餐下的输出,仅作示例:

套餐 pro | 快照间隔 10 秒 | 订单簿: 是

Spot – Spot,快照年龄 4 秒
币种    买入 → 卖出          价差    扣费后      订单簿
KLM     ByBit → Gate           1.62     1.42       0.86
XYZ     MEXC → Gate            1.24     1.04  exhausted
ABC     BingX → HTX            1.12     0.92       0.31
QRS     Gate → OKX             1.05     0.85          —

资金费率,快照年龄 4 秒
XYZ     MEXC 4h / Bitget 8h          0.0600 %
ABC     Hyper 1h / CoinEx 8h         0.0500 %
200 响应:6,304:0

KLM:该行价差为 1.62%,扣两笔手续费后为 1.42%,再扣 $1,000 订单簿成交和手续费后为 0.86%。XYZ 在 $1,000 时订单簿被耗尽:这样的交易对要缩小规模或直接跳过。QRS 排在第四行,所以没有请求它的订单簿。资金费率表显示各交易所的结算频率:Hyper(响应中 Hyperliquid 的名称)每小时结算,CoinEx 每 8 小时结算。按 Ctrl+C 停止监控程序。

在第 3 课的四项交易对检查中,监控程序自己完成价差和转账检查,在 Pro 和 Max 上检查订单簿,并在表格上方显示数据新鲜度。合约和提币手续费由你自己核对。

练习

  1. 启动监控程序

    输出的第一行显示套餐、快照间隔以及是否检查订单簿;请与你的个人资料对照。

  2. 调整阈值

    设置 MIN_SPREAD = 0.5,看看新增的行中有多少扣费后一列仍高于零。

  3. 添加数据集

    为 /arbitrage/futures-futures 复制 spot_rows:行格式相同。合约不需要检查充值和提币,因为那里不涉及币种在交易所之间转移。

  4. 检查用量

    一小时后调用 /account/usage,把 calls_used 与估算值对比:Trial 上每小时最多 2 × 60 = 120 次调用。

  5. 找出持续存在的交易对

    在电子表格中打开 monitor.csv,统计每个交易所组合连续出现了多少轮。

自动化的风险,从过期数据和错误到密钥和 AI 代理,见第 5 课;用筛选、压缩和 ETag 节省轮询的方法见如何轮询 API 而不触发限额一文。

常见问题

监控程序和套利机器人有什么区别?

监控程序打印表格并保存历史记录;机器人会发送新交易对的提醒,对重复出现的则保持沉默。两者共用请求和筛选代码,Telegram 机器人见用 Python 编写加密货币套利机器人一文。

可以比 freshness_sec 更快地轮询吗?

拿不到新数据:你的套餐每 freshness_sec 秒获得一份快照。下一次快照之前,不带筛选的请求返回免费的 304,而带筛选的请求为同样的数据消耗一次调用。

为什么订单簿列显示短横线?

订单簿 Δ 只在 Pro 和 Max 上提供,监控程序只为前三个交易对请求它(BOOK_TOP)。在 Trial 和 Start 上,endpoint 返回 403 plan_restricted,所以监控程序不会调用它。