Genesis Arbitrage

Genesis Arbitrage · · 18 min de leitura

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 o Retry-After em 429 e 503 e 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:

EloO que fazNeste bot
DadosBusca preços e spreads entre exchangesGenesis API GET /arbitrage/spot-spot
FiltroMantém os pares executáveisStatus de depósito e saque, Δ do livro de ofertas para $ 1.000
AlertaInforma o parMétodo sendMessage da API de bots do Telegram
Decisão e operaçãoConfere o par e operaUma 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.

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

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
  1. Espere a primeira rodada

    As mensagens chegam quando o mercado tem pares acima dos seus limites. Se nenhuma chegar em alguns minutos, reduza MIN_SPREAD e MIN_VOLUME por um tempo: isso mostra que a cadeia da API até o Telegram funciona.

  2. 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.

  3. Confira a deduplicação

    O mesmo par não deve chegar de novo em menos de 15 minutos.

  4. Acompanhe o uso de chamadas

    Veja o campo calls_used em /account/usage ou a linha «Chamadas usadas» no seu perfil: no Trial, sem checagem de livro, o bot usa cerca de 1.440 chamadas por dia.

  5. 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.

PlanoConsultaChecagem do livro de ofertas em $ 1.000Chamadas em 30 dias
Trial, $ 20/mêsA cada 60 sNão43.200 de 500 mil
Start, $ 50/mêsA cada 30 sNão86.400 de 2 milhões
Pro, $ 100/mêsA cada 10 sSimAté 1.555.200 de 5 milhões
Max, $ 200/mêsA cada 5 sSimAté 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

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.