gateway de usdt no brasil, do pix ao webhook.

as duas pontas do gateway

um projeto de "gateway de USDT" junta duas coisas bem diferentes:

• a ponta on-chain: gerar endereço, saber que o dinheiro chegou, consolidar e pagar. é o que a API da dolaramp faz, em Solana, TRON, gram(TON), Base e Arbitrum, com USDT, USDC e PYUSD conforme a rede.
• a ponta em reais: receber PIX, entregar PIX, fazer o câmbio entre real e stablecoin. isso é de uma exchange ou de um PSP autorizado. a dolaramp não guarda real, não converte e não faz PIX.

separe as duas desde o desenho: integrar uma API de carteira não resolve a parte regulada.

a arquitetura on-chain, passo a passo

1. hotwallet. você cria uma por rede. a API devolve um wallet_secret uma única vez; ele cifra a chave da hotwallet e de todos os filhos, e sem ele nem a dolaramp consegue mover os fundos.
2. endereço filho. POST /hotwallets/{rede}/children gera até 100 endereços por chamada, cada um com o seu external_ref (o número do pedido, ou lojista:cobrança). esse é o endereço que aparece no QR do checkout.
3. webhook. quando o pagamento aparece na rede chega deposit.detected, que só serve para mostrar "pagamento a caminho". o pedido libera no deposit.confirmed, que só dispara quando a regra da rede foi cumprida (solidificação na TRON, finalized na Solana, safe head em Base e Arbitrum). o payload já traz o external_ref, então você credita o lojista sem consulta extra. os webhooks são assinados com HMAC-SHA256: valide a assinatura antes de acreditar.
4. varredura. POST /sweep move o saldo dos filhos para a hotwallet em lote, sem você ter TRX, SOL ou ETH. use idempotency_key: repetir a chamada depois de um timeout devolve o mesmo lote em vez de varrer de novo.
5. saque. o lojista pede o dinheiro dele e o seu sistema chama POST /hotwallet/withdraw com idempotency_key = id do saque. um saque maior que o saldo é recusado, nunca enviado pela metade sem você pedir.
6. conciliação. GET /ledger e GET /operations fecham o dia sem depender de webhook, e GET /statement?month= entrega o mês inteiro, com taxas, para a contabilidade.

o mapa desse fluxo está em fluxos de integração (perfil "gateway"), e cada chamada está na referência da API.

filho por pedido ou filho por cliente

as duas funcionam, mas o custo muda conforme a rede:

• filho por pedido deixa a conciliação trivial: um endereço, um valor, um pedido. na TRON, porém, todo endereço novo paga uma ativação de 1,50 USDT uma única vez na primeira movimentação, e na Solana um endereço novo paga as contas de token na primeira saída (~US$ 0,65 no free).
• filho por cliente (fixo) dilui esse custo: o comprador recorrente paga sempre no mesmo endereço, e o external_ref identifica quem é.

em Base e Arbitrum um filho é um único endereço válido nas duas redes, e conta uma vez só no limite do plano (1.000 endereços no free, 50.000 no pro).

quanto custa, por rede

receber é grátis. você paga por varredura ou saque, em stablecoin, dentro da própria operação:

a conta honesta para um pedido de 100 USDT pago na TRON num filho novo: varredura de 1,60 + ativação de 1,50 = 3,10 USDT, ou 3,1%. o mesmo pedido em USDC na Base custa 0,10. se os seus clientes pagam pela TRON, aceite, mas com filho fixo por cliente e varredura em lote, não um filho descartável por pedido. o guia de USDT TRC20 sem TRX explica de onde vem esse 1,50.

valores de pricing em 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 antes de qualquer operação.

a ponta em reais: PIX por parceiro

se o cliente paga em real e o lojista quer receber em real, existe um parceiro no meio. ele recebe e envia PIX, compra e vende a stablecoin e responde pelo câmbio:

• entrada (real → USDT): o parceiro recebe o PIX, compra a stablecoin e envia para a sua hotwallet, no deposit_address dela.
• saída (USDT → real): você saca para o endereço do parceiro, ele vende e paga o PIX do lojista.
• preço: GET /rates/BRL dá uma referência de mercado do USDT em real. não é cotação executável: aplique o seu spread.

escolha o parceiro olhando a situação dele no Banco Central, não só a taxa. a próxima seção explica por quê.

o que diz a regulação (setembro de 2026)

o que segue é o texto das normas, não parecer jurídico.

• a base. a Lei 14.478, de 21/12/2022, criou o marco dos ativos virtuais. o BCB regulamentou com as Resoluções BCB 519, 520 e 521, de 10/11/2025 (DOU de 11/11/2025), em vigor desde 2/02/2026.
• quem é PSAV. serviço de ativo virtual é, segundo o BCB, "realizar, em nome de terceiros, compra, venda, intermediação e custódia de criptoativos". as sociedades prestadoras (SPSAV) têm três modalidades: intermediária, custodiante e corretora (Res. 520, art. 4º).
• autorização antes de operar. a SPSAV "deve solicitar autorização ao Banco Central do Brasil para iniciar" os serviços (Res. 520, art. 19). quem já operava em 2/02/2026 tem 270 dias para pedir, ou seja, até 30/10/2026 (art. 88).
• bancos e instituições de pagamento. a partir de 6/11/2026, elas ficam proibidas de realizar ou viabilizar operações com prestadoras de serviços de ativos virtuais que não estejam autorizadas pelo BCB, o que inclui contas e transações de pagamento (Res. 520, art. 91, na redação da Res. BCB 589, de 23/09/2026). na prática: o PIX do seu parceiro depende da autorização dele.
• stablecoin é câmbio. a Res. 521 incluiu no mercado de câmbio a compra, venda ou troca de ativo virtual referenciado em moeda fiduciária, o pagamento internacional com ativo virtual e a transferência de ou para carteira autocustodiada. a prestadora tem que identificar o dono dessa carteira. se o seu gateway recebe USDT de uma exchange na sua hotwallet, espere que ela peça prova de que o endereço é seu.

a dolaramp é tecnologia: a chave fica selada com o seu wallet_secret e nós não guardamos o seu saldo. isso não decide se o seu gateway é ou não PSAV. um gateway que guarda saldo de lojistas e movimenta em nome deles precisa ler os arts. 7º e 9º da Res. 520 contra o próprio modelo. contrate assessoria jurídica antes de operar; não conte com "é só software" como resposta.

checklist antes de subir

• libere pedido só no deposit.confirmed, nunca no deposit.detected.
• valide a assinatura HMAC de cada webhook e trate reentrega (até 8 tentativas, com intervalo crescente).
• idempotency_key em toda varredura e todo saque.
• guarde o wallet_secret fora do servidor da aplicação.
• situação do parceiro de PIX no BCB conferida, e parecer jurídico sobre o enquadramento do seu próprio gateway.

perguntas frequentes