> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockradar.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Saque em Fiat

> Converta stablecoins em fiat e envie para contas bancárias

<Note>
  Em resumo<br />
  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.
</Note>

<img src="https://mintcdn.com/blockradar/9k7zAm2kB6tSbuCY/images/withdraw-fiat.png?fit=max&auto=format&n=9k7zAm2kB6tSbuCY&q=85&s=17b9748b21b1ff2f7eff9779d791d44d" alt="Interface de Saque em Fiat da Blockradar" width="2032" height="1707" data-path="images/withdraw-fiat.png" />

## Pré-requisitos

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

<Steps>
  <Step title="Requisito de conformidade">
    Conclua a integração de parceiro antes de solicitar acesso ao Saque em Fiat (consulte
    [Requisitos de conformidade](#requisitos-de-conformidade) abaixo).
  </Step>

  <Step title="Chave de API">
    Obtenha sua chave de API no [Dashboard da
    Blockradar](https://dashboard.blockradar.co). Acesse **Developers** para
    gerá-la.
  </Step>

  <Step title="Wallet criada">
    Crie uma wallet pelo dashboard. Você precisará do `walletId` para as
    operações de saque.
  </Step>

  <Step title="Asset ID">
    Consulte os ativos fiat suportados usando [Get Supported
    Assets](/en/api-reference/withdraw-fiat/get-supported-assets).
  </Step>

  <Step title="Dados da conta bancária">
    Reúna um identificador de conta válido e o identificador da instituição (código bancário).
  </Step>
</Steps>

## Como funciona

O Saque em Fiat segue uma sequência simples:

<CardGroup cols={2}>
  <Card title="Descobrir ativos" icon="coins">
    Consulte os ativos suportados para saques.
  </Card>

  <Card title="Obter moedas fiat" icon="money-bill-wave">
    Recupere todas as moedas suportadas.
  </Card>

  <Card title="Obter taxas" icon="chart-line">
    Consulte a taxa de câmbio atual para o ativo selecionado.
  </Card>

  <Card title="Verificar conta" icon="badge-check">
    Valide os dados da conta da instituição antes de iniciar um saque.
  </Card>

  <Card title="Obter cotação" icon="calculator">
    Estime as taxas e a taxa de câmbio para o valor solicitado.
  </Card>

  <Card title="Executar" icon="paper-plane">
    Envie o saque para processamento.
  </Card>
</CardGroup>

## 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](https://airtable.com/appsn5KFgmZhzQ9lh/pag8ytSkiF9k5w590/form).
* **Outras moedas africanas**: Conclua a [integração de parceiro para moedas africanas](https://app.paycrest.io/partner-onboarding?referralId=blockradar).

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

### **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:

<CardGroup cols={2}>
  <Card title="Master Wallet" icon="wallet">
    Realize saques a partir da master wallet. Ideal para operações de tesouraria.
  </Card>

  <Card title="Child Address" icon="address-card">
    Realize saques a partir de uma child address específica. Útil para fluxos por usuário.
  </Card>
</CardGroup>

### 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

1. **Consulte os ativos suportados** para escolher a stablecoin a sacar.
2. **Liste as instituições** e selecione um identificador de banco/instituição.
3. **Verifique a conta** para confirmar o nome e os dados da conta.
4. **Obtenha uma cotação** para mostrar as taxas e a taxa de câmbio antes da execução.
5. **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

<CodeGroup>
  ```bash Curl theme={null}
  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"
    }'
  ```
</CodeGroup>

## 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

<CodeGroup>
  ```bash Curl theme={null}
  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"
    }'
  ```
</CodeGroup>

### Resposta da execução

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

```javascript theme={null}
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

<AccordionGroup>
  <Accordion title="Dados bancários inválidos">
    ```json theme={null}
    {
      "message": "Institution not supported",
      "statusCode": 400
    }
    ```
  </Accordion>

  <Accordion title="Moeda não suportada">
    ```json theme={null}
    {
      "message": "Currency not supported",
      "statusCode": 400
    }
    ```
  </Accordion>

  <Accordion title="Ativo não suportado">
    ```json theme={null}
    {
      "message": "Asset not supported",
      "statusCode": 404
    }
    ```
  </Accordion>

  <Accordion title="Recurso não habilitado">
    ```json theme={null}
    {
      "message": "Fiat withdrawal feature is not enabled for this business, please contact support via the live chat or email support for more information",
    }
    ```
  </Accordion>

  <Accordion title="Saldo insuficiente">
    ```json theme={null}
    {
      "message": "Insufficient token balance for withdrawal",
      "statusCode": 400,
    }
    ```
  </Accordion>

  <Accordion title="Saldo nativo insuficiente">
    ```json theme={null}
    {
      "message": "Insufficient native balance for gas fees",
      "statusCode": 400
    }
    ```
  </Accordion>

  <Accordion title="Saldo insuficiente na Master Wallet">
    ```json theme={null}
    {
      "message": "Insufficient master balance for gas top-up",
      "statusCode": 400
    }
    ```
  </Accordion>
</AccordionGroup>

## 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](/en/api-reference/withdraw-fiat/get-supported-assets)             | Listar os ativos stablecoin suportados       |
| [Get Institutions](/en/api-reference/withdraw-fiat/get-institutions)                     | Listar instituições por moeda                |
| [Get Exchange Rates](/en/api-reference/withdraw-fiat/get-exchange-rates)                 | Obter a taxa de câmbio para uma cotação      |
| [Get Currencies](/en/api-reference/withdraw-fiat/get-currencies)                         | Listar moedas fiat suportadas                |
| [Verify Institution Account](/en/api-reference/withdraw-fiat/verify-institution-account) | Verificar dados da conta bancária            |
| [Master Wallet Quote](/en/api-reference/withdraw-fiat/master-wallet-get-quote)           | Obter cotação a partir da master wallet      |
| [Master Wallet Execute](/en/api-reference/withdraw-fiat/master-wallet-execute)           | Executar saque a partir da master wallet     |
| [Child Address Quote](/en/api-reference/withdraw-fiat/child-address-get-quote)           | Obter cotação a partir de uma child address  |
| [Child Address Execute](/en/api-reference/withdraw-fiat/child-address-execute)           | Executar saque a partir de uma child address |

## Suporte

* **E-mail**: [support@blockradar.co](mailto:support@blockradar.co)
* **Documentação**: [Referência da API](/en/api-reference/withdraw-fiat/get-supported-assets)