Withdraw Fiat - Blockradar

v2 · Recommended
v1 · Legacy

In a nutshell
Blockradar’s Withdraw Fiat API converts supported stablecoins into fiat and pays out to bank accounts, mobile money, and other local rails. The v2 flow discovers the payment methods available for a corridor, returns a schema describing exactly what each method needs, resolves fields such as the beneficiary account name, and then quotes and executes the withdrawal from a master wallet or child address.

v2 payment methods return a JSON Schema describing the beneficiary and payment details your application must collect. See Dynamic Forms to render, validate, resolve, and submit these fields. The v1 flow is available in the v1 · Legacy tab, but is no longer recommended.

Prerequisites

Before using Withdraw Fiat, ensure you have:

Compliance Approved

Complete the Due Diligence process on the Dashboard: My Wallets → Settings → Compliance. Compliance requirements and approval processes vary by geography, so you only need to complete the ones for the local rails your product uses.

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. Use the returned id as the assetId throughout the flow.

How It Works

The v2 flow is corridor-driven: you choose an asset, currency, and amount, then discover the payment methods that support that corridor and collect exactly what each method requires.

Discover Assets

Fetch the stablecoins supported for withdrawals.

Get Currencies & Rates

List supported payout currencies and fetch the current rate.

List Payment Methods

Discover the methods available for the asset, currency, and amount.

Get Requirements

Retrieve the JSON Schema describing the fields the method needs.

Resolve & Quote

Resolve fields like the account name, then quote fees and rate.

Execute

Submit paymentMethodData to process the withdrawal.

Supported Fiat Currencies

Currencies vary by corridor and provider. Always fetch the live list with Get Supported Currencies rather than hard-coding it. The table below shows the stablecoins and blockchains each supported currency covers:

