Saque em Fiat - Blockradar

Em resumo
A API de Saque em Fiat da Blockradar permite converter stablecoins suportadas em moeda fiat e transferir os fundos para contas bancárias. Você pode consultar os ativos suportados, validar contas bancárias, obter cotações e executar saques tanto a partir de master wallets quanto de child addresses.

Interface de Saque em Fiat da Blockradar

Pré-requisitos

Antes de usar o Saque em Fiat, certifique-se de ter:

Requisito de conformidade

Conclua a integração de parceiro antes de solicitar acesso ao Saque em Fiat (consulte Requisitos de conformidade abaixo).

Chave de API

Obtenha sua chave de API no Dashboard da Blockradar. Acesse Developers para gerá-la.

Wallet criada

Crie uma wallet pelo dashboard. Você precisará do walletId para as operações de saque.

Asset ID

Consulte os ativos fiat suportados usando Get Supported Assets.

Dados da conta bancária

Reúna um identificador de conta válido e o identificador da instituição (código bancário).

Como funciona

O Saque em Fiat segue uma sequência simples:

Descobrir ativos

Consulte os ativos suportados para saques.

Obter moedas fiat

Recupere todas as moedas suportadas.

Obter taxas

Consulte a taxa de câmbio atual para o ativo selecionado.

Verificar conta

Valide os dados da conta da instituição antes de iniciar um saque.

Obter cotação

Estime as taxas e a taxa de câmbio para o valor solicitado.

Executar

Envie o saque para processamento.

Moedas fiat suportadas

Moeda	Código
Xelim queniano	KES
Naira nigeriana	NGN
Xelim tanzaniano	TZS
Xelim ugandense	UGX
Real brasileiro	BRL
Kwacha malauiano	MWK

Requisitos de conformidade

Antes de acessar o Saque em Fiat, conclua o processo de integração de conformidade aplicável para a cobertura de moedas de pagamento.

Escolha seu caminho de integração

Apenas NGN (Naira): Preencha o formulário de integração apenas para Naira.
Outras moedas africanas: Conclua a integração de parceiro para moedas africanas.

Se precisar de acesso tanto a NGN quanto a outras moedas africanas suportadas, conclua os dois fluxos de integração.

Requisito de aprovação

O acesso ao Saque em Fiat é habilitado após a revisão e aprovação de conformidade para o caminho de integração selecionado.

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

Operação	Master Wallet	Child Address
Get Supported Assets	`GET /v1/wallets/{walletId}/withdraw/fiat/assets`	—
Get Institutions	`GET /v1/wallets/{walletId}/withdraw/fiat/institutions`	—
Get Exchange Rates	`GET /v1/wallets/{walletId}/withdraw/fiat/rates`	—
Get Currencies	`GET /v1/wallets/{walletId}/withdraw/fiat/currencies`	—
Verify Institution Account	`POST /v1/wallets/{walletId}/withdraw/fiat/institution-account-verification`	—
Get Quote	`POST /v1/wallets/{walletId}/withdraw/fiat/quote`	`POST /v1/wallets/{walletId}/addresses/{addressId}/withdraw/fiat/quote`
Execute	`POST /v1/wallets/{walletId}/withdraw/fiat/execute`	`POST /v1/wallets/{walletId}/addresses/{addressId}/withdraw/fiat/execute`

Fluxo típico

Consulte os ativos suportados para escolher a stablecoin a sacar.
Liste as instituições e selecione um identificador de banco/instituição.
Verifique a conta para confirmar o nome e os dados da conta.
Obtenha uma cotação para mostrar as taxas e a taxa de câmbio antes da execução.
Execute o saque e acompanhe o status no seu sistema.

Etapa 1: Obter uma cotação

Sempre obtenha uma cotação antes de executar um saque para poder exibir a taxa de câmbio e as taxas ao usuário.

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`assetId`	string	Sim	ID do ativo stablecoin a sacar
`amount`	string	Sim	Valor a sacar nas unidades do ativo
`currency`	string	Sim	Moeda fiat de destino (ex.: `NGN`)
`accountIdentifier`	string	Sim	Número ou identificador da conta bancária
`institutionIdentifier`	string	Sim	Código do banco/instituição

Exemplo de cotação

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/withdraw/fiat/quote \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assetId": "asset-uuid-here",
    "amount": "1000",
    "currency": "NGN",
    "accountIdentifier": "0023103996",
    "institutionIdentifier": "SBICNGLA"
  }'

Etapa 2: Executar o saque

Depois de aceitar a cotação, execute o saque com os mesmos dados.

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`assetId`	string	Sim	ID do ativo stablecoin a sacar
`amount`	string	Sim	Valor a sacar nas unidades do ativo
`currency`	string	Sim	Moeda fiat de destino (ex.: `NGN`)
`accountIdentifier`	string	Sim	Número ou identificador da conta bancária
`institutionIdentifier`	string	Sim	Código do banco/instituição
`reference`	string	Não	Referência do cliente para idempotência/rastreamento
`metadata`	object	Não	Metadados chave-valor anexados à transação
`note`	string	Não	Nota legível por humanos para este saque

