Um monitor de spreads e funding em Python
Em resumo
- O monitor é um programa de console: a cada
meta.freshness_secsegundos ele busca os datasets completos/arbitrage/spot-spote/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 comIf-None-Matchantes do próximo snapshot devolve304sem consumir cota. Em429e503, o cliente esperaRetry-Aftersegundos. - 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ção | O que devolve | Quando |
|---|---|---|
/account/usage | Plano, freshness_sec, rps_limit | No início, não consome cota |
/arbitrage/spot-spot | Pares Spot – Spot | A cada passagem, dataset completo |
/funding/spread | Melhores pares de exchanges por funding | A cada passagem, dataset completo |
/orderbooks/spreads/spot-spot | Δ do order book para US$ 1.000 | Pro 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 cota | Pausa | Requisições por passagem | Chamadas em 30 dias |
|---|---|---|---|
| Trial, 500K | 60 s | 2 | 86.400 |
| Start, 2M | 30 s | 2 | 172.800 |
| Pro, 5M | 10 s | 5 | 1.296.000 |
| Max, 10M | 5 s | 5 | 2.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
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.
Mova o limiar
Defina
MIN_SPREAD = 0.5e veja quantas das novas linhas mantêm a coluna -taxas acima de zero.Adicione um dataset
Copie
spot_rowspara/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.Confira o consumo
Depois de uma hora, chame
/account/usagee comparecalls_usedcom a estimativa: no Trial são até 2 × 60 = 120 chamadas por hora.Encontre pares duradouros
Abra o
monitor.csvem 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.