api completa para dólar digital.

o que "completa" quer dizer

quase todo time começa com uma necessidade só, em geral "mostrar um endereço de depósito no checkout". um mês depois está cuidando de um nó, um indexador, uma carteira de gás por rede e uma planilha para conciliar tudo. estas são as tarefas que aparecem cedo ou tarde:

em volta delas ficam as chamadas pequenas que evitam chamado no suporte: POST /address/validate e POST /address/detect antes de pagar, GET /balance/{rede}/{endereço}/{token} para o saldo na hora e GET /quote para a taxa exata antes de mover qualquer coisa.

do cadastro ao primeiro endereço

crie a conta no painel com Google, GitHub ou código por e-mail. a primeira chave (dr_live_...) sai ali, no plano free, e vai no cabeçalho X-Api-Key de toda chamada. a URL base é https://api.dolaramp.com/v1.

1. crie uma hotwallet, uma por rede:

curl https://api.dolaramp.com/v1/hotwallets \
  -H "X-Api-Key: dr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"network":"base","label":"acme main"}'

a resposta traz um wallet_secret (ws_...) uma única vez. ele cifra a chave da hotwallet e de todos os filhos; nós guardamos só o texto cifrado. sem ele, nem a dolaramp consegue mover os fundos, então guarde fora do servidor da aplicação. em Base e Arbitrum a hotwallet é um endereço só, válido nas duas redes.

2. gere um endereço de depósito e marque com o seu identificador:

curl https://api.dolaramp.com/v1/hotwallets/base/children \
  -H "X-Api-Key: dr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"wallet_secret":"ws_...","count":1,"external_refs":["order-10432"]}'

até 100 filhos por chamada. o external_ref é seu: número do pedido, id do usuário, lojista:cobrança. ele volta em todo depósito, e você credita o cliente certo sem consulta extra.

a caminho não é confirmado

esta é a parte que custa dinheiro quando sai errada. um depósito tem dois momentos:

• a caminho (arriving): a transferência foi vista na rede. quer dizer "existe uma transação", não "não tem volta". webhook deposit.detected.
• confirmado (confirmed): a regra da própria rede foi cumprida. webhook deposit.confirmed. libere o pedido aqui, nunca antes.

um depósito que não liquida dentro do prazo dispara deposit.abandoned: trate como não recebido.

webhook só em HTTPS, com até 8 tentativas em intervalo crescente (30 segundos, depois dobrando) e assinatura HMAC-SHA256. o segredo aparece uma vez, quando você registra o endpoint em POST /webhooks. a assinatura chega no cabeçalho X-DolaRamp-Signature, como o HMAC em hexadecimal do corpo bruto. confira antes de acreditar no conteúdo:

import { createHmac, timingSafeEqual } from 'node:crypto';

function isFromDolaramp(rawBody, header, secret) {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(header ?? '');
  return a.length === b.length && timingSafeEqual(a, b);
}

calcule sobre os bytes que chegaram, não sobre um JSON remontado. se a sua fila caiu, GET /webhooks/deliveries mostra o que foi enviado e GET /deposits entrega os mesmos fatos por consulta.

varredura e saque, sem tanque de gás

a dor clássica de endereço de depósito: para tirar 20 USDT de um filho, o filho precisa da moeda da rede. multiplique por alguns milhares de endereços e você tem uma operação de gás para cuidar. aqui o gás é patrocinado e a taxa sai de dentro da transferência, em stablecoin.

POST /sweep junta os filhos na hotwallet em lote: por padrão os 20 mais recentes, ou até 20 que você indicar em child_addresses. em Solana, gram(TON), Base e Arbitrum ele responde confirmed com o tx_hash. na TRON responde accepted em 1 a 2 segundos e a confirmação vem por webhook (sweep.confirmed).

um pagamento é uma chamada:

curl https://api.dolaramp.com/v1/hotwallet/withdraw \
  -H "X-Api-Key: dr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"network":"base","token":"USDC","to":"0x...","amount":"10000000",
       "wallet_secret":"ws_...","idempotency_key":"payout-inv-10432"}'

