Cotação MutualDocumentação da operação · cotações por grupo com fees da Mutual · fase 1 (somente cotações)

1. Arquitetura

* A fonte do preço é o ticker (preço de mercado sem fee). Hoje ele é servido pela URL apis-hml (MUTUAL_CRYPTO_ENV=hml); a URL apis (prod) responde no formato "quote" com spread de provider embutido, usado apenas como último recurso. Com QUOTE_TICKER_FALLBACK=true, o sistema prefere o ticker onde quer que ele esteja — quando a Mutual publicar o ticker em prod, basta trocar MUTUAL_CRYPTO_ENV=prod.

2. Fluxo da cotação (/COTAR)

Seleção do preço no ticker (lado do cliente)

3. Fluxo da compra (/COMPRAR)

✅ Pedido recebido!

ID do grupo:
120363406233321709@g.us

ID da Transação:
b571d632-add7-43f8-9750-1e0b75d2f2f1

📅 Data da Operação:
11/07/2026 18:07

Tipo de Operação:
COMPRA USDT

Cotação:
1 USDT = R$ 5,16362

💵 Montante em USDT:
Total: 100.000 USDT
Pendente: 100.000 USDT

💼 Montante em BRL:
Total: R$ 516.361,63
Pendente: R$ 516.361,63

A operação será concluída manualmente por um
operador da Mutual. Aguarde a confirmação
aqui no grupo. 🤝

4. cURLs — todas as chamadas externas

4.1 Mutual · Merchants (produção, cache 60s)

curl --location -G 'https://apis.mutual.app.br/api/v2/resource/merchants' \
  --header 'Authorization: Bearer ak_SUA_CHAVE' \
  --header 'Content-Type: application/json' \
  --header 'x-service-token: SEU_SERVICE_TOKEN' \
  --data-urlencode 'page=1' --data-urlencode 'limit=100'
# usa: id, legalName, status, linkGroups[{channel, groupId, name, active}]
# groupId aceita: JID (…@g.us), link https://chat.whatsapp.com/CODIGO ou código puro

4.2 Mutual · Fees do merchant (produção, cache 60s)

curl --location -G 'https://apis.mutual.app.br/api/v2/resource/fees/merchant/org_3DXaWmcAaguU8rn2ryheTS2kRdw' \
  --header 'Authorization: Bearer ak_SUA_CHAVE' \
  --header 'Content-Type: application/json' \
  --header 'x-service-token: SEU_SERVICE_TOKEN'
# usa: operation + sourceAsset + destinationAsset + feeFixed + feePercentage (match EXATO)

4.3 Mutual · Cotação-base / ticker fonte do preço (NUNCA cacheada — 1 requisição por mensagem da fila)

curl --location -G 'https://apis-hml.mutual.app.br/api/v2/crypto/quote' \
  --header 'Authorization: Bearer ak_SUA_CHAVE' \
  --header 'Content-Type: application/json' \
  --header 'x-service-token: SEU_SERVICE_TOKEN' \
  --data-urlencode 'symbol=USDT-BRL' \
  --data-urlencode 'amount=1000' \
  --data-urlencode 'sourceAsset=BRL' \
  --data-urlencode 'targetAsset=USDT' \
  --data-urlencode 'targetNetwork=TRON'

# Resposta formato TICKER (preço de mercado SEM fee — é a base da cotação):
{"error":false,"message":"Quote fetched successfully","data":{
  "buy":"5.1635","sell":"5.1636","last":"5.1636","high":"5.1659","low":"5.1375",
  "open":"5.1453","vol":"7768643.22971","pair":"USDT-BRL","date":1783801754080}}

4.4 Mutual · Mesmo endpoint em produção formato "quote" — só último recurso

# Mesma chamada em https://apis.mutual.app.br → responde com spread de provider embutido:
{"error":false,"data":{"quote_id":"…","type":"BUY","source_asset":"BRL","target_asset":"USDT",
  "source_amount":"1000000","target_amount":"184501.845018","price":"5.42","fee_bps":50,
  "provider":"MERCADO_BITCOIN","locked_at":"…","expires_at":"…"}}