Fiat Currency	USDC Blockchains	USDT Blockchains	EURC Blockchains
COP	Ethereum, Polygon	Ethereum	—
GHS	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
INR	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
KES	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
NGN	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
TZS	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
UGX	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base

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 /v2/wallets/{id}/withdraw/fiat/assets`	—
Get Currencies	`GET /v2/wallets/{id}/withdraw/fiat/currencies`	—
Get Exchange Rates	`GET /v2/wallets/{id}/withdraw/fiat/rates`	—
Get Payment Methods	`GET /v2/wallets/{id}/withdraw/fiat/payment-methods`	—
Get Payment Method Requirements	`GET /v2/wallets/{id}/withdraw/fiat/payment-method-requirements`	—
Resolve Payment Method	`POST /v2/wallets/{id}/withdraw/fiat/payment-method/resolve`	—
Get Quote	`POST /v2/wallets/{id}/withdraw/fiat/quote`	`POST /v2/wallets/{walletId}/addresses/{addressId}/withdraw/fiat/quote`
Execute	`POST /v2/wallets/{id}/withdraw/fiat/execute`	`POST /v2/wallets/{walletId}/addresses/{addressId}/withdraw/fiat/execute`

Discovery endpoints (assets, currencies, rates, payment methods, requirements, resolve) are scoped to the master wallet. Once you have a validated paymentMethodData object, you can quote and execute from either the master wallet or a child address.

Typical Flow

Fetch supported assets to choose the stablecoin to withdraw.
Fetch currencies and rate for the chosen corridor.
List payment methods for the asset, currency, and amount.
Get requirements for the selected method to receive its schema.
Resolve fields such as the account name, then collect and validate paymentMethodData.
Get a quote to show fees and rate before execution.
Execute the withdrawal and track status with webhooks.

Step 1: Get Supported Assets

Fetch the stablecoins available for withdrawal and take the id you want as the assetId.

curl --request GET \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/withdraw/fiat/assets' \
  --header 'x-api-key: <api-key>'

Step 2: Get Currencies and Rate

List the supported payout currencies, then fetch the current rate for the asset, currency, and amount.

Parameter	In	Required	Description
`assetId`	query	Yes	Stablecoin asset ID to withdraw
`currency`	query	Yes	ISO 4217 payout currency (e.g., `NGN`)
`amount`	query	Yes	Decimal amount as a string to preserve precision

curl --request GET \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/withdraw/fiat/rates?assetId=ae455f23-3824-4125-baab-d158315cbcbd&currency=NGN&amount=100.00' \
  --header 'x-api-key: <api-key>'

Rate Response

{
  "statusCode": 200,
  "message": "Exchange rates fetched successfully",
  "data": {
    "rate": "1550.00",
    "amount": "100.00",
    "unlocked": true
  }
}

Step 3: List Payment Methods

Discover the payment methods available for the corridor. Pass the same assetId, currency, and amount; optionally narrow by country or paymentMethodCategory.

Parameter	In	Required	Description
`assetId`	query	Yes	Stablecoin asset ID to withdraw
`currency`	query	Yes	ISO 4217 payout currency
`amount`	query	Yes	Decimal amount as a string
`country`	query	No	ISO 3166-1 alpha-2 country code
`paymentMethodCategory`	query	No	High-level category, e.g., `bank`
`provider`	query	No	Provider slug. Omit to let Blockradar route automatically

curl --request GET \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/withdraw/fiat/payment-methods?assetId=ae455f23-3824-4125-baab-d158315cbcbd&currency=NGN&amount=100.00' \
  --header 'x-api-key: <api-key>'

Payment Methods Response

{
  "statusCode": 200,
  "message": "Payment methods fetched successfully",
  "data": [
    {
      "id": "bank_transfer",
      "supportsPaymentMethodResolution": true,
      "type": "bank_transfer",
      "country": "NG",
      "fiatCurrency": "NGN",
      "paymentMethodCategory": "bank",
      "paymentMethodType": "bank_transfer",
      "processingSeconds": 60,
      "fee": "1500.00",
      "providers": [
        {
          "id": "example-provider",
          "name": "Example Provider",
          "type": "bank_transfer",
          "metadata": null
        }
      ]
    }
  ]
}

supportsPaymentMethodResolution: true means the method’s schema can include an x-resolution field (such as an account-name lookup) that you resolve before quoting. See Step 5.

Step 4: Get Payment Method Requirements

Fetch the JSON Schema that describes the fields the selected paymentMethod needs. Interpret and complete it with Dynamic Forms.

Parameter	In	Required	Description
`assetId`	query	Yes	Stablecoin asset ID to withdraw
`currency`	query	Yes	ISO 4217 payout currency
`amount`	query	Yes	Decimal amount as a string
`paymentMethod`	query	Yes	Payment-method `id` from Step 3
`country`	query	No	ISO 3166-1 alpha-2 country code
`provider`	query	No	Provider slug

curl --request GET \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/withdraw/fiat/payment-method-requirements?assetId=ae455f23-3824-4125-baab-d158315cbcbd&currency=NGN&amount=100.00&paymentMethod=bank_transfer' \
  --header 'x-api-key: <api-key>'

Requirements Response

{
  "statusCode": 200,
  "message": "Payment method requirements fetched successfully",
  "data": {
    "paymentMethodId": "bank_transfer",
    "schema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "title": "Bank account details",
      "properties": {
        "institutionIdentifier": { "type": "string", "title": "Institution" },
        "accountIdentifier": { "type": "string", "title": "Account identifier" },
        "accountName": {
          "type": "string",
          "title": "Account name",
          "readOnly": true,
          "x-field-kind": "resolved",
          "x-resolution": {
            "method": "POST",
            "url": "/v2/wallets/{walletId}/withdraw/fiat/payment-method/resolve",
            "body": {
              "provider": "example-provider",
              "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
              "currency": "NGN",
              "amount": "100.00",
              "paymentMethod": "bank_transfer"
            },
            "inputPath": "paymentMethodData",
            "dependsOn": ["institutionIdentifier", "accountIdentifier"],
            "responsePath": "data.accountName"
          }
        }
      },
      "required": ["institutionIdentifier", "accountIdentifier"],
      "additionalProperties": false
    },
    "metadata": null
  }
}

Step 5: Resolve Fields and Build `paymentMethodData`

Collect the fields in data.schema. When a field carries x-resolution (like accountName above), call the resolve endpoint once its dependsOn fields are valid, then store the result at that field.

Parameter	Type	Required	Description
`assetId`	string	Yes	Stablecoin asset ID
`currency`	string	Yes	ISO 4217 payout currency
`amount`	string	Yes	Withdrawal amount as a decimal string
`paymentMethod`	string	Yes	Payment-method `id`
`paymentMethodData`	object	Yes	Current form values required by the resolution
`provider`	string	No	Provider slug selected earlier in the flow

curl --request POST \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/withdraw/fiat/payment-method/resolve' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
    "currency": "NGN",
    "amount": "100.00",
    "paymentMethod": "bank_transfer",
    "provider": "example-provider",
    "paymentMethodData": {
      "institutionIdentifier": "999",
      "accountIdentifier": "0123456789"
    }
  }'

Resolve Response

{
  "statusCode": 200,
  "message": "Payment method resolved successfully",
  "data": {
    "paymentMethod": "bank_transfer",
    "data": {
      "accountNumber": "0123456789",
      "accountName": "Ada Okafor",
      "bankCode": "999"
    },
    "metadata": { "institutionId": "bank_999" }
  }
}

After resolving and validating, your completed paymentMethodData looks like:

{
  "institutionIdentifier": "999",
  "accountIdentifier": "0123456789",
  "accountName": "Ada Okafor"
}

Step 6: Get a Quote

Always fetch a quote before executing so you can display the rate, fees, and estimated arrival time to the user. Send the validated paymentMethodData.

Parameter	Type	Required	Description
`assetId`	string	Yes	Stablecoin asset ID to withdraw
`amount`	string	Yes	Amount to withdraw as a decimal string
`currency`	string	Yes	ISO 4217 payout currency
`paymentMethod`	string	Yes	Payment-method `id` from discovery
`paymentMethodData`	object	Yes	Values validated against the requirements schema
`isGaslessWithdraw`	boolean	No	Whether Blockradar should sponsor on-chain gas where supported
`provider`	string	No	Provider slug. Omit for automatic routing

curl --request POST \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/withdraw/fiat/quote' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
    "amount": "100.00",
    "currency": "NGN",
    "paymentMethod": "bank_transfer",
    "paymentMethodData": {
      "institutionIdentifier": "999",
      "accountIdentifier": "0123456789",
      "accountName": "Ada Okafor"
    }
  }'

Quote Response

{
  "statusCode": 200,
  "message": "Successful",
  "data": {
    "debitAmount": "101.50",
    "minAmount": "10.00",
    "networkFee": "0.00006779052",
    "networkFeeInUSD": "0.14",
    "estimatedArrivalTime": 60,
    "transactionFee": "1.50",
    "nativeBalance": "0.000929309612767174",
    "nativeBalanceInUSD": "1.97"
  }
}

Step 7: Execute Withdrawal

Once the user accepts the quote, execute with the same details. Add an optional reference for idempotency and tracking, plus metadata and note as needed.

Parameter	Type	Required	Description
`assetId`	string	Yes	Stablecoin asset ID to withdraw
`amount`	string	Yes	Amount to withdraw as a decimal string
`currency`	string	Yes	ISO 4217 payout currency
`paymentMethod`	string	Yes	Payment-method `id` from discovery
`paymentMethodData`	object	Yes	Values validated against the requirements schema
`isGaslessWithdraw`	boolean	No	Whether Blockradar should sponsor on-chain gas where supported
`reference`	string	No	Unique client reference for reconciliation and safe retries
`metadata`	object	No	Your application metadata attached to the transaction
`note`	string	No	Human-readable note for this withdrawal
`provider`	string	No	Provider slug. Omit for automatic routing

curl --request POST \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/withdraw/fiat/execute' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
    "amount": "100.00",
    "currency": "NGN",
    "paymentMethod": "bank_transfer",
    "paymentMethodData": {
      "institutionIdentifier": "999",
      "accountIdentifier": "0123456789",
      "accountName": "Ada Okafor"
    },
    "reference": "wd_20260719_001",
    "metadata": { "payoutId": "payout_123" },
    "note": "Vendor payout"
  }'

Execute Response

{
  "statusCode": 200,
  "message": "Successful",
  "data": {
    "id": "5b26b640-7a15-48aa-a465-82a4cb6e927b",
    "reference": "wd_20260719_001",
    "senderAddress": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a",
    "recipientAddress": "0123456789",
    "tokenAddress": "0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "amount": "100.00",
    "amountPaid": "100.00",
    "amountUSD": "100.00",
    "rateUSD": "1.00",
    "fee": "1.50",
    "feeUSD": "1.50",
    "currency": "NGN",
    "toCurrency": "NGN",
    "hash": null,
    "confirmed": false,
    "status": "pending",
    "processingStatus": "pending",
    "processingProviderReference": null,
    "type": "offramp",
    "note": "Vendor payout",
    "createdAt": "2026-07-19T12:30:00.000Z",
    "updatedAt": "2026-07-19T12:30:00.000Z"
  }
}

Withdraw from a Child Address

To pay out from a specific child address, quote and execute against the address-scoped endpoints using the same request bodies:

POST /v2/wallets/{walletId}/addresses/{addressId}/withdraw/fiat/quote
POST /v2/wallets/{walletId}/addresses/{addressId}/withdraw/fiat/execute

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": "wd_20260719_001",
    "senderAddress": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a",
    "tokenAddress": "0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "amount": "100.00",
    "amountPaid": "100.00",
    "amountUSD": "100.00",
    "rateUSD": "1.00",
    "fee": "1.50",
    "feeUSD": "1.50",
    "currency": "NGN",
    "toCurrency": "NGN",
    "status": "PROCESSING",
    "processingStatus": "SUCCESS",
    "type": "offramp",
    "network": "mainnet",
    "beneficiary": {
      "name": "Ada Okafor",
      "type": "FIAT",
      "institutionIdentifier": "999",
      "institutionAccountIdentifier": "0123456789",
      "currency": "NGN"
    }
  }
}

For webhook setup, payload structure, and event handling, see the Webhooks documentation.

Complete Flow Example

A full v2 implementation showing the discover → requirements → resolve → quote → execute flow:

async function executeFiatWithdrawal({ walletId, currency, amount, formValues }) {
  const apiKey = process.env.BLOCKRADAR_API_KEY;
  const baseUrl = "https://api.blockradar.co/v2";
  const headers = { "x-api-key": apiKey };
  const jsonHeaders = { ...headers, "Content-Type": "application/json" };

  // 1. Pick an asset to withdraw
  const assets = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/assets`,
    { headers },
  ).then((r) => r.json());
  const assetId = assets.data?.[0]?.id;

  // 2. Fetch the rate for the corridor
  const rates = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/rates?assetId=${assetId}&currency=${currency}&amount=${amount}`,
    { headers },
  ).then((r) => r.json());
  console.log("Rate:", rates.data?.rate);

  // 3. List payment methods for the corridor
  const methods = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/payment-methods?assetId=${assetId}&currency=${currency}&amount=${amount}`,
    { headers },
  ).then((r) => r.json());
  const paymentMethod = methods.data?.[0]?.id;

  // 4. Get the requirements schema for the method
  const requirements = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/payment-method-requirements?assetId=${assetId}&currency=${currency}&amount=${amount}&paymentMethod=${paymentMethod}`,
    { headers },
  ).then((r) => r.json());
  const schema = requirements.data?.schema;

  // 5. Collect fields from `schema`, then resolve fields carrying x-resolution.
  //    See the Dynamic Forms guide for how to interpret and validate the schema.
  const resolved = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/payment-method/resolve`,
    {
      method: "POST",
      headers: jsonHeaders,
      body: JSON.stringify({
        assetId,
        currency,
        amount,
        paymentMethod,
        paymentMethodData: formValues, // e.g. { institutionIdentifier, accountIdentifier }
      }),
    },
  ).then((r) => r.json());

  const paymentMethodData = {
    ...formValues,
    accountName: resolved.data?.data?.accountName,
  };

  // 6. Get a quote
  const quote = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/quote`,
    {
      method: "POST",
      headers: jsonHeaders,
      body: JSON.stringify({ assetId, amount, currency, paymentMethod, paymentMethodData }),
    },
  ).then((r) => r.json());
  console.log("Debit amount:", quote.data?.debitAmount);
  console.log("Estimated arrival (s):", quote.data?.estimatedArrivalTime);

  // 7. Execute (after user confirmation)
  const execution = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/fiat/execute`,
    {
      method: "POST",
      headers: jsonHeaders,
      body: JSON.stringify({
        assetId,
        amount,
        currency,
        paymentMethod,
        paymentMethodData,
        reference: "wd_20260719_001",
        metadata: { payoutId: "payout_123" },
        note: "Vendor payout",
      }),
    },
  ).then((r) => r.json());
  console.log("Withdrawal initiated:", execution.data?.id, execution.data?.status);

  // 8. Listen for the offramp.success webhook to confirm completion
  return execution.data;
}

