Bot de arbitragem de criptomoedas em Python: da API de spreads aos alertas no Telegram
Em resumo
- Um bot de arbitragem de criptomoedas tem quatro elos: dados de spreads, um filtro de pares executáveis, um alerta e a decisão de uma pessoa. O código cuida dos três primeiros; as operações você faz nas exchanges.
- Executar é a parte difícil da arbitragem: mover a moeda, taxas, slippage e tempo. Por isso o bot mantém só os pares com saques e depósitos abertos e, no Pro e no Max, recalcula também o spread atravessando $ 1.000 do livro de ofertas.
- O bot consulta a Genesis API no máximo a cada
meta.freshness_sec, espera oRetry-Afterem429e503e alerta sobre um par no máximo uma vez a cada 15 minutos. A versão básica roda no plano Trial de $ 20 por mês.
Um bot de arbitragem de criptomoedas é um programa que busca em intervalos regulares os spreads entre exchanges (a diferença de preço de uma moeda, em porcentagem), mantém os pares que de fato dá para executar e avisa você sobre eles. A decisão e a operação ficam com uma pessoa. Um bot assim para arbitragem spot entre exchanges tem cerca de 140 linhas de Python: os spreads vêm da Genesis API, e as mensagens saem pela API de bots do Telegram.
Do que é feito um bot de arbitragem
Todo bot de arbitragem é construído com quatro elos:
| Elo | O que faz | Neste bot |
|---|---|---|
| Dados | Busca preços e spreads entre exchanges | Genesis API GET /arbitrage/spot-spot |
| Filtro | Mantém os pares executáveis | Status de depósito e saque, Δ do livro de ofertas para $ 1.000 |
| Alerta | Informa o par | Método sendMessage da API de bots do Telegram |
| Decisão e operação | Confere o par e opera | Uma pessoa nas exchanges |
O seu próprio coletor de dados é o elo mais demorado de construir: cada exchange tem sua API, seus nomes de tickers e redes e seus status de depósito e saque, e tudo precisa ser unificado em um formato só. A Genesis API devolve pares prontos de mais de 20 exchanges CEX, entre elas Binance, OKX, Bybit, Bitget, MEXC e Gate, com preços, spread, rede, contrato, status de depósito e saque e volumes. Os campos de cada endpoint de arbitragem estão no guia Endpoints de arbitragem da Genesis API, e a escolha de uma fonte de dados é tratada em API de criptomoedas: tipos e como escolher.
Por que as operações ficam com uma pessoa
Encontrar um spread é a parte fácil da arbitragem. Executar é a parte difícil: quatro obstáculos separam uma linha da resposta da API do dinheiro na sua conta.
- Mover a moeda: o saque e o depósito levam de minutos a horas, e a exchange pode suspender depósitos ou saques a qualquer momento.
- Taxas: as duas exchanges cobram taxa de negociação, e a taxa de saque costuma ser um número fixo de moedas que consome o spread numa operação pequena.
- Slippage: o spread é calculado pelas últimas negociações, mas uma ordem a mercado percorre o livro de ofertas, então a compra é executada acima do melhor ask e a venda abaixo do melhor bid.
- Tempo: os dados chegam com o atraso do seu plano, até 60 segundos no Trial, e outros traders enxergam a mesma diferença e a fecham.
Exemplo hipotético: o bot envia um par com spread de 1,2%, ou seja, $ 12 em $ 1.000. Depois de percorrer os livros de ofertas para $ 1.000, sobram 0,8%, ou $ 8. Uma taxa taker de 0,1% na compra e na venda custa cerca de $ 2, e sacar a moeda custa $ 3.
Um código que compra e saca a moeda sozinho transforma cada uma dessas falhas em uma operação que ninguém conferiu. Por isso este bot envia um sinal: ele mesmo confere saques, depósitos e o spread depois dos livros de ofertas, e uma pessoa verifica o contrato, as taxas e a rota de transferência antes de operar. De qualquer modo, a Genesis API não opera: ela só lê dados e não envia ordens. A conferência manual de um par, passo a passo, está em Arbitragem de criptomoedas entre exchanges.
O que você precisa
- Python 3.10 ou mais recente e a biblioteca
requests. - Uma chave da Genesis API de qualquer plano: clique em «Obter chave» no seu perfil e guarde a chave
gns_live_…, que é exibida uma única vez. Como guardá-la e reemiti-la está no guia Chave da Genesis API. - Um token de bot do Telegram: envie
/newbotpara o @BotFather, escolha um nome e um nome de usuário, e o BotFather responde com um token do tipo123456:ABC-DEF…. chat_id, o ID do seu chat com o bot. Um bot não pode escrever para você primeiro (documentação do Telegram): envie/startpara ele e depois chamegetUpdates; o número em"chat":{"id":…}é o seuchat_id. As atualizações ficam guardadas por no máximo 24 horas.
python3 --version # é preciso Python 3.10 ou mais recente
python3 -m pip install requests
export GENESIS_API_KEY="gns_live_XXXXXXXXXXXXXXXX"
export TG_BOT_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
# depois de /start no chat do bot, procure "chat":{"id":...} na resposta
curl "https://api.telegram.org/bot$TG_BOT_TOKEN/getUpdates"
export TG_CHAT_ID="123456789"
As variáveis definidas com export duram até você fechar o terminal. Segundo a documentação do Telegram, o token dá controle total do bot, e a chave dá acesso ao seu plano; por isso os dois ficam apenas em variáveis de ambiente: nunca vão para o código nem para um repositório.
Código do bot passo a passo
Os sete blocos abaixo formam o bot.py completo: salve-os em um único arquivo, nesta ordem. Os limites das configurações são valores de exemplo; ajuste-os às suas taxas e ao tamanho da operação.
1. Configurações
import os
import time
import requests
API = "https://api.genesisarbitrage.com/v1"
TG = "https://api.telegram.org/bot" + os.environ["TG_BOT_TOKEN"]
CHAT_ID = os.environ["TG_CHAT_ID"]
MIN_SPREAD = 1.0 # spread da linha a partir de 1%
MIN_VOLUME = 50_000 # volume 24 h nas duas exchanges, a partir de $ 50.000
MIN_EXEC = 0.5 # spread após livros de $ 1.000, a partir de 0,5%
TOP = 5 # pares por rodada, no máximo
REPEAT_SEC = 15 * 60 # um par no máximo uma vez a cada 15 minutos
RECHECK_SEC = 5 * 60 # um par que o livro consumiu espera 5 minutos
api = requests.Session()
api.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {} # requisição -> (ETag, resposta)
wait_until = {} # par -> hora até a qual fica em silêncio
A chave viaja no cabeçalho X-API-Key de cada requisição feita pela sessão api e nunca vai na URL. MIN_VOLUME descarta os pares cujo volume de 24 h em qualquer uma das exchanges é inferior a $ 50.000. cache guarda os ETags das respostas, e wait_until guarda a hora até a qual o bot fica em silêncio sobre um par.
2. Chamando a Genesis API: Retry-After e ETag
def get(path, params=None):
"""GET na Genesis API com novas tentativas por Retry-After e ETag."""
key = (path, tuple(sorted((params or {}).items())))
for _ in range(4): # uma requisição e até três novas tentativas
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: # snapshot não mudou
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
body = r.json()
if "ETag" in r.headers: # só conjuntos completos trazem ETag
cache[key] = (r.headers["ETag"], body)
return body
raise RuntimeError("Genesis API ocupada, tentando na próxima rodada")
429 volta quando você excede o rate limit por segundo ou o volume de download, e 503 enquanto os dados são reconstruídos. Os dois trazem Retry-After, e get espera tantos segundos quanto o servidor pedir. Uma cota esgotada também devolve 429, mas com Retry-After igual ao tempo até a renovação, às vezes dias, então o bot para. 400, 401 e 403 não somem ao tentar de novo, por isso raise_for_status os lança. Todos os limites estão no guia Limites da Genesis API.
3. Spreads e filtragem de pares
def candidates():
"""Pares Spot – Spot cuja moeda dá para mover de verdade."""
body = get("/arbitrage/spot-spot",
{"min_spread": MIN_SPREAD, "min_volume": MIN_VOLUME})
# saques abertos na compra, depósitos abertos na venda
rows = [x for x in body["data"]
if x["withdraw_enabled_buy"] and x["deposit_enabled_sell"]]
rows.sort(key=lambda x: x["spread_pct"], reverse=True)
return rows, body["meta"]["freshness_sec"]
min_spread e min_volume filtram as linhas no servidor. Não há parâmetros para os indicadores de depósito e saque, então o código os verifica: a moeda pode ser movida se os saques estiverem abertos na exchange de compra (withdraw_enabled_buy) e os depósitos na de venda (deposit_enabled_sell). Os campos que o bot usa, numa linha da documentação Spot — Spot:
{
"coin": "FUEL",
"exchange_buy": "ByBit",
"exchange_sell": "Gate",
"spread_pct": 0.11,
"network": "ETH",
"contract": "0x675B68AA4d9c2d3BB3F0397048e62E6B7192079c",
"withdraw_enabled_buy": true,
"deposit_enabled_sell": true,
"volume_24h_buy": 17652.64,
"volume_24h_sell": 12512.51,
"trade_url_buy": "https://www.bybit.com/trade/spot/FUEL/USDT",
"trade_url_sell": "https://www.gate.io/trade/FUEL_USDT",
…
}
Esta linha não passaria pelos filtros do bot: um spread de 0,11% e volumes abaixo de $ 50.000. O bot coloca a rede e o contrato na mensagem para você compará-los com as páginas de saque e depósito das duas exchanges.
4. A checagem do livro de ofertas em $ 1.000
def exec_spread(row):
"""Spread após livros de $ 1.000. Só Pro e Max."""
body = get("/orderbooks/spreads/spot-spot",
{"coin": row["coin"], "volume": 1000})
for x in body["data"]:
od = x["order_delta"]
if (x["exchange_buy"] == row["exchange_buy"]
and x["exchange_sell"] == row["exchange_sell"]
and od["status"] == "ok"):
return od["spread_pct"]
return None # no_book, exhausted ou o par sumiu
O endpoint devolve as linhas da moeda no conjunto Spot – Spot com um objeto order_delta: o Δ do livro de ofertas, o spread depois de percorrer os livros, comprando contra os asks da exchange de compra e vendendo contra os bids da exchange de venda. A função pega a linha com as mesmas exchanges e seu order_delta.spread_pct quando status é ok; no_book significa que não há livro, e exhausted que o livro acabou antes de chegar a $ 1.000. Os livros ficam de 5 a 20 segundos atrás da exchange; os campos estão descritos na documentação do Δ do livro de ofertas e no guia de endpoints de livros de ofertas.
Esta etapa existe apenas no Pro e no Max; no Trial e no Start o endpoint devolve 403 plan_restricted. O bot lê o seu plano ao iniciar e pula a checagem nesses planos: a mensagem diz que o livro não foi verificado, e a profundidade você olha por conta própria no terminal da exchange.
5. A mensagem do Telegram
def message(row, ex):
buy, sell = row["exchange_buy"], row["exchange_sell"]
if ex is None:
book = "livro não verificado (Trial ou Start)"
else:
book = f"após livros de $ 1.000: {ex:.2f}%"
return "\n".join([
f'{row["coin"]}: {buy} → {sell}',
f'Spread {row["spread_pct"]}%, {book}',
f'Rede {row["network"]}, contrato {row["contract"] or "—"}',
f'Compra: {row["trade_url_buy"]}',
f'Venda: {row["trade_url_sell"]}',
])
def send(text):
"""sendMessage da API do Telegram; em 429, aguarda retry_after."""
for _ in range(3):
r = requests.post(TG + "/sendMessage", timeout=15, json={
"chat_id": CHAT_ID, "text": text,
"link_preview_options": {"is_disabled": True}})
if r.status_code != 429:
r.raise_for_status() # 400 ou 401: chat ou token errado
return
wait = r.json().get("parameters", {}).get("retry_after", 5)
time.sleep(wait) # controle de flood do Telegram
raise RuntimeError("O Telegram não aceitou a mensagem")
sendMessage recebe chat_id e text de 1 a 4096 caracteres, e a requisição vai para https://api.telegram.org/bot<token>/sendMessage (documentação da API de bots do Telegram). link_preview_options com is_disabled desativa as prévias de links. Sob o controle de flood, o Telegram devolve 429 e coloca a espera, em segundos, em parameters.retry_after. Em um único chat, o Telegram pede que os bots evitem enviar mais de uma mensagem por segundo (FAQ para desenvolvedores de bots).
Uma mensagem fica assim, como exemplo hipotético:
XYZ: MEXC → Gate
Spread 1,4%, após livros de $ 1.000: 0,62%
Rede ETH, contrato 0x…
Compra: https://…
Venda: https://…
6. Deduplicação: um par a cada 15 minutos
def scan(books):
"""Uma rodada: spreads, livros de ofertas, mensagens."""
rows, pause = candidates()
done = 0
for row in rows:
key = (row["coin"], row["exchange_buy"], row["exchange_sell"])
if time.time() < wait_until.get(key, 0):
continue # já avisado, ou o livro consumiu o spread
if done == TOP:
break
done += 1
ex = exec_spread(row) if books else None
ok = not books or (ex is not None and ex >= MIN_EXEC)
if ok:
send(message(row, ex))
# silêncio de 15 minutos após um alerta, 5 se o livro é raso
hold = REPEAT_SEC if ok else RECHECK_SEC
wait_until[key] = time.time() + hold
time.sleep(1) # no máximo uma requisição e uma mensagem por segundo
return pause
Um par é a tripla de moeda, exchange de compra e exchange de venda. Depois de um alerta, o bot fica em silêncio sobre ele por 15 minutos, mesmo que o spread se mantenha. Se o livro consumiu o spread, o bot volta ao par em 5 minutos, de modo que a checagem do livro não gasta uma chamada a cada rodada. Cada rodada pega no máximo os cinco pares de maior spread e pausa um segundo após cada um: isso mantém o bot dentro do que o Telegram recomenda e dentro do limite por segundo de qualquer plano. O dicionário vive na memória, então pares recentes podem se repetir após um reinício.
7. O laço: pausa de pelo menos freshness_sec
def main():
usage = get("/account/usage")["data"] # não consome cota
books = usage["plan"] in ("pro", "max")
pause = usage["freshness_sec"]
print("Plano", usage["plan"], "| consulta a cada", pause, "s",
"| livros de ofertas:", "sim" if books else "não")
while True:
try:
pause = scan(books)
except requests.HTTPError as e:
if e.response.status_code < 500:
raise # chave, plano ou token: tentar de novo não ajuda
print("Erro do servidor, tentando de novo:", e)
except (requests.RequestException, RuntimeError) as e:
print("Sem resposta, tentando de novo:", e)
time.sleep(pause) # não mais que a cada meta.freshness_sec
if __name__ == "__main__":
main()
Ao iniciar, o bot chama /account/usage: a requisição não consome cota e devolve o seu plano e freshness_sec. Essa é a atualidade dos dados, o intervalo em que o seu plano recebe um novo snapshot: 60 segundos no Trial, 30 no Start, 10 no Pro e 5 no Max. Depois disso a pausa vem de meta.freshness_sec, porque consultar mais rápido devolve o mesmo snapshot. Falhas de rede e erros 5xx esperam a próxima rodada, enquanto os demais erros 4xx — chave errada, assinatura expirada, plano sem o endpoint, token ou chat_id errado — param o bot. Os códigos de erro estão em Respostas e erros da Genesis API, e um monitor de spreads sem Telegram é montado na lição Monitor de spreads e funding em Python.
Como executar e conferir
python3 bot.py
# Plano trial | consulta a cada 60 s | livros de ofertas: não
Espere a primeira rodada
As mensagens chegam quando o mercado tem pares acima dos seus limites. Se nenhuma chegar em alguns minutos, reduza
MIN_SPREADeMIN_VOLUMEpor um tempo: isso mostra que a cadeia da API até o Telegram funciona.Compare um par com a tabela
Abra Spot – Spot no site: a mesma moeda e o mesmo par de exchanges estão na tabela. Os números podem diferir um pouco, porque a API entrega o snapshot com o atraso do seu plano.
Confira a deduplicação
O mesmo par não deve chegar de novo em menos de 15 minutos.
Acompanhe o uso de chamadas
Veja o campo
calls_usedem/account/usageou a linha «Chamadas usadas» no seu perfil: no Trial, sem checagem de livro, o bot usa cerca de 1.440 chamadas por dia.Deixe o bot rodando
nohup python3 bot.py >> bot.log 2>&1 &executa o bot em segundo plano; defina as variáveis de ambiente na mesma sessão do terminal.
Qual plano da Genesis API o bot precisa
Uma rodada é uma chamada a /arbitrage/spot-spot, mais até cinco chamadas a /orderbooks/spreads/spot-spot no Pro e no Max; só as respostas 200 consomem cota. Limite superior para 30 dias: (1 + checagens por rodada) × 86.400 / pausa × 30.
| Plano | Consulta | Checagem do livro de ofertas em $ 1.000 | Chamadas em 30 dias |
|---|---|---|---|
| Trial, $ 20/mês | A cada 60 s | Não | 43.200 de 500 mil |
| Start, $ 50/mês | A cada 30 s | Não | 86.400 de 2 milhões |
| Pro, $ 100/mês | A cada 10 s | Sim | Até 1.555.200 de 5 milhões |
| Max, $ 200/mês | A cada 5 s | Sim | Até 3.110.400 de 10 milhões |
No Trial são 86.400 / 60 × 30 = 43.200 chamadas, 8,64% da cota. No Pro, no pior caso em que cada rodada checa cinco livros, dá 6 × 86.400 / 10 × 30 = 1.555.200 chamadas, ou 31,1% da cota. As regras da cota estão na seção Planos e limites da documentação.
Riscos de um bot de arbitragem
- Preços defasados: o snapshot é atualizado a cada
freshness_sece os livros ficam de 5 a 20 segundos atrás da exchange; por isso confira os preços no terminal da exchange antes de operar. - Redes fechadas: os indicadores de depósito e saque valem no momento do snapshot, e a exchange pode fechar os saques enquanto você compra. Um mesmo ticker pode ser tokens diferentes em exchanges diferentes, então compare
contractenetwork. - Taxas e saques:
spread_pctnão os inclui, e uma taxa de saque fixa consome o spread inteiro num valor pequeno. - Spreads falsos em livros rasos: um spread largo de última negociação numa moeda pouco negociada some com a primeira ordem.
min_volumee a checagem de $ 1.000 filtram parte desses pares, mas não todos. - Bater nos limites: requisições extras dentro de um segundo recebem
429comRetry-After: 1, e uma cota esgotada para o bot até a renovação. Usar várias chaves ou contas para contornar os limites viola as regras; existem planos maiores para cargas maiores. O Telegram também responde429sob o controle de flood.
Sem código: alertas do Genesis Arbitrage no Telegram
Se você prefere não escrever nem executar o seu próprio bot, os Alertas do Telegram do Genesis Arbitrage enviam os pares por você. Você cria um bot no @BotFather, cola o token dele no site e escolhe categorias como Spot - Spot, DEX - Futuros, Crosschain e Arbitragem de Funding. Os filtros definem o spread mínimo, as exchanges e as redes, o Status de depósito/saque e o Spread por ordens, e o Tempo de repetição (min) limita a frequência com que um mesmo par volta. O bot pessoal funciona no plano Pro do site, separado dos planos da Genesis API; a configuração está no guia de notificações do Telegram.
Perguntas e respostas
O bot pode operar sozinho?
Não pela Genesis API: a API só entrega dados e não envia ordens. A negociação é adicionada pelas APIs próprias das exchanges com chaves de trading, o que é outro código e risco seu: um spread defasado ou um saque fechado vira uma operação que ninguém conferiu.
Quanto custa um bot como este?
O código é gratuito, e as mensagens do bot para usuários do Telegram também. Você paga pelos dados: a Genesis API começa em $ 20 por mês no Trial, e a checagem do livro de ofertas começa no Pro, a $ 100. Você também precisa de um computador ou servidor que funcione o dia todo.
De qual plano da Genesis API eu preciso?
O Trial basta para o bot básico: /arbitrage/spot-spot está em todos os planos, com um novo snapshot a cada 60 segundos. O Start atualiza os dados a cada 30 segundos. A checagem do Δ do livro de ofertas em $ 1.000 só funciona no Pro e no Max.
Por que o bot enviou um par sem spread restante na exchange?
Os dados chegam com o atraso do seu plano, e outros traders também fecham a diferença. Além disso, o spread da linha é calculado pelas últimas negociações, enquanto você só consegue comprar no ask e vender no bid. Confira os preços e o livro de ofertas no terminal da exchange antes de operar.
Posso colocar o bot no GitHub?
Sim: os termos permitem criar seus próprios bots sobre a Genesis API, e a única restrição é revender os dados brutos como estão. Mantenha a chave e o token fora do repositório. Se a chave for parar em código público, clique em «Reemitir» no seu perfil, e o comando /token no @BotFather substitui o token do bot.