# 5,42 ≠ mercado (5,1636) → NÃO serve de base. Com QUOTE_TICKER_FALLBACK=true o sistema
# detecta o formato e busca o ticker na URL alternativa automaticamente.

4.5 Evolution · Envio da mensagem ao grupo

curl -X POST 'https://whatsapp.talkhub.me/message/sendText/talkbia' \
  --header 'apikey: SUA_EVOLUTION_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"number":"120363429012757266@g.us","text":"📊 Cotação BRL → USDT (1/10)…"}'

4.6 Evolution · Resolver convite → JID (cache 6h)

curl -G 'https://whatsapp.talkhub.me/group/inviteInfo/talkbia' \
  --header 'apikey: SUA_EVOLUTION_API_KEY' \
  --data-urlencode 'inviteCode=C34dh5vXFPJ8wgOGlE9LYG'
# resposta: { "id": "120363429012757266@g.us", "subject": "teste", … }

4.7 Evolution · Registro do webhook (feito pelo setup.sh)

curl -X POST 'https://whatsapp.talkhub.me/webhook/set/talkbia' \
  --header 'apikey: SUA_EVOLUTION_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"webhook":{"enabled":true,
    "url":"https://cotacaomutual.talkhub.me/webhook?token=SEU_WEBHOOK_TOKEN",
    "webhookByEvents":false,"webhookBase64":false,"events":["MESSAGES_UPSERT"]}}'

4.8 Nosso serviço · Webhook de entrada (contrato genérico p/ testes)

curl -X POST 'https://cotacaomutual.talkhub.me/webhook?token=SEU_WEBHOOK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"channel":"whatsapp","groupId":"120363429012757266@g.us","text":"/COTAR 25K USDT"}'

4.9 Nosso serviço · API do painel

# visão geral (canais, grupos, toggles, filas)
curl 'https://cotacaomutual.talkhub.me/api/panel/overview' -H 'Authorization: Bearer SEU_PANEL_TOKEN'

# liga/desliga bots (compra nasce SEMPRE desligada; ativação manual)
curl -X POST 'https://cotacaomutual.talkhub.me/api/panel/toggle' \
  -H 'Authorization: Bearer SEU_PANEL_TOKEN' -H 'Content-Type: application/json' \
  -d '{"scope":"group","channel":"whatsapp","groupId":"1203…@g.us","feature":"buy","enabled":true}'

# registro detalhado + diagnóstico da cotação-base ao vivo
curl 'https://cotacaomutual.talkhub.me/api/panel/logs?limit=100' -H 'Authorization: Bearer SEU_PANEL_TOKEN'
curl 'https://cotacaomutual.talkhub.me/api/panel/diag/quote?asset=USDT&side=buy&env=hml' -H 'Authorization: Bearer SEU_PANEL_TOKEN'

5. Variáveis utilizadas na cotação

5.1 Parâmetros da requisição de ticker

5.2 Variáveis de ambiente (.env)

5.3 Variáveis do cálculo (por mensagem da fila)

6. Fórmulas e exemplo numérico

taxa = (feeFixed + feePercentage) / 100
       ← as duas fees da Mutual são PONTOS PERCENTUAIS que se SOMAM
       (ex: fixa 0.1 + percentual 0.65 → taxa total de 0,75%)

① Quantidade do ativo (/COTAR 25K USDT — cliente paga mais):
     finalTotal = quantidade × baseUnitPrice × (1 + taxa)

② Orçamento em BRL (/COTAR 5000 BRL USDT — fee sai do orçamento):
     baseAvailable = amountBRL / (1 + taxa)
     quantity      = baseAvailable / baseUnitPrice

③ Venda/conversão da origem (/COTAR 1 BTC BRL — cliente recebe menos):
     net = quantidade × baseUnitPrice × (1 − taxa)

Exemplo real (fee do merchant: fixa 0% + percentual 0,65% = 0,65%)

O grupo vê apenas a cotação final. feePercentage, feeFixed, preço-base sem fee, merchantId e ticker cru ficam SÓ no painel/registro (data/quote-log.jsonl).

7. Requisitos técnicos

8. Resolução de merchants (resiliência)

