Withdraw Fiat

In a nutshell
Blockradar’s Withdraw Fiat API lets you convert supported stablecoins into fiat and transfer funds to bank accounts. You can fetch supported assets, validate bank accounts, get quotes, and execute withdrawals from both master wallets and child addresses.

Prerequisites

Before using Withdraw Fiat, ensure you have:

Compliance Requirement

Complete partner onboarding before requesting Withdraw Fiat access (see Compliance Requirements below).

API Key

Get your API key from the Blockradar Dashboard. Navigate to Developers to generate one.

Wallet Created

Create a wallet via the dashboard. You’ll need the walletId for withdrawal operations.

Asset ID

Fetch supported fiat assets using Get Supported Assets.

Bank Account Details

Collect a valid account identifier and institution identifier (bank code).

How It Works

Withdraw Fiat follows a simple sequence:

Discover Assets

Fetch the assets supported for withdrawals.

Get Fiat Currencies

Retrieve all supported currencies.

Get Rates

Fetch the current exchange rate for your selected asset.

Verify Account

Validate institution account details before initiating a withdrawal.

Get Quote

Estimate fees and exchange rate for the requested amount.

Execute

Submit the withdrawal for processing.

Compliance Requirements

Before accessing Withdraw Fiat, complete the applicable compliance onboarding process for your payout currency coverage.

Choose Your Onboarding Path

NGN (Naira) only: Complete the Naira-only onboarding form.
Other African currencies: Complete the African currencies partner onboarding.

If you need access to both NGN and other supported African currencies, complete both onboarding flows.

Approval Requirement

Withdraw Fiat access is enabled after compliance review and approval for your selected onboarding path.

Master Wallet vs Child Address

Withdraw Fiat is available at two levels:

Master Wallet

Withdraw from the master wallet. Ideal for treasury operations.

Child Address

Withdraw from a specific child address. Useful for user-specific flows.

Endpoints

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

Typical Flow

Fetch supported assets to choose the stablecoin to withdraw.
List institutions and select a bank/institution identifier.
Verify account to confirm account name/details.
Get quote to show fees and rate before execution.
Execute withdrawal and track status in your system.

Step 1: Get a Quote

Always fetch a quote before executing a withdrawal so you can display the rate and fees to the user.

Request Parameters

Parameter	Type	Required	Description
`assetId`	string	Yes	The stablecoin asset ID to withdraw
`amount`	number	Yes	Amount to withdraw in the asset’s units
`currency`	string	Yes	Destination fiat currency (e.g., `NGN`)
`accountIdentifier`	string	Yes	Bank account number or identifier
`institutionIdentifier`	string	Yes	Bank/institution code

Quote Example

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

Step 2: Execute Withdrawal

Once you accept the quote, execute the withdrawal with the same details (and any required code/OTP).

Request Parameters

Parameter	Type	Required	Description
`assetId`	string	Yes	The stablecoin asset ID to withdraw
`amount`	number	Yes	Amount to withdraw in the asset’s units
`currency`	string	Yes	Destination fiat currency (e.g., `NGN`)
`accountIdentifier`	string	Yes	Bank account number or identifier
`institutionIdentifier`	string	Yes	Bank/institution code
`code`	string	No	Verification code if required by the provider

Execute Example

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

Execute Response

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

Webhooks

Track withdrawal status with the following webhook events:

Event	Description
`offramp.processing`	Withdrawal is being processed
`offramp.success`	Withdrawal completed successfully
`offramp.failed`	Withdrawal failed

Webhook Payload Example

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

Complete Flow Example

Here’s a full implementation showing the verify → quote → execute flow:

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

Error Responses

Invalid Bank Details

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

Unsupported Currency

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

Asset not supported

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

Feature not enabled

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

Insufficient Balance

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

Insufficient Native Balance

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

Insufficient Master Wallet Balance

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

Best Practices

User Experience

Verify accounts first: Always confirm account name before showing a quote
Show full cost: Display exchange rate, network fee, and total amount
Surface processing state: Use webhooks to update users in real time

Security

Validate inputs: Ensure currency, institution, and account identifiers are well-formed
Use references: Track withdrawals with a unique reference
Confirm via webhooks: Treat offramp.success as the final source of truth

Performance

Cache institution lists: Refresh periodically instead of on every request
Reuse asset metadata: Cache supported assets and currencies
Retry on transient errors: Use exponential backoff for 5xx responses

API Reference

Endpoint	Description
Get Supported Assets	List supported stablecoin assets
Get Institutions	List institutions by currency
Get Exchange Rates	Fetch exchange rate for a quote
Get Currencies	List supported fiat currencies
Verify Institution Account	Verify bank account details
Master Wallet Quote	Get quote from master wallet
Master Wallet Execute	Execute withdrawal from master wallet
Child Address Quote	Get quote from child address
Child Address Execute	Execute withdrawal from child address

Support

Email: [email protected]
Documentation: API Reference

Get Started

Essentials

Prerequisites

How It Works

Discover Assets

Get Fiat Currencies

Get Rates

Verify Account

Get Quote

Execute

Compliance Requirements

Choose Your Onboarding Path

Approval Requirement

Master Wallet vs Child Address

Master Wallet

Child Address

Endpoints

Typical Flow

Step 1: Get a Quote

Request Parameters

Quote Example

Step 2: Execute Withdrawal

Request Parameters

Execute Example

Execute Response

Webhooks

Webhook Payload Example

Complete Flow Example

Error Responses

Best Practices

User Experience

Security

Performance

API Reference

Support

Get Started

Essentials

​Prerequisites

​How It Works

Discover Assets

Get Fiat Currencies

Get Rates

Verify Account

Get Quote

Execute

​Compliance Requirements

​Choose Your Onboarding Path

​Approval Requirement

​Master Wallet vs Child Address

Master Wallet

Child Address

​Endpoints

​Typical Flow

​Step 1: Get a Quote

​Request Parameters

​Quote Example

​Step 2: Execute Withdrawal

​Request Parameters

​Execute Example

​Execute Response

​Webhooks

​Webhook Payload Example

​Complete Flow Example

​Error Responses

​Best Practices

​User Experience

​Security

​Performance

​API Reference

​Support

Prerequisites

How It Works

Compliance Requirements

Choose Your Onboarding Path

Approval Requirement

Master Wallet vs Child Address

Endpoints

Typical Flow

Step 1: Get a Quote

Request Parameters

Quote Example

Step 2: Execute Withdrawal

Request Parameters

Execute Example

Execute Response

Webhooks

Webhook Payload Example

Complete Flow Example

Error Responses

Best Practices

User Experience

Security

Performance

API Reference

Support