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

# 法币提现

> 将稳定币转换为法币并发送至银行账户

<Note>
  简而言之<br />
  Blockradar 的法币提现 API 让您可以将受支持的稳定币转换为法币并将资金转账到银行账户。您可以查询受支持的资产、验证银行账户、获取报价并从 master wallet 和 child address 执行提现。
</Note>

<img src="https://mintcdn.com/blockradar/9k7zAm2kB6tSbuCY/images/withdraw-fiat.png?fit=max&auto=format&n=9k7zAm2kB6tSbuCY&q=85&s=17b9748b21b1ff2f7eff9779d791d44d" alt="Blockradar 法币提现界面" width="2032" height="1707" data-path="images/withdraw-fiat.png" />

## 前提条件

在使用法币提现之前，请确保您具备以下条件：

<Steps>
  <Step title="合规要求">
    在申请法币提现访问权限之前完成合作伙伴入驻流程（请参阅下方
    [合规要求](#compliance-requirements)）。
  </Step>

  <Step title="API 密钥">
    从 [Blockradar
    控制台](https://dashboard.blockradar.co)获取您的 API 密钥。导航至 **Developers** 进行
    生成。
  </Step>

  <Step title="已创建钱包">
    通过控制台创建钱包。您需要 `walletId` 来执行提现
    操作。
  </Step>

  <Step title="Asset ID">
    使用 [Get Supported
    Assets](/en/api-reference/withdraw-fiat/get-supported-assets) 获取受支持的法币资产。
  </Step>

  <Step title="银行账户详情">
    收集有效的账户标识符和机构标识符（银行代码）。
  </Step>
</Steps>

## 工作原理

法币提现遵循一个简单的流程：

<CardGroup cols={2}>
  <Card title="发现资产" icon="coins">
    获取支持提现的资产。
  </Card>

  <Card title="获取法币" icon="money-bill-wave">
    检索所有受支持的货币。
  </Card>

  <Card title="获取汇率" icon="chart-line">
    获取所选资产的当前汇率。
  </Card>

  <Card title="验证账户" icon="badge-check">
    在发起提现前验证机构账户详情。
  </Card>

  <Card title="获取报价" icon="calculator">
    估算所请求金额的费用和汇率。
  </Card>

  <Card title="执行" icon="paper-plane">
    提交提现以进行处理。
  </Card>
</CardGroup>

## 受支持的法币

| 货币     | 代码  |
| ------ | --- |
| 肯尼亚先令  | KES |
| 尼日利亚奈拉 | NGN |
| 坦桑尼亚先令 | TZS |
| 乌干达先令  | UGX |
| 巴西雷亚尔  | BRL |
| 马拉维克瓦查 | MWK |

## 合规要求

在访问法币提现之前，请根据您的支付货币覆盖范围完成相应的
合规入驻流程。

### **选择您的入驻路径**

* **仅 NGN（奈拉）**：填写 [仅奈拉入驻表单](https://airtable.com/appsn5KFgmZhzQ9lh/pag8ytSkiF9k5w590/form)。
* **其他非洲货币**：完成 [非洲货币合作伙伴入驻](https://app.paycrest.io/partner-onboarding?referralId=blockradar)。

<Note>
  如果您需要同时访问 NGN 和其他受支持的非洲货币，请完成两个入驻流程。
</Note>

### **批准要求**

法币提现访问权限将在所选入驻路径的合规审核和批准后启用。

## Master Wallet 与 Child Address

法币提现在两个层级提供：

<CardGroup cols={2}>
  <Card title="Master Wallet" icon="wallet">
    从 master wallet 提现。适合资金管理操作。
  </Card>

  <Card title="Child Address" icon="address-card">
    从特定的 child address 提现。适用于面向用户的流程。
  </Card>
</CardGroup>

### Endpoints

| 操作                         | 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` |

## 典型流程

1. **获取受支持的资产**以选择要提现的稳定币。
2. **列出机构**并选择银行/机构标识符。
3. **验证账户**以确认账户名称/详情。
4. **获取报价**以在执行前显示费用和汇率。
5. **执行提现**并在系统中跟踪状态。

## 步骤 1：获取报价

在执行提现之前，请始终先获取报价，以便向用户展示汇率和费用。

### 请求参数

| 参数                      | 类型     | 必填 | 描述             |
| ----------------------- | ------ | -- | -------------- |
| `assetId`               | string | 是  | 要提现的稳定币资产 ID   |
| `amount`                | string | 是  | 以资产单位表示的提现金额   |
| `currency`              | string | 是  | 目标法币（例如 `NGN`） |
| `accountIdentifier`     | string | 是  | 银行账号或标识符       |
| `institutionIdentifier` | string | 是  | 银行/机构代码        |

### 报价示例

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

## 步骤 2：执行提现

接受报价后，使用相同的详细信息执行提现。

### 请求参数

| 参数                      | 类型     | 必填 | 描述             |
| ----------------------- | ------ | -- | -------------- |
| `assetId`               | string | 是  | 要提现的稳定币资产 ID   |
| `amount`                | string | 是  | 以资产单位表示的提现金额   |
| `currency`              | string | 是  | 目标法币（例如 `NGN`） |
| `accountIdentifier`     | string | 是  | 银行账号或标识符       |
| `institutionIdentifier` | string | 是  | 银行/机构代码        |
| `reference`             | string | 否  | 用于幂等性/跟踪的客户端引用 |
| `metadata`              | object | 否  | 附加到交易的键值元数据    |
| `note`                  | string | 否  | 此次提现的人类可读备注    |

### 执行示例

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

### 执行响应

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

通过以下 webhook 事件跟踪提现状态：

| 事件                   | 描述      |
| -------------------- | ------- |
| `offramp.processing` | 提现正在处理中 |
| `offramp.success`    | 提现成功完成  |
| `offramp.failed`     | 提现失败    |

### Webhook payload 示例

```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"
    }
  }
}
```

## 完整流程示例

以下是展示验证 → 报价 → 执行流程的完整实现：

```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",
});
```

## 错误响应

<AccordionGroup>
  <Accordion title="无效的银行详情">
    ```json theme={null}
    {
      "message": "Institution not supported",
      "statusCode": 400
    }
    ```
  </Accordion>

  <Accordion title="不支持的货币">
    ```json theme={null}
    {
      "message": "Currency not supported",
      "statusCode": 400
    }
    ```
  </Accordion>

  <Accordion title="不支持的资产">
    ```json theme={null}
    {
      "message": "Asset not supported",
      "statusCode": 404
    }
    ```
  </Accordion>

  <Accordion title="功能未启用">
    ```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="余额不足">
    ```json theme={null}
    {
      "message": "Insufficient token balance for withdrawal",
      "statusCode": 400,
    }
    ```
  </Accordion>

  <Accordion title="原生代币余额不足">
    ```json theme={null}
    {
      "message": "Insufficient native balance for gas fees",
      "statusCode": 400
    }
    ```
  </Accordion>

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

