Saltar para o conteúdo principal
Em resumo
A API de Saque Fiat da Blockradar permite converter stablecoins suportadas em moeda fiduciária e transferir fundos para contas bancárias. Você pode consultar ativos suportados, validar contas bancárias, obter cotações e executar saques a partir de carteiras principais e endereços filhos.
Interface de Saque Fiat da Blockradar

Pré-requisitos

Antes de usar Saque Fiat, certifique-se de ter:
1

Requisito de compliance

Conclua o onboarding de parceiro antes de solicitar acesso ao Saque Fiat (veja Requisitos de compliance abaixo).
2

Chave API

Obtenha sua chave API no Painel da Blockradar. Vá até Developers para gerar uma.
3

Carteira criada

Crie uma carteira pelo painel. Você precisará do walletId para as operações de saque.
4

ID do ativo

Consulte os ativos fiat suportados em Obter Ativos Suportados.
5

Dados bancários

Tenha em mãos um identificador de conta válido e um identificador da instituição (código bancário).

Como funciona

O Saque 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 bancária antes de iniciar um saque.

Obter cotação

Estime taxas e câmbio para o valor solicitado.

Executar

Envie o saque para processamento.

Requisitos de compliance

Antes de acessar o Saque Fiat, conclua o processo de onboarding de compliance aplicável à cobertura de moeda de pagamento que você precisa.

Escolha sua trilha de onboarding

Se você precisar de acesso a NGN e também a outras moedas africanas suportadas, conclua os dois fluxos de onboarding.

Requisito de aprovação

O acesso ao Saque Fiat é habilitado após análise de compliance e aprovação da trilha de onboarding selecionada.

Carteira principal vs endereço filho

O Saque Fiat está disponível em dois níveis:

Carteira principal

Saque pela carteira principal. Ideal para operações de tesouraria.

Endereço filho

Saque a partir de um endereço filho específico. Útil para fluxos por usuário.

Endpoints

OperaçãoCarteira principalEndereço filho
Obter ativos suportadosGET /v1/wallets/{walletId}/withdraw/fiat/assets
Obter instituiçõesGET /v1/wallets/{walletId}/withdraw/fiat/institutions
Obter taxas de câmbioGET /v1/wallets/{walletId}/withdraw/fiat/rates
Obter moedasGET /v1/wallets/{walletId}/withdraw/fiat/currencies
Verificar conta da instituiçãoPOST /v1/wallets/{walletId}/withdraw/fiat/institution-account-verification
Obter cotaçãoPOST /v1/wallets/{walletId}/withdraw/fiat/quotePOST /v1/wallets/{walletId}/addresses/{addressId}/withdraw/fiat/quote
ExecutarPOST /v1/wallets/{walletId}/withdraw/fiat/executePOST /v1/wallets/{walletId}/addresses/{addressId}/withdraw/fiat/execute

Fluxo típico

  1. Consulte os ativos suportados para escolher a stablecoin que será sacada.
  2. Liste as instituições e selecione um identificador de banco/instituição.
  3. Verifique a conta para confirmar nome e dados da conta.
  4. Obtenha uma cotação para exibir taxas e câmbio antes da execução.
  5. Execute o saque e acompanhe o status no seu sistema.

Etapa 1: Obter uma cotação

Sempre solicite uma cotação antes de executar um saque para exibir a taxa e os custos ao usuário.

Parâmetros da requisição

ParâmetroTipoObrigatórioDescrição
assetIdstringSimID do ativo stablecoin a ser sacado
amountnumberSimValor a sacar nas unidades do ativo
currencystringSimMoeda fiat de destino (ex.: NGN)
accountIdentifierstringSimNúmero da conta bancária ou identificador
institutionIdentifierstringSimCó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 (e qualquer código/OTP exigido).

Parâmetros da requisição

ParâmetroTipoObrigatórioDescrição
assetIdstringSimID do ativo stablecoin a ser sacado
amountnumberSimValor a sacar nas unidades do ativo
currencystringSimMoeda fiat de destino (ex.: NGN)
accountIdentifierstringSimNúmero da conta bancária ou identificador
institutionIdentifierstringSimCódigo do banco/instituição
codestringNãoCódigo de verificação, se exigido pelo provedor

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",
    "code": "445223"
  }'

Resposta de execução

{
  "message": "Withdrawal initiated successfully",
  "status": true,
  "data": {
    "id": "withdrawal-uuid",
    "status": "processing",
    "amount": 1000,
    "currency": "NGN"
  }
}

Webhooks

Acompanhe o status do saque com os seguintes eventos de webhook:
EventoDescrição
offramp.processingO saque está sendo processado
offramp.successO saque foi concluído com sucesso
offramp.failedO saque falhou

Exemplo de payload de 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

Aqui está uma implementação completa mostrando o fluxo verificar → cotar → executar:
async function executeFiatWithdrawal({
  walletId,
  currency,
  accountIdentifier,
  code,
}) {
  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}&providerId=${institutionIdentifier}`,
    { 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,
        code,
      }),
    },
  ).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",
  code: "445223",
});

Respostas de erro

{
  "message": "Institution not supported",
  "statusCode": 400
}
{
  "message": "Currency not supported",
  "statusCode": 400
}
{
  "message": "Asset not supported",
  "statusCode": 404
}
{
  "message": "Fiat withdrawal feature is not enabled for this business, please contact support via the live chat or email support for more information",
}
{
  "message": "Insufficient token balance for withdrawal",
  "statusCode": 400,
}
{
  "message": "Insufficient native balance for gas fees",
  "statusCode": 400
}
{
  "message": "Insufficient master balance for gas top-up",
  "statusCode": 400
}

Boas práticas

Experiência do usuário

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

Segurança

  • Valide entradas: Garanta que moeda, instituição e identificadores de conta estejam bem formatados
  • Use referências: Rastreie saques com uma reference única
  • Confirme via webhooks: Trate offramp.success como fonte final da verdade

Performance

  • Faça cache das listas de instituições: Atualize periodicamente em vez de consultar a cada requisição
  • Reutilize metadados de ativos: Faça cache de ativos e moedas suportadas
  • Tente novamente em erros transitórios: Use backoff exponencial para respostas 5xx

Referência da API

EndpointDescrição
Obter Ativos SuportadosLista stablecoins suportadas
Obter InstituiçõesLista instituições por moeda
Obter Taxas de CâmbioConsulta a taxa de câmbio para uma cotação
Obter MoedasLista moedas fiat suportadas
Verificar Conta da InstituiçãoVerifica dados da conta bancária
Cotação da Carteira PrincipalObtém cotação da carteira principal
Execução da Carteira PrincipalExecuta saque da carteira principal
Cotação do Endereço FilhoObtém cotação de um endereço filho
Execução do Endereço FilhoExecuta saque de um endereço filho

Suporte