Genesis Arbitrage

Genesis Arbitrage · · 14 min de leitura

Um monitor de spreads e funding em Python

Em resumo

  • O monitor é um programa de console: a cada meta.freshness_sec segundos ele busca os datasets completos /arbitrage/spot-spot e /funding/spread, filtra as linhas por limiares, imprime tabelas e as acrescenta a um arquivo CSV.
  • Os dois datasets são pedidos sem filtros, então vêm com ETag: uma repetição com If-None-Match antes do próximo snapshot devolve 304 sem consumir cota. Em 429 e 503, o cliente espera Retry-After segundos.
  • O que sobra com taxas taker presumidas de 0,1% por perna é o spread menos 0,2 ponto percentual. Em Pro e Max, o monitor reconfere os três melhores pares com US$ 1.000 de order book.
  • O teto é de 86.400 chamadas por 30 dias no Trial, 17,28% da cota, e de 1.296.000 no Pro com checagens de book, 25,92%.

Um monitor de spreads e funding é um programa que busca em laço os spreads entre exchanges e os spreads de funding, mantém as linhas acima dos seus limiares e as imprime como tabela no console. O monitor desta lição tem cerca de 170 linhas de Python: os dados vêm da Genesis API, o histórico vai para um arquivo CSV e ele não abre operações. Também não envia alertas; o bot com mensagens no Telegram está em Bot de arbitragem de criptomoedas em Python.

Plano de consultas: endpoints, frequência e consumo de chamadas

RequisiçãoO que devolveQuando
/account/usagePlano, freshness_sec, rps_limitNo início, não consome cota
/arbitrage/spot-spotPares Spot – SpotA cada passagem, dataset completo
/funding/spreadMelhores pares de exchanges por fundingA cada passagem, dataset completo
/orderbooks/spreads/spot-spotΔ do order book para US$ 1.000Pro e Max, três pares por passagem

meta.freshness_sec define a frequência: seu plano recebe um snapshot novo a cada 60 segundos no Trial, 30 no Start, 10 no Pro e 5 no Max. Fazer polling mais rápido devolve o mesmo snapshot com o mesmo meta.updated_at. Os campos dos dois datasets estão na documentação de Spot — Spot e de Spread de funding.

Plano e cotaPausaRequisições por passagemChamadas em 30 dias
Trial, 500K60 s286.400
Start, 2M30 s2172.800
Pro, 5M10 s51.296.000
Max, 10M5 s52.592.000

No Trial: 2 × 86.400 / 60 × 30 = 86.400 chamadas, 17,28% da cota. No Pro, três checagens de book se somam aos dois datasets: 5 × 86.400 / 10 × 30 = 1.296.000 chamadas, 25,92% de 5M. As regras da cota estão no guia de limites da Genesis API.

O monitor respeita o limite de requisições por segundo com uma pausa de 1,1 / rps_limit segundo entre as requisições: 1,1 segundo no Trial e 0,22 no Pro. Uma passagem de cinco requisições no Pro leva cerca de um segundo.

Configurações e um cliente com ETag e Retry-After

Os sete blocos de código desta lição formam o arquivo monitor.py inteiro: salve-os um após o outro em um único arquivo. Os limiares das configurações são ilustrativos; ajuste-os às suas taxas e aos seus tamanhos.

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

import requests

API = "https://api.genesisarbitrage.com/v1"
MIN_SPREAD = 1.0     # spread da linha a partir de 1%
MIN_VOLUME = 50_000  # volume de 24 h nas duas exchanges a partir de US$ 50.000
MIN_FUNDING = 0.05   # spread de funding a partir de 0,05%
FEE = 0.1            # taxa taker presumida por perna, %
TOP = 10             # linhas em cada tabela
BOOK_TOP = 3         # pares conferidos nos books por passagem, Pro/Max
BOOK_USD = 1000      # tamanho da checagem do book, USD
CSV_FILE = "monitor.csv"

api = requests.Session()
api.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {}                # requisição -> (ETag, corpo da resposta)
stats = {200: 0, 304: 0}  # quantas respostas 200 e 304 chegaram
pace = {"gap": 1.1, "last": 0.0}  # pausa entre requisições, s

A chave vem da variável de ambiente GENESIS_API_KEY e vai no cabeçalho X-API-Key de cada requisição, nunca na URL. cache guarda o ETag e o corpo da última resposta a cada requisição, stats conta as respostas 200 e 304, e pace lembra quando saiu a última requisição.

