Saltar para o conteúdo principal
Em resumo
A API Withdraw da Blockradar permite enviar ativos stablecoin de suas carteiras para endereços blockchain externos. Suporta saques individuais, saques em lote para múltiplos destinatários e fornece estimativa de taxas antes da execução.
Interface Withdraw da Blockradar

Pré-requisitos

Antes de usar a API Withdraw, certifique-se de ter:
1

Chave de API

Obtenha sua chave de API no Dashboard da Blockradar. Vá até Developers para gerar uma.
2

Carteira criada

Crie uma carteira pelo dashboard (consulte Criar uma Carteira Principal). Você precisará do walletId para as operações de saque.
3

ID do ativo

Obtenha o assetId do token que deseja sacar em Assets no dashboard ou pela API Get Assets.
4

Saldo suficiente

Garanta que sua carteira tenha saldo suficiente do ativo a ser sacado, além do token nativo (ETH, BNB, MATIC, etc.) para cobrir as taxas de rede.

Como funciona

A API Withdraw envia ativos stablecoin de sua carteira Blockradar para qualquer endereço blockchain externo:

Saque individual

Envie ativos para um endereço destinatário com uma única chamada de API.

Saque em lote

Envie ativos para múltiplos destinatários em uma única chamada de API, reduzindo overhead e simplificando pagamentos em massa.

Estimativa de taxas

Calcule as taxas de rede antes da execução para garantir saldo suficiente e exibir os custos aos usuários.

Modo Sign-Only

Assine transações sem transmiti-las para casos de uso avançados como assinatura offline ou envio personalizado.

Master Wallet vs Child Address

A API Withdraw está disponível em dois níveis:

Master Wallet

Saque diretamente de sua master wallet. Ideal para operações de tesouraria e gestão centralizada de fundos.

Child Address

Saque de child addresses individuais. Perfeito para operações específicas de usuário e gestão segregada de fundos.

Endpoints


Saque individual

Envie ativos para um único endereço destinatário.

Parâmetros da requisição

Os parâmetros marcados com * são obrigatórios para saques individuais, mas não são necessários se você estiver usando o array assets para saques em lote.

Exemplo de saque individual

Resposta do saque individual


Memos on-chain

Na Solana, o campo note de um saque é gravado na blockchain como o memo da transação. No Stellar, o memo vem de recipientRouting, e da note quando recipientRouting é omitido. Memos on-chain são públicos — qualquer pessoa pode lê-los em um explorador —, então nunca inclua dados sensíveis em um memo. Nas demais blockchains, a nota não é publicada on-chain. Em todos os casos, a note continua armazenada no registro da transação na Blockradar.

Memos no Stellar

Exchanges e plataformas custodiais costumam compartilhar uma única conta Stellar entre todos os seus clientes e creditam cada depósito pelo memo que emitiram. Um pagamento que chega sem esse memo geralmente não é creditado automaticamente. Defina o memo com recipientRouting: Para sacar para uma conta de exchange que exige um memo ID, passe o ID emitido pela exchange em recipientRouting. A note fica no registro da sua transação e não vai on-chain:
recipientRouting funciona em saques individuais e em cada item de um lote, a partir de master wallets e child addresses. Em um lote, defina-o em cada item de assets; um recipientRouting no nível superior é ignorado quando assets está presente. A resposta do saque retorna recipientRouting como você o enviou, ou null quando omitido. recipientRouting é suportado apenas para destinatários G.... Memos nunca são anexados para destinatários muxed (M...) ou de contrato (C...), então requisições que incluem recipientRouting para eles são rejeitadas — consulte Endereços de destinatário no Stellar.

Sem recipientRouting

Quando recipientRouting é omitido, a note é enviada como o memo: Isso mantém as integrações existentes funcionando, mas publica sua observação interna em um ledger público e a limita a 28 bytes. Use recipientRouting em vez disso: defina o memo de que o destinatário precisa, ou { "type": "none" } para manter a note fora da blockchain.

Validação do memo

A Blockradar verifica o memo quando você faz a requisição. Um memo que não pode ser enviado retorna um 400 e nenhum saque é criado; em um lote, um único item inválido rejeita a requisição inteira. Se uma política retiver o saque para aprovação, a verificação é feita quando o saque é aprovado.
Um objeto recipientRouting malformado falha na validação da requisição, e message é um array: recipientRouting.type must be one of none, memo_id or memo_text, recipientRouting.value must not be supplied when type is none ou recipientRouting.value is required and must be a non-empty string for memo_id (ou memo_text). Em um lote, o caminho inclui a posição do item, por exemplo assets.0.recipientRouting.type must be one of none, memo_id or memo_text.

Memos na Solana

Na Solana, a note é anexada à transação de saque como uma instrução do programa SPL Memo, tanto para saques de SOL quanto de tokens:
  • O memo é sempre texto simples em UTF-8 — a Solana não tem o tipo memo ID, então uma note composta apenas por dígitos é gravada como texto literal.
  • O memo é assinado pelo endereço remetente, de modo que destinatários e indexadores podem verificar que ele veio do remetente.
  • O programa Memo aceita no máximo 566 bytes em UTF-8. Notas mais longas falham durante o processamento — e quanto mais curtas melhor, já que o memo conta para o limite de tamanho de transação da Solana.

Endereços de destinatário no Stellar

No Stellar, o campo address aceita três formatos de destinatário. As mesmas regras se aplicam a saques individuais, saques em lote e estimativa de taxas, tanto nos endpoints de master wallet quanto nos de child address. O modo Sign-Only não é suportado no Stellar.

Contas muxed (M...)