// Usage
executeFiatWithdrawal({
  walletId: "wallet-uuid",
  currency: "NGN",
  amount: "100.00",
  formValues: { institutionIdentifier: "999", accountIdentifier: "0123456789" },
});

Error Responses

Invalid payment method data

{
  "statusCode": 400,
  "message": "Invalid payment method data for accountIdentifier: accountIdentifier does not match the expected format"
}

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
}

Best Practices

User Experience

Resolve before quoting: Confirm the beneficiary account name via the resolve endpoint before showing a quote.
Show full cost: Display the rate, transaction fee, network fee, and debitAmount.
Surface processing state: Use webhooks to update users in real time.

Correctness

Use the returned schema: Collect only the fields in the current requirements schema. Do not hard-code beneficiary fields — see Dynamic Forms.
Preserve strings: Send amount and account identifiers as strings to avoid precision loss.
Use references: Track withdrawals with a unique reference for safe retries.
Confirm via webhooks: Treat offramp.success as the final source of truth.

Performance

Cache asset and currency lists: Refresh periodically instead of on every request.
Re-fetch rates and methods per corridor: Rates and payment methods depend on the asset, currency, and amount.
Retry on transient errors: Use exponential backoff for 5xx responses.

API Reference

v2 (Recommended)

Endpoint	Description
Get Supported Assets	List supported stablecoin assets
Get Supported Currencies	List supported payout currencies
Get Exchange Rates	Fetch the rate for a corridor
Get Payment Methods	List methods available for the corridor
Get Payment Method Requirements	Fetch the fields schema for a method
Resolve Payment Method	Resolve fields such as the account name
Master Wallet Quote	Get a quote from the master wallet
Master Wallet Execute	Execute a withdrawal from the master wallet
Child Address Quote	Get a quote from a child address
Child Address Execute	Execute a withdrawal from a child address

