Documentação da API
Documentação de integração da API aberta da Tovanix, organizada por serviço: Pagamentos multichain, Aluguel de energia, API SMTP, API de IA, Cartão virtual, E-mail, Armazenamento de objetos, Verificação e risco de transações, Acesso MCP. Laboratórios: Estúdio de contratos, Reprodução de pagamentos, Laboratório de roteamento de IA.
- Pagamentos multichain
- Aluguel de energia
- API SMTP
- API de IA
- Cartão virtual
- Armazenamento de objetos
- Verificação e risco de transações
- Acesso MCP
USDT / USDC / ETH / TRX / BTC · TRON / EVM / Bitcoin · Assinatura dupla HMAC-SHA256 (pagamento) + RSA-2048 (saída de recursos) · Notificação de liquidação em 30 segundos
Integração em 3 etapas
- 1 Cadastre uma conta e crie um aplicativo Obtenha app_id e app_key em "Meus aplicativos" no console e configure notify_url Cadastre-se grátis →
- 2 Implemente a função de assinatura Pagamento usa HMAC-SHA256 (simétrica); saída de recursos usa RSA-2048 (assimétrica). O SDK oficial encapsula ambas, com exemplos completos em várias linguagens
- 3 Escolha um modo e faça sua primeira transação Um para um (endereço vinculado a usuário, ideal para carteiras/recargas) · Rotação (endereço gerado por pedido, ideal para caixa de e-commerce)
Visão geral
Tovanix suporta dois modos de pagamento que podem ser ativados simultaneamente:
Modo um para um
Usuários vinculam um endereço fixo; todos os recebimentos são notificados proativamente. Ideal para recargas e recebimentos.
- Usuário vincula um endereço fixo de recebimento
- Notificações de recebimento em tempo real
- Suporta pagamentos repetidos
- Verificação de assinatura independente
Modo de rotação
Um endereço é atribuído dinamicamente na criação do pedido e reciclado ao expirar. Ideal para pagamentos únicos.
- Alocação dinâmica de endereços
- Controle de expiração de pedidos
- Conversão automática de câmbio
- Página do caixa
Algoritmo de assinatura
Notificações do modo um para um usam webhook_secret para assinar, não app_key.
1. Use HMAC-SHA256 com o segredo como parâmetro de chave HMAC (não adicionado ao texto)
2. A assinatura é um hexadecimal de 64 caracteres em minúsculas; a comparação diferencia maiúsculas e minúsculas
3. Ao criar um pedido, amount deve ter duas casas decimais (ex.: 100.00), e timeout deve ser um inteiro em texto; mesmo omitido, timeout deve ser assinado como timeout=0 (o servidor sempre o inclui no texto de assinatura)
4. Campos com valor vazio são excluídos do cálculo da assinatura
Proteção contra repetição
Para impedir repetição de requisições interceptadas, chamadas assinadas podem incluir timestamp e nonce; ambos entram na assinatura. Encerrar pedido, vincular e desvincular endereço exigem ambos e retornam 400 se ausentes; nos outros endpoints são opcionais.
/api/v1/pay/close: timestamp e nonce obrigatórios. /api/v1/pay/bind-address e /api/v1/pay/unbind-address: sign_ts e nonce obrigatórios (o campo de horário também aceita timestamp). /api/v1/pay/get-address também usa sign_ts, mas é opcional. Criar pedido, consultar pedido e configuração do aplicativo usam timestamp, opcional: com timestamp e nonce presentes, o servidor verifica janela de tempo e nonce; com apenas um ou nenhum, verifica só a assinatura.
timestamp deve estar a até 300 segundos da hora do servidor; sincronize com NTP. Um nonce não pode ser reutilizado em 5 minutos. Timestamp fora da janela ou nonce repetido é rejeitado: criação e consulta de pedidos retornam HTTP 400; os demais endpoints retornam 401. O campo message informa o motivo.
Vincular endereço
POST /api/v1/pay/bind-address
Atribua um endereço fixo de pagamento a um usuário. Retorna o existente se já estiver vinculado.
Consultar vínculo
POST /api/v1/pay/get-address
Consulte o endereço de pagamento vinculado a um usuário.
Desvincular endereço
POST /api/v1/pay/unbind-address
Desvincule o endereço de pagamento de um usuário.
Criar pedido
POST /api/v1/pay/create
Crie um pedido de pagamento; o sistema atribui automaticamente um endereço de recebimento.
Campos da resposta
amount aceita número e texto: 100 ou "100". Na assinatura, sempre use duas casas decimais, como "100.00".
Consultar pedido
GET /api/v1/pay/query
Consulte o status pelo ID de pedido do usuário. Parâmetros na URL Query.
Encerrar pedido
POST /api/v1/pay/close
Encerre manualmente um pedido não pago; o endereço é reciclado. Apenas pedidos pendentes (status=0) podem ser encerrados.
Consultar configuração do aplicativo
GET /api/v1/pay/app-config
Consulte modos, tokens ativados, configurações de notificações etc. Sem exposição de dados sensíveis.
Notificação do modo um para um
Quando um endereço vinculado recebe uma transferência, o sistema envia POST à notify_url configurada.
Notificações são assinadas com webhook_secret, visualizável ou regenerável nos detalhes do aplicativo.
Campos da notificação
Retorne HTTP 200 ou {"code": 0} ao receber; caso contrário, há novas tentativas automáticas (até 10, com espera exponencial).
Notificação de callback do pedido
Após pagar um pedido em rotação, o sistema envia callback para notify_url.
Callbacks são assinados com webhook_secret, visualizável ou redefinível nos detalhes do aplicativo.
Campos de callback
Qualquer status 2xx conta como entregue; o corpo da resposta não é verificado (retornar {"code": 0} com status diferente de 2xx continua sendo falha). Status diferente de 2xx, sem resposta em 10 segundos, erro de conexão e redirecionamento contam como falha; a plataforma tenta de novo após 30 segundos, 1, 2 e 5 minutos e depois a cada 10 minutos, até 10 vezes. As novas tentativas mantêm o mesmo notify_id, mas trazem sign_ts, nonce e assinatura novos — deduplique por notify_id.
Obter taxa de câmbio
GET /api/v1/rate
Obtenha a cotação em tempo real entre duas moedas
Converter valor
POST /api/v1/convert
Converta um valor usando cotações em tempo real
Cotações em lote
GET /api/v1/rates
Consulte cotações de várias moedas (códigos separados por vírgulas)
Todas as taxas de câmbio
GET /api/v1/rates/all
Obtenha as cotações de todas as moedas suportadas
Taxas de câmbio fiduciárias
GET /api/v1/rates/fiat
Obtenha todas as cotações fiduciárias com base em uma moeda (mais de 30, agrupadas por região)
Status dos pedidos
Os pedidos passam pelos seguintes estados:
Códigos de erro
Códigos de erro unificados da API de pagamento (/api/v1/pay/*); erros da API de saída de recursos ficam na seção Referência.
Visão geral / Pré-requisitos de saídas de recursos
A API de saída de recursos é o lado de desembolso dos pagamentos multichain — envia programaticamente ativos já consolidados na carteira central a endereços externos. Assinatura mútua RSA-2048, lista de IPs permitidos, transmissão adiada, interceptação por notificações multicanal e callback de confirmação na blockchain.
Esta API só usa ativos consolidados na carteira central em custódia do sistema. Em autocustódia, os recursos chegam aos seus endereços sem consolidação, portanto nenhum saldo "consolidado, aguardando saída" é gerado e não pode ser pago por esta API.
Ative em 4 etapas
- Acesse "Pagamentos multichain → Saída por API" no console
- Gere localmente um par RSA-2048 e envie-nos a chave pública
- Configure pelo menos um IP permitido (obrigatório); opcionalmente, endereços permitidos, limite por transação e atraso
- Ative a opção principal; o sistema gera um par de chaves da plataforma para a conta — copie a pública para verificar callbacks
Assinatura · RSA-2048 (saída de recursos)
Todos os endpoints /api/v1/withdraw* exigem os cabeçalhos abaixo. Diferente do HMAC simétrico de pagamento, saídas usam RSA assimétrico — a plataforma só guarda sua chave pública; o risco é o vazamento da privada.
- X-API-Key — API Key da plataforma (Ferramentas e configurações → Gerenciamento de API); deve ter capacidade withdraw
- X-Timestamp — Unix atual em ms; diferença do servidor ≤ 60 segundos
- X-Nonce — Nonce de uso único (uuid), não reutilizável em 5 minutos
- X-Withdraw-Signature — RSA-PKCS1v15-SHA256(caller_private_key, signString), Base64
Regra de concatenação para assinatura
BODY é o corpo HTTP original (JSON sem alteração — não serialize novamente). Em GET, BODY é texto vazio.
Além da assinatura RSA e da lista de IPs permitidos da conta acima, a chave de API deve ter o recurso withdraw e está sujeita à sua própria lista de IPs permitidos: ausência do recurso retorna 403 / 4032, e IP de origem fora da lista retorna 403 / 4033. Ambas as verificações se aplicam a /api/v1/withdraw, /api/v1/balance/withdrawable e /api/v1/fee/quote. Chaves existentes antes desta mudança receberam withdraw automaticamente e não são afetadas; nas novas chaves, selecione-o em Ferramentas e configurações → Gerenciamento de API. Consulte os recursos da chave por GET /api/v1/whoami (com X-API-Key + X-Secret-Key ou assinatura HMAC).
Callback do resultado de saída de recursos
Informe callback_url no corpo ao comprar; após concluir / falhar / cancelar, a plataforma envia POST com o resultado.
- O corpo do callback é assinado com a chave privada da plataforma no cabeçalho X-Platform-Signature
- Verifique com a chave pública da plataforma (copiável nas configurações); algoritmo igual ao das requisições
- Em falhas, tenta em 1m / 5m / 30m / 2h / 6h / 24h — 6 vezes — depois encaminha para atendimento manual
- Retorne HTTP 2xx; qualquer outra resposta é tratada como falha
Cabeçalhos
- X-Timestamp — Timestamp unix atual em milissegundos
- X-Platform-Signature — Base64(RSA-PKCS1v15-SHA256(chave privada da plataforma, string de assinatura))
Regra de concatenação para assinatura
PATH é o caminho de callback_url (sem domínio nem query string) e BODY é o corpo recebido sem alterações — não serialize de novo. Verifique com a chave pública da plataforma da página de configurações.
status é completed / failed / failed_onchain / cancelled; valores e taxas são strings; created_at e completed_at são segundos unix, e 0 quando não há horário de conclusão. O corpo não muda entre tentativas do mesmo pedido — deduplique por order_id.
Iniciar saída de recursos
POST /api/v1/withdraw
Após criar, o status é pending, aguardando o atraso para transmissão automática. Nesse período, você pode pausar / acelerar / cancelar no console.
Descrições dos campos
- chain — string — Sim — tron / eth / bsc / polygon / arbitrum / base / optimism / avax / xlayer / btc
- symbol — string — Sim — USDT / TRX / ETH etc.
- amount — string — Sim — Até 18 casas decimais; use texto para evitar erros de ponto flutuante
- to_address — string — Sim — Destino (deve ser adicionado antes no console se a lista de endereços permitidos estiver ativada)
- memo — string — Não — Descrição (≤500 caracteres); enviada ao usuário da conta com a notificação
- callback_url — string — Não — URL de callback; nenhum envio se vazia
- request_id — string — Altamente recomendado — Chave de idempotência; repetir o mesmo valor na mesma conta retorna o pedido original; se a rede, o símbolo, o endereço ou o valor forem diferentes, retorna 409 e nenhum pedido é criado Sem ele não há proteção de idempotência: repetir após um timeout ou uma resposta 5xx cria um segundo pagamento real.
Campos da resposta
- order_id — string — ID do pedido de saque; usado em "Consultar um saque"
- status — string — Status atual, com os mesmos valores de status_label da consulta. Novo pedido é pending (saldo debitado, aguardando atraso de risco e transmissão); repetir request_id retorna o status real, possivelmente completed, failed etc.
- amount — string — Valor do saque (texto)
- fee — string — Taxa esperada (salva no pedido)
- fee_mode — string — in_amount = descontada do valor (recebido = valor − taxa, saldo debitado pelo valor); out_amount = cobrada separadamente (recebido = valor, saldo debitado por valor + taxa)
- delayed_until — string | null — Transmissão planejada (atraso de risco); null = sem atraso
Consultar status de uma saída de recursos
GET /api/v1/withdraw/:id
Retorna detalhes; pode consultar periodicamente (callback continua recomendado).
Campos da resposta
- id — string — ID de pedido de saque
- request_id — string — Chave de idempotência informada
- chain / symbol — string — Blockchain / símbolo do token
- amount / expected_fee / fee_mode — string — Valor / taxa esperada salva no pedido / modo da taxa (in_amount, out_amount)
- to_address — string — Endereço de destino
- memo — string — Memo (TAG/Memo)
- status / status_label — int / string — Código e rótulo de status; veja "Status do pedido" abaixo
- tx_hash — string — Hash da transação (após transmitir)
- fail_reason — string — Motivo da falha (quando houver)
- delayed_until / broadcast_at / confirmed_at / paused_at / cancelled_at — string | null — Horários das etapas: transmissão planejada / transmissão / confirmação / pausa / cancelamento; null se não atingida
- callback_url / callback_retry — string / int — URL de callback / tentativas realizadas
- callback_state — string — Callback: pending = não chamado ou tentando, success = 2xx recebido, giveup = tentativas esgotadas, no_url = sem URL
- created_at — string — Criação
Consultar saldo disponível
GET /api/v1/balance/withdrawable
Retorna o saldo "consolidado, aguardando saída" por blockchain × ativo. Só essa parte permite saída por API.
Dois níveis: blockchain → símbolo → saldo sacável (texto); só entradas com saldo maior que 0.
Estimativa de tarifas
Retorna a taxa pré-descontada configurada pelo administrador para blockchain × símbolo (valor fixo no estilo OKX).
Campos da resposta
- chain / symbol / amount — string — Parâmetros devolvidos: chain / symbol / amount
- fee_amount — string — Valor da taxa
- fee_asset — string — Ativo de liquidação da taxa
Exemplo cURL completo
Fluxo completo de assinatura e requisição; copie no terminal para testar.
Status do pedido · Saída de recursos
Estados: pending → broadcasted → completed / failed_onchain; entre eles, pode haver paused / cancelled / failed.
- 0 — pending — Saldo debitado; aguardando atraso / ainda não transmitido
- 1 — completed — Transação confirmada na blockchain (permite callback)
- 2 — failed — Falha antes de transmitir (saldo reembolsado)
- 3 — broadcasted — Transmitido; aguardando confirmação
- 4 — failed_onchain — Falha na blockchain (revertida / sem mineração por muito tempo; saldo reembolsado)
- 5 — paused — Pausado manualmente; pode retomar ou cancelar
- 6 — cancelled — Cancelado manualmente; saldo reembolsado
- 7 — broadcasting — Transmitindo (estado transitório breve que evita transmissão dupla)
Códigos de erro · API de saída de recursos
- 400 — Parâmetros inválidos / saldo insuficiente / valor fora dos limites de blockchain × símbolo / endereço inválido
- 401 — API Key inválida / horário muito diferente / nonce usado / assinatura falhou
- 403 — Saída por API não ativada / IP fora da lista da conta; chave sem withdraw (code 4032) ou origem fora da lista da chave (code 4033)
- 404 — Pedido não encontrado
- 429 — Excesso de requisições (até 10 por segundo por conta). A resposta inclui Retry-After: 1; aguarde um segundo e tente novamente com o mesmo request_id
- 5xx — Erro da plataforma; pode repetir (mesmo request_id para idempotência)
Observações de segurança de saídas de recursos
- Guarde a chave privada localmente; vazamento permite que outros enviem recursos em seu nome
- Configure IPs permitidos antes de ativar (obrigatório); IP fora da lista é recusado mesmo com assinatura válida
- Recomendamos também ativar "lista de endereços de saída permitidos" e cadastrar destinos conhecidos
- Após ativar 2FA, o usuário pode usá-la no console para acelerar / cancelar pedidos durante o atraso
- Para pedidos grandes, considere atraso maior (algumas horas) para dar tempo de interceptação manual
Páginas relacionadas: Pagamentos com cripto em várias redes · API de agregação SMTP · Serviços de IA
Carregando…