def get(path, params=None):
    """GET na Genesis API: ritmo, ETag e novas tentativas por Retry-After."""
    key = (path, tuple(sorted((params or {}).items())))
    for _ in range(4):  # uma requisição e até três novas tentativas
        wait = pace["last"] + pace["gap"] - time.monotonic()
        if wait > 0:
            time.sleep(wait)  # no máximo rps_limit requisições por segundo
        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:  # o snapshot não mudou
            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:  # é assim que uma cota esgotada aparece
                raise SystemExit(f"Cota esgotada: aguarde {wait} s")
            time.sleep(wait)
            continue
        r.raise_for_status()  # 400, 401, 403: tentar de novo não ajuda
        stats[200] += 1
        body = r.json()
        if "ETag" in r.headers:  # só os datasets completos trazem
            cache[key] = (r.headers["ETag"], body)
        return body
    raise RuntimeError("API ocupada, nova tentativa na próxima passagem")

O ETag é uma etiqueta de versão do snapshot. get o devolve no cabeçalho If-None-Match e, enquanto o snapshot não muda, o servidor responde 304 sem corpo: nenhuma cota é consumida e a função devolve o corpo anterior. Em 429 e 503, ela espera Retry-After segundos e tenta de novo; uma pausa maior que um minuto significa que a cota do período acabou, e o monitor para. Os códigos de erro e as regras de nova tentativa estão no guia de respostas e erros da Genesis API.

Spreads e funding: carregamento, limiares e ordenação

def spot_rows():
    """Pares Spot – Spot acima dos limiares, com a moeda transferível."""
    body = get("/arbitrage/spot-spot")  # sem filtros: tem 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():
    """Moedas com o maior spread de funding."""
    body = get("/funding/spread")  # sem filtros: tem 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"]

Os dois datasets são pedidos sem parâmetros: a resposta a uma requisição com min_spread, coin ou outro filtro é montada para aquela requisição e vem sem ETag. O monitor aplica os limiares por conta própria: spread de pelo menos MIN_SPREAD, volume de 24 h de pelo menos MIN_VOLUME nas duas exchanges, saques abertos na exchange de compra e depósitos abertos na exchange de venda. Um volume null conta como zero, então essa linha não passa.

As linhas são ordenadas por spread_pct em ordem decrescente e as primeiras TOP entram na tabela. Em /funding/spread, o limiar MIN_FUNDING é comparado com o spread_pct do melhor par.

O que sobra depois das taxas e a checagem do order book

def net(spread_pct):
    """O que sobra depois de duas taxas taker, aproximadamente, %."""
    return round(spread_pct - 2 * FEE, 4)