Support

Email: [email protected]
Live chat: Available on the dashboard

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.

Some fiat payment methods return a schema describing the beneficiary or payment details your application must collect. See Dynamic Forms to render, validate, and submit these fields.

Prerequisites

Before using Withdraw Fiat, ensure you have:

Compliance Requirement

Complete the Due Diligence process on the Dashboard: My wallets > Settings > Compliance

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.

Supported Fiat Currencies

Currency	Code
Kenyan Shilling	KES
Nigerian Naira	NGN
Tanzanian Shilling	TZS
Ugandan Shilling	UGX
Brazilian Real	BRL
Malawian Kwacha	MWK

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

Request Parameters

Parameter	Type	Required	Description
`assetId`	string	Yes	The stablecoin asset ID to withdraw
`amount`	string	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
`reference`	string	No	Client reference for idempotency/tracking
`metadata`	object	No	Key-value metadata attached to the transaction
`note`	string	No	Human-readable note for this withdrawal

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",
    "reference": "WD-20260303-001",
    "metadata": {
      "source": "payroll",
      "initiatedBy": "treasury-bot"
    },
    "note": "March payroll payout"
  }'

Execute Response

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

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

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

​Prerequisites

​How It Works

Discover Assets

Get Currencies & Rates

List Payment Methods

