跳转到主要内容

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.

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

​
前提条件

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

合规要求

在申请法币提现访问权限之前完成合作伙伴入驻流程（请参阅下方 合规要求）。
2

API 密钥

从 Blockradar 控制台获取您的 API 密钥。导航至 Developers 进行 生成。
3

已创建钱包

通过控制台创建钱包。您需要 walletId 来执行提现 操作。
4

Asset ID

使用 Get Supported Assets 获取受支持的法币资产。
5

银行账户详情

收集有效的账户标识符和机构标识符（银行代码）。

​
工作原理

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

发现资产

获取支持提现的资产。

获取法币

检索所有受支持的货币。

获取汇率

获取所选资产的当前汇率。

验证账户

在发起提现前验证机构账户详情。

获取报价

估算所请求金额的费用和汇率。

执行

提交提现以进行处理。

​
受支持的法币

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

​
合规要求

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

​
选择您的入驻路径

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

​
批准要求

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

​
Master Wallet 与 Child Address

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

Master Wallet

从 master wallet 提现。适合资金管理操作。

Child Address

从特定的 child address 提现。适用于面向用户的流程。

​
Endpoints

操作Master WalletChild Address
Get Supported AssetsGET /v1/wallets/{walletId}/withdraw/fiat/assets—
Get InstitutionsGET /v1/wallets/{walletId}/withdraw/fiat/institutions—
Get Exchange RatesGET /v1/wallets/{walletId}/withdraw/fiat/rates—
Get CurrenciesGET /v1/wallets/{walletId}/withdraw/fiat/currencies—
Verify Institution AccountPOST /v1/wallets/{walletId}/withdraw/fiat/institution-account-verification—
Get QuotePOST /v1/wallets/{walletId}/withdraw/fiat/quotePOST /v1/wallets/{walletId}/addresses/{addressId}/withdraw/fiat/quote
ExecutePOST /v1/wallets/{walletId}/withdraw/fiat/executePOST /v1/wallets/{walletId}/addresses/{addressId}/withdraw/fiat/execute

​
典型流程

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

​
步骤 1：获取报价

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

​
请求参数

参数类型必填描述
assetIdstring是要提现的稳定币资产 ID
amountstring是以资产单位表示的提现金额
currencystring是目标法币（例如 NGN）
accountIdentifierstring是银行账号或标识符
institutionIdentifierstring是银行/机构代码

​
报价示例

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

​
步骤 2：执行提现

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

​
请求参数

参数类型必填描述
assetIdstring是要提现的稳定币资产 ID
amountstring是以资产单位表示的提现金额
currencystring是目标法币（例如 NGN）
accountIdentifierstring是银行账号或标识符
institutionIdentifierstring是银行/机构代码
referencestring否用于幂等性/跟踪的客户端引用
metadataobject否附加到交易的键值元数据
notestring否此次提现的人类可读备注

​
执行示例

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

​
执行响应

{
  "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 示例

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

​
完整流程示例

以下是展示验证 → 报价 → 执行流程的完整实现： 
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",
});

​
错误响应

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

​
最佳实践

​
用户体验

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

​
安全

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

​
性能

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

​
API 参考

Endpoint描述
Get Supported Assets列出受支持的稳定币资产
Get Institutions按货币列出机构
Get Exchange Rates获取报价的汇率
Get Currencies列出受支持的法币
Verify Institution Account验证银行账户详情
Master Wallet Quote从 master wallet 获取报价
Master Wallet Execute从 master wallet 执行提现
Child Address Quote从 child address 获取报价
Child Address Execute从 child address 执行提现

​
支持