Um endereço muxed incorpora um ID de roteamento sobre uma conta clássica G.... Exchanges e plataformas custodiais os utilizam para creditar o usuário final correto sem depender de um memo. Fundos enviados para um endereço muxed são liquidados na sua conta G... subjacente. Para destinatários muxed, nenhum memo é anexado — o ID de roteamento já está incorporado no próprio endereço. Não envie recipientRouting; requisições que o incluem retornam um 400. Sua note continua armazenada no registro da transação na Blockradar.

Contratos Soroban (C...)

Saques de token para um endereço de contrato são executados como uma invocação transfer no Stellar Asset Contract do token e submetidos via Soroban RPC. On-chain, o resultado é uma invocação de contrato em vez de uma operação de pagamento clássica — tenha isso em mente se as ferramentas do destinatário monitorarem apenas operações de pagamento. Destinatários de contrato são suportados apenas para ativos token:
  • Suportado: saques de token (ex.: USDC, EURC) e a estimativa de taxa de rede correspondente.
  • Não suportado: saques de XLM nativo — enviar XLM para um endereço C... retorna um erro 400. Destinos de saques em fiat, swaps e liquidações automáticas também exigem um endereço clássico G... ou muxed M....
Saques de token para destinatários G... ou M... exigem que a conta de destino exista e tenha uma trustline para o ativo (veja Ativação de Endereços). Destinatários de contrato não têm exigência de trustline, e nenhum memo é anexado a transferências de contrato.

Saques em lote

Envie ativos para múltiplos destinatários em uma única chamada de API. Os saques em lote são executados sequencialmente, e cada saque é processado como uma transação blockchain independente.

Quando usar saques em lote

  • Pagamentos em massa: Pague vários funcionários, fornecedores ou parceiros de uma vez
  • Distribuições: Envie ativos para múltiplos endereços
  • Transferências multidestinatário: Envie valores diferentes para endereços diferentes
  • Eficiência operacional: Reduza chamadas de API e simplifique a lógica de pagamento

Parâmetros da requisição em lote

Para saques em lote, use o array assets em vez de parâmetros individuais: Cada item no array assets:

Exemplo de saque em lote

Resposta do saque em lote

Tratamento de falhas parciais

Os saques em lote suportam sucesso parcial. Se alguns saques falharem, os demais ainda serão executados:

Regras de saque em lote


Estimando taxas de rede

Sempre estime as taxas antes de executar saques para garantir saldo suficiente do token nativo e exibir custos precisos aos usuários.

Estimativa de taxa individual

Resposta de taxa individual

Estimativa de taxa em lote

Estime taxas para múltiplos saques de uma vez:

Resposta de taxa em lote

Campos da resposta de taxa


Modo Sign-Only

Assine transações sem transmiti-las à blockchain. Útil para:
  • Assinatura offline: Prepare transações para envio posterior
  • Fluxos multi-assinatura: Colete assinaturas antes do envio
  • Inspeção de transações: Revise os detalhes da transação antes de transmiti-la
Saques Sign-Only não são suportados no Stellar. Uma solicitação a partir de uma wallet ou address Stellar retorna um 400 com Sign-only withdrawals are not supported on Stellar yet. Para assinar uma transação Stellar que você mesmo constrói, use os endpoints de assinatura.

Exemplo de Sign-Only

Resposta de Sign-Only


Saques de Child Address

Saque de child addresses individuais em vez da master wallet:
Os saques de child address também suportam operações em lote usando o array assets, seguindo o mesmo formato dos saques em lote da master wallet.

Eventos de Webhook

Monitore a conclusão dos saques por meio de webhooks:

Payload do Webhook

networkFee é a taxa de rede total que suas carteiras pagaram por este pagamento, no token nativo da cadeia e em USD. Use para repassar o custo exato ao seu cliente. O detalhamento por transação está disponível no campo networkFees, veja Taxas de rede nos payloads de webhooks.

Exemplo de fluxo completo

A seguir, uma implementação completa do fluxo: estimativa de taxa → confirmação do usuário → saque:

Respostas de erro


Boas práticas

Segurança

  • Valide endereços: Sempre verifique os endereços dos destinatários antes de iniciar saques — o endpoint Validate Address verifica se um endereço é válido para uma determinada blockchain e retorna a forma com checksum para endereços EVM
  • Use referências: Rastreie saques com IDs de referência únicos para conciliação
  • Implemente webhooks: Escute os eventos withdraw.success e withdraw.failed para confirmar o status
  • Verifique AML: A Blockradar faz triagem automática dos endereços; revise quaisquer transações sinalizadas

Gestão de taxas

  • Estime antes de executar: Sempre chame o endpoint network-fee antes dos saques
  • Monitore o saldo nativo: Garanta ETH/BNB/MATIC suficientes para as taxas de gas
  • Use lotes para mais eficiência: Agrupe vários saques para reduzir chamadas de API e overhead operacional

Tratamento de erros

  • Trate falhas parciais: Em saques em lote, verifique tanto o array success quanto errors
  • Implemente retentativas: Use backoff exponencial para falhas transitórias
  • Registre todas as transações: Armazene IDs e hashes de transações para depuração e conciliação

Desempenho

  • Use tamanhos de lote adequados: Lotes maiores reduzem chamadas de API, mas aumentam o tempo de cada requisição
  • Cache os IDs de ativos: Armazene os IDs de ativos localmente para evitar consultas repetidas
  • Implemente limitação de taxa: Respeite os limites de taxa da API para evitar throttling

Referência da API

Endpoints da Master Wallet

Endpoints de Child Address


Suporte

A API Withdraw fornece uma interface flexível para enviar ativos stablecoin para endereços externos. Comece com saques individuais e estimativa de taxas e, em seguida, incorpore operações em lote para pagamentos em massa conforme suas necessidades crescerem.