Get Requirements

Resolve & Quote

Execute

​Supported Fiat Currencies

​Master Wallet vs Child Address

Master Wallet

Child Address

​Endpoints

​Typical Flow

​Step 1: Get Supported Assets

​Step 2: Get Currencies and Rate

​Step 3: List Payment Methods

​Step 4: Get Payment Method Requirements

​Step 5: Resolve Fields and Build paymentMethodData

​Step 6: Get a Quote

​Step 7: Execute Withdrawal

​Execute Response

​Withdraw from a Child Address

​Webhooks

​Webhook Payload Example

​Complete Flow Example

​Error Responses

​Best Practices

​User Experience

​Correctness

​Performance

​API Reference

​v2 (Recommended)

​Support

​Prerequisites

​How It Works

Discover Assets

Get Fiat Currencies

Get Rates

Verify Account

Get Quote

Execute

​Supported Fiat Currencies

​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

Supported Fiat Currencies

Master Wallet vs Child Address

Endpoints

Typical Flow

Step 1: Get Supported Assets

Step 2: Get Currencies and Rate

Step 3: List Payment Methods

Step 4: Get Payment Method Requirements

Step 5: Resolve Fields and Build `paymentMethodData`

Step 6: Get a Quote

Step 7: Execute Withdrawal

Execute Response

Withdraw from a Child Address

Webhooks

Webhook Payload Example

Complete Flow Example

Error Responses

Best Practices

User Experience

Correctness

Performance

API Reference

v2 (Recommended)

Support

Prerequisites

How It Works

Supported Fiat Currencies

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