Tovanix
Tovanix

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
  • E-mail
  • 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…