Exemplo de execução

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/withdraw/fiat/execute \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assetId": "asset-uuid-here",
    "amount": "1000",
    "currency": "NGN",
    "accountIdentifier": "8034007516",
    "institutionIdentifier": "OPAYNGPC",
    "reference": "WD-20260303-001",
    "metadata": {
      "source": "payroll",
      "initiatedBy": "treasury-bot"
    },
    "note": "March payroll payout"
  }'

Resposta da execução

{
  "status": true,
  "message": "Successful",
  "data": {
    "id": "db53c3ef-5643-4f98-92cf-d02aef300f45",
    "reference": "WD-20260303-001",
    "senderAddress": "0x969838345E5cd5F755DfcADB57e72F5d23271e48",
    "recipientAddress": "0x30F6A8457F8E42371E204a9c103f2Bd42341dD0F",
    "tokenAddress": "0x46C85152bFe9f96829aA94755D9f915F9B10EF5F",
    "amount": "1000",
    "amountPaid": "1000",
    "amountUSD": "0.68",
    "rateUSD": "0.00068",
    "fee": "2",
    "currency": "NGN",
    "toAmount": "1000.00",
    "toCurrency": "NGN",
    "status": "PENDING",
    "processingStatus": "PENDING",
    "processingProviderReference": null,
    "processingReason": null,
    "type": "OFFRAMP",
    "createdChannel": "api",
    "network": "mainnet",
    "chainId": null,
    "note": "March payroll payout",
    "metadata": {
      "source": "payroll",
      "initiatedBy": "treasury-bot"
    },
    "beneficiary": {
      "id": "4dd8d16e-8550-4f51-84a1-60df9c608c5d",
      "name": "JOHN DOE",
      "type": "FIAT",
      "isActive": true,
      "institutionIdentifier": "OPAYNGPC",
      "institutionAccountIdentifier": "8034007516",
      "currency": "NGN"
    }
  }
}

Webhooks

Acompanhe o status do saque com os seguintes eventos de webhook:

Evento	Descrição
`offramp.processing`	O saque está sendo processado
`offramp.success`	Saque concluído com sucesso
`offramp.failed`	O saque falhou

Exemplo de payload do webhook

{
  "event": "offramp.processing",
  "data": {
    "id": "d2b985da-7f7e-4494-a6bc-0e675d50eed3",
    "reference": "EVF2g9X70Sj4hoX3ma8l",
    "senderAddress": "0x969838345E5cd5F755DfcADB57e72F5d23271e48",
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "0.5",
    "amountPaid": "0.5",
    "amountUSD": "0.4998",
    "rateUSD": "0.9996",
    "fee": "0",
    "feeUSD": null,
    "currency": "USD",
    "toCurrency": "NGN",
    "status": "PROCESSING",
    "processingStatus": "SUCCESS",
    "processingProviderReference": "0x25003cb8356c92e3c296e7dd384ead681c5f57fb6182760fa4178750464ffd35",
    "processingReason": null,
    "type": "OFFRAMP",
    "createdChannel": "api",
    "network": "mainnet",
    "chainId": 8453,
    "metadata": null,
    "toAmount": "711.21",
    "rate": "1422.42",
    "beneficiary": {
      "id": "4dd8d16e-8550-4f51-84a1-60df9c608c5d",
      "name": "JOHN DOE",
      "type": "FIAT",
      "isActive": true,
      "reference": "d7dd5c7cf57acb5e2ff62eb23bceaca84d5dad6e62fec3d3836f20cfa1ea735c",
      "institutionIdentifier": "OPAYNGPC",
      "institutionAccountIdentifier": "8030303030",
      "currency": "NGN"
    }
  }
}

Exemplo de fluxo completo

A seguir, uma implementação completa mostrando o fluxo verificar → cotar → executar:

async function executeFiatWithdrawal({
  walletId,
  currency,
  accountIdentifier,
}) {
  const apiKey = process.env.BLOCKRADAR_API_KEY;
  const baseUrl = "https://api.blockradar.co/v1";
  const headers = { "x-api-key": apiKey };

  // Step 1: Get supported assets
  const assetsRes = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/assets`,
    { headers },
  ).then((r) => r.json());

  // Pick the first asset (example)
  const assetId = assetsRes.data?.[0]?.asset?.id;

  // Step 2: Get supported currencies
  const currenciesRes = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/currencies`,
    { headers },
  ).then((r) => r.json());

  console.log("Supported currencies:", currenciesRes.data);

  // Step 3: Get institutions for the currency
  const institutionsRes = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/institutions?currency=${currency}`,
    { headers },
  ).then((r) => r.json());

  // Pick the first institution (example)
  const institutionIdentifier = institutionsRes.data?.[0]?.code;

  // Step 4: Verify account
  const verification = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/institution-account-verification`,
    {
      method: "POST",
      headers: {
        ...headers,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        accountIdentifier,
        currency,
        institutionIdentifier,
      }),
    },
  ).then((r) => r.json());

  console.log("Account name:", verification.data?.accountName);

  // Step 5: Get exchange rate (optional)
  const amount = "1000";
  const ratesRes = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/rates?currency=${currency}&assetId=${assetId}&amount=${amount}`,
    { headers },
  ).then((r) => r.json());

  console.log("Rate:", ratesRes.data);

  // Step 6: Get quote
  const quote = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/quote`,
    {
      method: "POST",
      headers: {
        ...headers,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        assetId,
        amount,
        currency,
        accountIdentifier,
        institutionIdentifier,
      }),
    },
  ).then((r) => r.json());

  console.log("Estimated arrival:", quote.data?.estimatedArrivalTime);
  console.log("Network fee:", quote.data?.networkFee);

  // Step 7: Execute (after user confirmation)
  const execution = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/execute`,
    {
      method: "POST",
      headers: {
        ...headers,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        assetId,
        amount,
        currency,
        accountIdentifier,
        institutionIdentifier,
        reference: "WD-20260303-001",
        metadata: { source: "payroll", initiatedBy: "treasury-bot" },
        note: "March payroll payout",
      }),
    },
  ).then((r) => r.json());

  console.log("Withdrawal initiated:", execution.data?.id);
  console.log("Status:", execution.data?.status);

  // Step 8: Listen for webhook to confirm completion
  return execution.data;
}

// Usage
executeFiatWithdrawal({
  walletId: "wallet-uuid",
  currency: "NGN",
  accountIdentifier: "0023103996",
});

Respostas de erro

Dados bancários inválidos

{
  "message": "Institution not supported",
  "statusCode": 400
}

Moeda não suportada

{
  "message": "Currency not supported",
  "statusCode": 400
}

Ativo não suportado

{
  "message": "Asset not supported",
  "statusCode": 404
}

Recurso não habilitado

{
  "message": "Fiat withdrawal feature is not enabled for this business, please contact support via the live chat or email support for more information",
}

Saldo insuficiente

{
  "message": "Insufficient token balance for withdrawal",
  "statusCode": 400,
}

Saldo nativo insuficiente

{
  "message": "Insufficient native balance for gas fees",
  "statusCode": 400
}

Saldo insuficiente na Master Wallet

{
  "message": "Insufficient master balance for gas top-up",
  "statusCode": 400
}

Boas práticas

Experiência do usuário

Verifique as contas primeiro: Sempre confirme o nome da conta antes de exibir uma cotação
Mostre o custo total: Exiba a taxa de câmbio, a taxa de rede e o valor total
Exponha o estado de processamento: Use webhooks para atualizar os usuários em tempo real

Segurança

Valide as entradas: Garanta que a moeda, a instituição e os identificadores de conta estejam bem formados
Use referências: Acompanhe os saques com um reference único
Confirme via webhooks: Trate offramp.success como a fonte final da verdade

Desempenho

Cacheie as listas de instituições: Atualize periodicamente em vez de a cada requisição
Reutilize os metadados de ativos: Cacheie os ativos e moedas suportados
Repita em erros transitórios: Use backoff exponencial para respostas 5xx

Referência da API

Endpoint	Descrição
Get Supported Assets	Listar os ativos stablecoin suportados
Get Institutions	Listar instituições por moeda
Get Exchange Rates	Obter a taxa de câmbio para uma cotação
Get Currencies	Listar moedas fiat suportadas
Verify Institution Account	Verificar dados da conta bancária
Master Wallet Quote	Obter cotação a partir da master wallet
Master Wallet Execute	Executar saque a partir da master wallet
Child Address Quote	Obter cotação a partir de uma child address
Child Address Execute	Executar saque a partir de uma child address

Suporte

E-mail: [email protected]
Documentação: Referência da API

Começar

Carteiras

Receber Pagamentos

Enviar Pagamentos

Converter e Gerenciar

Conformidade e Recuperação

Integrações

Documentation Index

​Pré-requisitos

​Como funciona

Descobrir ativos

Obter moedas fiat

Obter taxas

Verificar conta

Obter cotação

Executar

​Moedas fiat suportadas

​Requisitos de conformidade

​Escolha seu caminho de integração

​Requisito de aprovação

​Master Wallet vs Child Address

Master Wallet

Child Address

​Endpoints

​Fluxo típico

​Etapa 1: Obter uma cotação

​Parâmetros da requisição

​Exemplo de cotação

​Etapa 2: Executar o saque

​Parâmetros da requisição

​Exemplo de execução

​Resposta da execução

​Webhooks

​Exemplo de payload do webhook

​Exemplo de fluxo completo

​Respostas de erro

​Boas práticas

​Experiência do usuário

​Segurança

​Desempenho

​Referência da API

​Suporte

Pré-requisitos

Como funciona

Moedas fiat suportadas

Requisitos de conformidade

Escolha seu caminho de integração

Requisito de aprovação

Master Wallet vs Child Address

Endpoints

Fluxo típico

Etapa 1: Obter uma cotação

Parâmetros da requisição

Exemplo de cotação

Etapa 2: Executar o saque

Parâmetros da requisição

Exemplo de execução

Resposta da execução

Webhooks

Exemplo de payload do webhook

Exemplo de fluxo completo

Respostas de erro

Boas práticas

Experiência do usuário

Segurança

Desempenho

Referência da API

Suporte