## 最佳实践

### 用户体验

* **首先验证账户**：在显示报价前始终确认账户名称
* **显示完整成本**：展示汇率、网络费用和总金额
* **呈现处理状态**：使用 webhooks 实时更新用户状态

### 安全

* **验证输入**：确保货币、机构和账户标识符格式正确
* **使用引用**：使用唯一的 `reference` 跟踪提现
* **通过 webhooks 确认**：将 `offramp.success` 视为最终事实来源

### 性能

* **缓存机构列表**：定期刷新而不是每次请求都获取
* **复用资产元数据**：缓存受支持的资产和货币
* **对瞬时错误进行重试**：对 5xx 响应使用指数退避

## API 参考

| Endpoint                                                                                 | 描述                   |
| ---------------------------------------------------------------------------------------- | -------------------- |
| [Get Supported Assets](/en/api-reference/withdraw-fiat/get-supported-assets)             | 列出受支持的稳定币资产          |
| [Get Institutions](/en/api-reference/withdraw-fiat/get-institutions)                     | 按货币列出机构              |
| [Get Exchange Rates](/en/api-reference/withdraw-fiat/get-exchange-rates)                 | 获取报价的汇率              |
| [Get Currencies](/en/api-reference/withdraw-fiat/get-currencies)                         | 列出受支持的法币             |
| [Verify Institution Account](/en/api-reference/withdraw-fiat/verify-institution-account) | 验证银行账户详情             |
| [Master Wallet Quote](/en/api-reference/withdraw-fiat/master-wallet-get-quote)           | 从 master wallet 获取报价 |
| [Master Wallet Execute](/en/api-reference/withdraw-fiat/master-wallet-execute)           | 从 master wallet 执行提现 |
| [Child Address Quote](/en/api-reference/withdraw-fiat/child-address-get-quote)           | 从 child address 获取报价 |
| [Child Address Execute](/en/api-reference/withdraw-fiat/child-address-execute)           | 从 child address 执行提现 |

## 支持

* **邮箱**：[support@blockradar.co](mailto:support@blockradar.co)
* **文档**：[API 参考](/en/api-reference/withdraw-fiat/get-supported-assets)