def book_net(row):
    """O que sobra depois de BOOK_USD de book e taxas. Pro e 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 ou exhausted
        return net(od["spread_pct"])
    return "gone"  # o par saiu do dataset

Taxas taker presumidas de 0,1% na compra e 0,1% na venda reduzem o spread em cerca de 0,2 ponto percentual: um par a 1,62% deixa 1,62 − 2 × 0,1 = 1,42%. Coloque em FEE as taxas das suas exchanges (maker e taker). As taxas de saque não estão nas respostas da API, e o monitor não as considera.

No Pro e no Max, book_net reconfere os três melhores pares nos order books: /orderbooks/spreads/spot-spot com a moeda do par e volume=1000 devolve as linhas dessa moeda com um objeto order_delta, e a função pega a linha com o mesmo par de exchanges (Δ do order book). Se não há book ou ele acabou, você recebe o status no_book ou exhausted em vez de um número. Uma requisição com coin não tem ETag e sempre custa uma chamada, por isso uma passagem faz só três, definidas por BOOK_TOP.

A tabela no console

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, idade do snapshot {s_age:.0f} s")
    print(f"{'Moeda':<8}{'Compra → venda':<20}"
          f"{'Spread':>7}{'-taxas':>9}{'Book':>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"\nFunding, idade do snapshot {f_age:.0f} s")
    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"Respostas 200: {stats[200]}, 304: {stats[304]}")

A primeira tabela mostra a moeda, o par de exchanges, spread_pct, o que sobra depois das taxas e o que sobra depois do book; um traço significa que o book não foi conferido. A segunda mostra o melhor par de exchanges por funding, com os intervalos de funding e spread_pct. Acima das tabelas fica a idade do snapshot, a hora atual menos meta.updated_at, e abaixo delas o número de respostas 200 e 304 desde o início.

Histórico em CSV

def save(spot, fund):
    """Acrescenta a passagem ao CSV: hora, dataset, par, spreads."""
    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 vira uma célula vazia
        for x in fund:
            b = x["best"]
            w.writerow([ts, "funding", x["coin"], b["exchange_1"],
                        b["exchange_2"], x["spread_pct"], None, None])

A tabela do console dura até a próxima passagem, enquanto o monitor.csv guarda todas as passagens: ele mostra quanto tempo um par dura e em que horários aparece. O módulo csv faz parte da biblioteca padrão do Python. Abra o arquivo com newline="", como exige a documentação do módulo; caso contrário, em sistemas que usam quebras de linha \r\n, um \r a mais vai parar no arquivo.

A coluna book guarda o que sobra depois do book, em porcentagem, ou o status exhausted ou no_book. O módulo grava None como célula vazia, então a coluna fica vazia nas linhas de funding e nos pares não conferidos. Os horários estão em UTC.

O laço principal

def main():
    usage = get("/account/usage")["data"]  # não consome cota
    books = usage["plan"] in ("pro", "max")
    pace["gap"] = 1.1 / usage["rps_limit"]
    print("Plano", usage["plan"], "| snapshot a cada",
          usage["freshness_sec"], "s | order books:",
          "sim" if books else "não")
    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  # chave, plano ou parâmetros: tentar de novo não ajuda
            print("Erro do servidor, nova tentativa:", e)
        except (requests.RequestException, RuntimeError) as e:
            print("Sem resposta, nova tentativa:", e)
        time.sleep(pause)  # mais rápido que freshness_sec = o mesmo snapshot


if __name__ == "__main__":
    try:
        main()
    except KeyboardInterrupt:
        print("\nMonitor parado, o histórico está em", CSV_FILE)

Ao iniciar, o monitor chama /account/usage: a requisição não consome cota e devolve o plano, freshness_sec e rps_limit (Uso). O plano indica ao monitor se deve conferir os order books, e rps_limit define a pausa entre as requisições. O monitor aguenta falhas de rede e erros 5xx até a próxima passagem, enquanto os erros 4xx (chave errada, assinatura vencida, plano sem o endpoint) o param.

Como executar e ler a saída

python3 --version   # é necessário Python 3.10 ou mais recente
python3 -m pip install requests
export GENESIS_API_KEY="gns_live_XXXXXXXXXXXXXXXX"
python3 monitor.py

Saída no plano Pro, um exemplo ilustrativo:

Plano pro | snapshot a cada 10 s | order books: sim

Spot – Spot, idade do snapshot 4 s
Moeda   Compra → venda       Spread   -taxas       Book
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          —

Funding, idade do snapshot 4 s
XYZ     MEXC 4h / Bitget 8h          0.0600 %
ABC     Hyper 1h / CoinEx 8h         0.0500 %
Respostas 200: 6, 304: 0

KLM: o spread da linha é de 1,62%, 1,42% depois de duas taxas e 0,86% depois de US$ 1.000 de order book mais taxas. XYZ ficou sem book em US$ 1.000: para um par assim, você reduz o tamanho ou o descarta. QRS é a quarta linha, então o book dela não foi pedido. A tabela de funding mostra com que frequência cada exchange liquida: Hyper (o nome da Hyperliquid nas respostas) a cada hora e a CoinEx a cada 8 horas. Pressione Ctrl+C para parar o monitor.

Das quatro checagens de um par da lição 3, o monitor faz sozinho a diferença de preço e a transferência, o order book no Pro e no Max, e mostra a atualidade acima da tabela. Você confere o contrato e a taxa de saque.

Prática

  1. Inicie o monitor

    A primeira linha da saída mostra o plano, o passo do snapshot e se os books são conferidos; compare com o seu perfil.

  2. Mova o limiar

    Defina MIN_SPREAD = 0.5 e veja quantas das novas linhas mantêm a coluna -taxas acima de zero.

  3. Adicione um dataset

    Copie spot_rows para /arbitrage/futures-futures: o formato das linhas é o mesmo. Tire a checagem de depósito e saque nos futuros, já que lá nenhuma moeda circula entre exchanges.

  4. Confira o consumo

    Depois de uma hora, chame /account/usage e compare calls_used com a estimativa: no Trial são até 2 × 60 = 120 chamadas por hora.

  5. Encontre pares duradouros

    Abra o monitor.csv em uma planilha e conte quantas passagens seguidas cada par de exchanges durou.

Os riscos da automação, de dados desatualizados e erros a chaves e agentes de IA, estão na lição 5, e as consultas econômicas com filtros, compressão e ETag, no artigo sobre como consultar uma API sem bater nos limites.

Perguntas e respostas

Em que o monitor difere de um bot de arbitragem?

O monitor imprime uma tabela e guarda o histórico; um bot envia alertas sobre pares novos e fica em silêncio sobre os repetidos. Os dois compartilham o código de requisição e filtragem, e o bot do Telegram está em Bot de arbitragem de criptomoedas em Python.

Posso consultar mais rápido que freshness_sec?

Você não vai obter dados novos: seu plano recebe um snapshot a cada freshness_sec segundos. Uma requisição sem filtros antes do próximo snapshot devolve um 304 gratuito, enquanto uma requisição com filtros consome uma chamada pelos mesmos dados.

Por que a coluna Book mostra um traço?

O Δ do order book só existe no Pro e no Max, e o monitor o pede para os três melhores pares (BOOK_TOP). No Trial e no Start, o endpoint devolve 403 plan_restricted, por isso o monitor não o chama.