- v2 · Recomendado
- v1 · Legacy
Em resumo
A API de Saque em Fiat da Blockradar converte stablecoins suportadas em fiat e envia para contas bancárias, mobile money e outros rails locais. O fluxo v2 descobre os métodos de pagamento disponíveis para um corredor, retorna um schema descrevendo exatamente o que cada método precisa, resolve campos como o nome da conta do beneficiário e, então, cota e executa o saque a partir de uma master wallet ou child address.
A API de Saque em Fiat da Blockradar converte stablecoins suportadas em fiat e envia para contas bancárias, mobile money e outros rails locais. O fluxo v2 descobre os métodos de pagamento disponíveis para um corredor, retorna um schema descrevendo exatamente o que cada método precisa, resolve campos como o nome da conta do beneficiário e, então, cota e executa o saque a partir de uma master wallet ou child address.

Os métodos de pagamento v2 retornam um JSON Schema descrevendo os detalhes do
beneficiário e do pagamento que sua aplicação deve coletar. Consulte
Formulários Dinâmicos para renderizar, validar,
resolver e enviar esses campos. O fluxo v1 está disponível na aba v1 · Legacy, mas não é mais recomendado.
Pré-requisitos
Antes de usar o Saque em Fiat, certifique-se de ter:1
Compliance aprovado
Conclua o processo de Due Diligence no Dashboard: My Wallets → Settings → Compliance. Os requisitos de conformidade e os processos de aprovação variam por região, então você só precisa concluir os que se aplicam aos rails locais que seu produto usa.
2
Chave de API
Obtenha sua chave de API no Dashboard da
Blockradar. Acesse Developers para
gerá-la.
3
Wallet criada
Crie uma wallet pelo dashboard. Você precisará do
walletId para as
operações de saque.4
Asset ID
Consulte os ativos fiat suportados usando Get Supported
Assets. Use o
id retornado como o assetId ao longo do fluxo.Como funciona
O fluxo v2 é orientado por corredor: você escolhe um ativo, uma moeda e um valor e, então, descobre os métodos de pagamento que suportam esse corredor e coleta exatamente o que cada método exige.Descobrir ativos
Consulte as stablecoins suportadas para saques.
Obter moedas e taxas
Liste as moedas de pagamento suportadas e obtenha a taxa atual.
Listar métodos de pagamento
Descubra os métodos disponíveis para o ativo, a moeda e o valor.
Obter requisitos
Recupere o JSON Schema que descreve os campos que o método precisa.
Resolver e cotar
Resolva campos como o nome da conta e, então, cote taxas e câmbio.
Executar
Envie
paymentMethodData para processar o saque.Moedas fiat suportadas
As moedas variam por corredor e provedor. Sempre obtenha a lista ao vivo com Get Supported Currencies em vez de fixá-la no código. O panorama abaixo mostra USD, EUR e os principais corredores da América Latina; veja a matriz completa de fiat por blockchain na página Moedas Fiat Suportadas.Master Wallet vs Child Address
O Saque em Fiat está disponível em dois níveis:Master Wallet
Realize saques a partir da master wallet. Ideal para operações de tesouraria.
Child Address
Realize saques a partir de uma child address específica. Útil para fluxos por usuário.
Endpoints
Os endpoints de descoberta (ativos, moedas, taxas, métodos de pagamento,
requisitos, resolução) têm escopo na master wallet. Assim que você tiver um
objeto
paymentMethodData validado, poderá cotar e executar a partir da master
wallet ou de uma child address.Fluxo típico
- Consulte os ativos suportados para escolher a stablecoin a sacar.
- Obtenha moedas e taxa para o corredor escolhido e guarde o
sessionIdretornado. - Liste os métodos de pagamento usando essa sessão.
- Obtenha os requisitos do método selecionado para receber seu schema.
- Resolva campos como o nome da conta e, então, colete e valide
paymentMethodData. - Obtenha uma cotação usando a mesma sessão para mostrar taxas e câmbio antes da execução.
- Execute usando a mesma sessão e acompanhe o status com webhooks.
O endpoint de taxas v2 inicia uma sessão de roteamento de provedor. Trate o
sessionId dele como a referência oficial para o restante do fluxo: ele vincula
a wallet, o ativo da wallet, a moeda, o valor, o lado do valor, o provedor e
a rota de conversão por 20 minutos. Não misture uma sessão com valores de
roteamento de outra solicitação de taxa. Se a API retornar
FIAT_WITHDRAWAL_SESSION_EXPIRED ou FIAT_WITHDRAWAL_SESSION_UNAVAILABLE,
solicite uma nova taxa e reinicie o fluxo.Etapa 1: Obter ativos suportados
Consulte as stablecoins disponíveis para saque e pegue oid desejado como o
assetId.Etapa 2: Obter moedas e taxa
Liste as moedas de pagamento suportadas e, então, obtenha a taxa atual para o ativo, a moeda e o valor.Rate Response
Etapa 3: Listar métodos de pagamento
Descubra os métodos de pagamento disponíveis para o corredor vinculado à sessão. Passe osessionId retornado pela Etapa 2; opcionalmente, restrinja por
country ou paymentMethodCategory.Payment Methods Response
requirementsRef, procure o schema dele em
data.requirements[requirementsRef]. Vários métodos podem referenciar a mesma
entrada, por isso a API retorna um schema compartilhado apenas uma vez. Um método
sem requirementsRef não tem requisitos de formulário.supportsPaymentMethodResolution: true significa que o schema do método pode
incluir um campo x-resolution (como uma busca de nome de conta) que você
resolve antes de cotar. Consulte a
Etapa 5.Etapa 4: Ler os requisitos do método de pagamento
Leia o JSON Schema do método selecionado no registro compartilhadorequirements
retornado na Etapa 3. Interprete-o e preencha-o com
Formulários Dinâmicos. Isso não exige outra
requisição à API.Requirements Response
Etapa 5: Resolver campos e montar paymentMethodData
Colete os campos em data.schema. Quando um campo carrega x-resolution (como
accountName acima), chame o endpoint de resolução assim que seus campos
dependsOn forem válidos e, então, armazene o resultado nesse campo.Resolve Response
paymentMethodData completo fica assim:Etapa 6: Obter uma cotação
Sempre obtenha uma cotação antes de executar para poder exibir a taxa de câmbio, as taxas e o tempo estimado de chegada ao usuário. Envie opaymentMethodData
validado.Quote Response
Fixar o valor a receber
Escolha o lado do valor ao solicitar a taxa que cria a sessão. Por padrão,amount é o valor em stablecoin que você envia (amountSide: "source"). Para
entregar um valor fiat exato, defina amountSide=target na requisição de taxas.
A sessão resultante preserva essa escolha na cotação e na execução.amountSide: "target", o destinatário recebe exatamente o valor fiat que
você especificar — 155.000 NGN no exemplo acima — e o debitAmount da cotação
mostra o stablecoin que será debitado, derivado da taxa e arredondado para cima
até a precisão decimal do ativo, para que o pagamento nunca fique abaixo do
valor. amountSide está disponível apenas nos endpoints v2.Etapa 7: Executar o saque
Assim que o usuário aceitar a cotação, execute com os mesmos dados. Adicione umreference opcional para idempotência e rastreamento, além de metadata e
note conforme necessário.Resposta da execução
Sacar de uma Child Address
Para pagar a partir de uma child address específica, cote e execute nos endpoints com escopo de endereço usando os mesmos corpos de requisição:Webhooks
Acompanhe o status do saque com os seguintes eventos de webhook:Exemplo de payload do webhook
Exemplo de fluxo completo
Uma implementação v2 completa mostrando o fluxo descobrir → requisitos → resolver → cotar → executar:Respostas de erro
Dados do método de pagamento inválidos
Dados do método de pagamento inválidos
Moeda não suportada
Moeda não suportada
Ativo não suportado
Ativo não suportado
Recurso não habilitado
Recurso não habilitado
Saldo insuficiente
Saldo insuficiente
Saldo nativo insuficiente
Saldo nativo insuficiente
Boas práticas
Experiência do usuário
- Resolva antes de cotar: Confirme o nome da conta do beneficiário via endpoint de resolução antes de mostrar uma cotação.
- Mostre o custo total: Exiba a taxa de câmbio, a taxa de transação, a taxa de rede e o
debitAmount. - Exponha o estado de processamento: Use webhooks para atualizar os usuários em tempo real.
Correção
- Mantenha uma sessão por tentativa: Passe o
sessionIdretornado pelas taxas pelos métodos de pagamento, pela resolução, pela cotação e pela execução. - Reinicie sessões expiradas: Solicite uma nova taxa em vez de tentar novamente uma sessão expirada ou indisponível.
- Use o schema retornado: Colete apenas os campos no schema de requisitos atual. Não fixe campos de beneficiário no código — consulte Formulários Dinâmicos.
- Preserve as strings: Envie
amounte os identificadores de conta como strings para evitar perda de precisão. - Use referências: Acompanhe os saques com um
referenceúnico para novas tentativas seguras. - Confirme via webhooks: Trate
offramp.successcomo a fonte final da verdade.
Desempenho
- Cacheie as listas de ativos e moedas: Atualize periodicamente em vez de a cada requisição.
- Reobtenha as taxas a cada tentativa: Uma taxa v2 cria uma sessão de roteamento de 20 minutos para aquela tentativa de saque.
- Repita em erros transitórios: Use backoff exponencial para respostas 5xx.
Referência da API
v2 (Recomendado)
Suporte
- E-mail: [email protected]
- Chat ao vivo: Disponível no dashboard