amount vai em microunidades (6 casas), então 10000000 são 10 USDC, e quem recebe fica com o valor menos a taxa. três comportamentos para conhecer antes de produção:

• idempotência. repita com a mesma idempotency_key e volta a operação original, com replayed: true. timeout seguido de nova tentativa nunca paga duas vezes.
• sem pagamento parcial escondido. saque maior que o saldo é recusado com 400 insufficient_balance. na TRON dá para mandar allow_partial: true e enviar o que couber.
• 202 pendente. se a transferência foi entregue à rede mas a chegada não foi vista a tempo, a chamada responde 202 com status: pending. o resultado vem como withdraw.confirmed ou withdraw.failed, em geral dentro de um minuto.

mover usdc entre redes

POST /bridge move USDC entre Solana, Base e Arbitrum pelo CCTP da Circle: queimado na origem, emitido pela Circle no destino, um para um. é troca de rede, não é câmbio: sem pool, sem slippage. o caminho rápido leva de 8 a 20 segundos. o teto é de US$ 10.000.000 por operação e o valor mínimo é US$ 10.

GET /bridge/quote detalha a operação antes de executar: a nossa taxa, a taxa da Circle (repassada sem acréscimo) e quanto chega no destino. a história completa, com tempos medidos, está em mover USDC da Solana para a Base.

quanto custa

o plano free não tem mensalidade, e receber é grátis em todos os planos. você paga por varredura ou saque, em stablecoin, dentro da operação:

o plano free acompanha 1.000 endereços e o pro, 50.000. a ponte custa US$ 2 + 0,3% no free e US$ 2 + 0,2% no pro.

dois custos que pegam de surpresa: a primeira saída de um endereço novo na Solana também paga as contas de token (~US$ 0,65 no free), e um endereço inativo na TRON paga uma ativação única de 1,50 USDT. se os seus clientes pagam pela TRON, prefira um endereço fixo por cliente a um endereço descartável por pedido. de onde vem esse 1,50 está em enviar USDT sem TRX.

valores de pricing a preços de 25/09/2026. Solana e gram(TON) seguem o preço de SOL e TON. GET /v1/quote devolve a taxa exata do seu plano.

o que a api não faz

melhor saber antes de desenhar o sistema em cima dela:

• não mexe com real. a dolaramp não converte moeda, não guarda saldo em banco e não faz PIX. a ponta em reais passa por uma exchange ou PSP autorizado. GET /rates/BRL dá uma referência de mercado do USDT em real; não é cotação executável, então aplique o seu spread. o desenho completo para o Brasil está no guia do gateway de USDT.
• não troca um token por outro. USDT não vira USDC aqui. a ponte move o mesmo ativo, USDC, entre redes.
• não tem ponte para TRON nem gram(TON). a ponte cobre só Solana, Base e Arbitrum.
• uma hotwallet por rede, e 20 filhos por chamada de varredura. para milhares de filhos, faça em laço.
• limite de uso: 120 requisições por minuto por chave.
• não tem rede de teste. a API roda nas redes reais. um jeito barato de ensaiar é usar poucos dólares de USDC na Base, onde a operação custa US$ 0,10.

chaves e segurança

cada chave de API tem um escopo: read (listar, cotar, consultar) ou operate (tudo, inclusive varredura, saque e ponte). uma escrita com chave read responde 403 insufficient_scope, então painéis e relatórios podem rodar com uma chave que não move dinheiro. a chave também pode ser presa a IPs específicos.

o modelo de custódia é o ponto central: as chaves da hotwallet ficam num envelope que só abre com o seu wallet_secret, e toda chamada que move fundos precisa levar esse segredo. mais em security.

os sete perfis de integração (loja, gateway, exchange, só entrada, só saída, pagamentos em massa, cartão cripto) estão desenhados chamada por chamada nos fluxos de integração, e cada endpoint está na referência da API.

perguntas frequentes