A listagem GET /resource/merchants pode recusar o service token (Service token not accepted on this endpoint) e a API não expõe merchant por ID — /resource/merchants/{id} responde 404 em HTML (Cannot GET …). O sistema tem quatro níveis; o primeiro que funcionar vence, e o painel mostra qual está em uso.

8.1 Origem dos IDs de organização

8.2 Vincular grupo → merchant pelo link de convite

O usuário final não sabe o JID interno do grupo — ele tem o link de convite. É esse link que se cola no painel; a resolução para JID acontece no clique.

Cada linha de grupo tem um botão vincular que já preenche o formulário. Para remover, deixe o merchant vazio e clique em Desvincular — aceita o link ou o JID, independentemente de qual foi usado no cadastro. O vínculo é gravado em DATA_DIR (volume externo) e sobrevive a reinícios e redeploys.

curl -X POST 'https://cotacaomutual.talkhub.me/api/panel/bind-group' \
  -H 'Authorization: Bearer SEU_PANEL_TOKEN' -H 'Content-Type: application/json' \
  -d '{"channel":"whatsapp","groupId":"https://chat.whatsapp.com/C34dh5vXFPJ8wgOGlE9LYG",
       "merchantId":"org_3G8y…","label":"Grupo VIZZO"}'

# resposta quando o convite resolve:
{"ok":true,"binding":{"channel":"whatsapp","groupId":"120363429012757266@g.us",
  "merchantId":"org_3G8y…","invite":"https://chat.whatsapp.com/C34dh…"},
 "resolvedJid":"120363429012757266@g.us","warning":null}
# warning != null → convite não resolveu agora; o vínculo ficou salvo pelo link

# desvincular: merchantId vazio (link ou JID)
curl -X POST 'https://cotacaomutual.talkhub.me/api/panel/bind-group' \
  -H 'Authorization: Bearer SEU_PANEL_TOKEN' -H 'Content-Type: application/json' \
  -d '{"channel":"whatsapp","groupId":"https://chat.whatsapp.com/C34dh5vXFPJ8wgOGlE9LYG","merchantId":""}'

# catálogo para o seletor + vínculos ativos
curl 'https://cotacaomutual.talkhub.me/api/panel/known-merchants' -H 'Authorization: Bearer SEU_PANEL_TOKEN'

# diagnóstico: testa listagem E consulta individual ao vivo, com status e corpo do erro
curl 'https://cotacaomutual.talkhub.me/api/panel/diag/merchants' -H 'Authorization: Bearer SEU_PANEL_TOKEN'

9. Regras da fase atual

1. Só cotações. ORDERS_ENABLED=false; a chamada de criação de ordem não existe no código.
2. Compra (execução) sempre nasce desligada — ativação exclusivamente manual no painel, por canal ou grupo.
3. Fila de 10 cotações por comando, cada mensagem com requisição própria (sem cache de ticker), interrompível pelo /COMPRAR.
4. 1 cotação = 1 confirmação. O /COMPRAR trava (consome) a cotação; nova confirmação exige /COTAR novo. Validade da cotação para confirmação: 15 min.
5. Argumentos do /COMPRAR são conferidos (ativo e quantidade) contra a cotação ativa — divergência não confirma.
6. Fee exata obrigatória por operation+source+destination — sem fallback silencioso.
7. Nunca citar estado do bot — recursos inativos respondem apenas que a operação será concluída manualmente por um operador da Mutual.
8. Grupo vê só a cotação final; todos os internos vão para o painel e o quote-log (auditoria completa por transactionId).

10. Operação (runbook)

# Primeiro deploy (pergunta só a MUTUAL_API_KEY; gera tokens; registra webhook)
cd /root/cotacaomutual.talkhub.me && bash setup.sh

# Atualização rápida
git pull && docker build -t cotacaomutual:latest . && \
docker service update --image cotacaomutual:latest --force cotacaomutual_cotacaomutual

# Redeploy limpo (remove stack, limpa imagens do serviço, rebuild --no-cache, preserva .env e volume)
bash redeploy.sh            # flags: --no-pull · --wipe-data · --yes

# Observabilidade
docker service logs -f cotacaomutual_cotacaomutual
https://cotacaomutual.talkhub.me/painel     # toggles, fila ao vivo, merchants/fees, registro, diagnóstico
https://cotacaomutual.talkhub.me/health