Retiro a Fiat - Blockradar

v2 · Recomendado
v1 · Legacy

En resumen
La API de Retiro a Fiat de Blockradar convierte stablecoins compatibles en moneda fiat y realiza pagos a cuentas bancarias, dinero móvil y otros rieles locales. El flujo v2 descubre los métodos de pago disponibles para un corredor, devuelve un esquema que describe exactamente lo que necesita cada método, resuelve campos como el nombre de la cuenta del beneficiario, y luego cotiza y ejecuta el retiro desde una master wallet o child address.

Los métodos de pago v2 devuelven un JSON Schema que describe los datos del beneficiario y del pago que su aplicación debe recopilar. Consulte Formularios dinámicos para renderizar, validar, resolver y enviar estos campos. El flujo v1 está disponible en la pestaña v1 · Legacy, pero ya no se recomienda.

Requisitos previos

Antes de utilizar Retiro a Fiat, asegúrese de contar con lo siguiente:

Cumplimiento aprobado

Complete el proceso de Diligencia Debida en el Dashboard: My Wallets → Settings → Compliance. Los requisitos de cumplimiento y los procesos de aprobación varían según la región, por lo que solo necesita completar los correspondientes a los rieles locales que utilice su producto.

Clave de API

Obtenga su clave de API desde el Dashboard de Blockradar. Diríjase a Developers para generarla.

Wallet creada

Cree una wallet desde el dashboard. Necesitará el walletId para las operaciones de retiro.

Asset ID

Consulte los activos fiat compatibles usando Get Supported Assets. Use el id devuelto como assetId a lo largo del flujo.

Cómo funciona

El flujo v2 está orientado por corredor: elige un activo, una moneda y un monto, luego descubre los métodos de pago que admiten ese corredor y recopila exactamente lo que requiere cada método.

Descubrir activos

Consulte las stablecoins compatibles para retiros.

Obtener monedas y tasas

Liste las monedas de pago compatibles y consulte la tasa actual.

Listar métodos de pago

Descubra los métodos disponibles para el activo, la moneda y el monto.

Obtener requisitos

Recupere el JSON Schema que describe los campos que necesita el método.

Resolver y cotizar

Resuelva campos como el nombre de la cuenta y luego cotice comisiones y tasa.

Ejecutar

Envíe paymentMethodData para procesar el retiro.

Monedas fiat compatibles

Las monedas varían según el corredor y el proveedor. Consulte siempre la lista en vivo con Get Supported Currencies en lugar de codificarla de forma fija. La tabla a continuación muestra las stablecoins y blockchains que cubre cada moneda compatible:

Moneda Fiat	Blockchains USDC	Blockchains USDT	Blockchains EURC
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

Retiro a Fiat está disponible en dos niveles:

Master Wallet

Realice retiros desde la master wallet. Ideal para operaciones de tesorería.

Child Address

Realice retiros desde una child address específica. Útil para flujos por usuario.

Endpoints

Operación	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`

Los endpoints de descubrimiento (activos, monedas, tasas, métodos de pago, requisitos, resolución) están limitados a la master wallet. Una vez que tenga un objeto paymentMethodData validado, puede cotizar y ejecutar desde la master wallet o desde una child address.

Flujo típico

Consulte los activos compatibles para elegir la stablecoin a retirar.
Consulte monedas y tasa para el corredor elegido.
Liste los métodos de pago para el activo, la moneda y el monto.
Obtenga los requisitos del método seleccionado para recibir su esquema.
Resuelva campos como el nombre de la cuenta, luego recopile y valide paymentMethodData.
Obtenga una cotización para mostrar las comisiones y la tasa antes de la ejecución.
Ejecute el retiro y haga seguimiento del estado con webhooks.

Paso 1: Obtener los activos compatibles

Consulte las stablecoins disponibles para retiro y tome el id que desee como assetId.

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

Paso 2: Obtener monedas y tasa

Liste las monedas de pago compatibles, luego consulte la tasa actual para el activo, la moneda y el monto.

Parámetro	En	Requerido	Descripción
`assetId`	query	Sí	ID del activo stablecoin a retirar
`currency`	query	Sí	Moneda de pago ISO 4217 (p. ej., `NGN`)
`amount`	query	Sí	Monto decimal como cadena para preservar la precisión

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

Paso 3: Listar métodos de pago

Descubra los métodos de pago disponibles para el corredor. Pase los mismos assetId, currency y amount; opcionalmente acote por country o paymentMethodCategory.

Parámetro	En	Requerido	Descripción
`assetId`	query	Sí	ID del activo stablecoin a retirar
`currency`	query	Sí	Moneda de pago ISO 4217
`amount`	query	Sí	Monto decimal como cadena
`country`	query	No	Código de país ISO 3166-1 alpha-2
`paymentMethodCategory`	query	No	Categoría general, p. ej., `bank`
`provider`	query	No	Slug del proveedor. Omítalo para que Blockradar enrute automáticamente

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 significa que el esquema del método puede incluir un campo x-resolution (como una búsqueda del nombre de la cuenta) que usted resuelve antes de cotizar. Consulte el Paso 5.

Paso 4: Obtener los requisitos del método de pago

Consulte el JSON Schema que describe los campos que necesita el paymentMethod seleccionado. Interprételo y complételo con Formularios dinámicos.

Parámetro	En	Requerido	Descripción
`assetId`	query	Sí	ID del activo stablecoin a retirar
`currency`	query	Sí	Moneda de pago ISO 4217
`amount`	query	Sí	Monto decimal como cadena
`paymentMethod`	query	Sí	`id` del método de pago del Paso 3
`country`	query	No	Código de país ISO 3166-1 alpha-2
`provider`	query	No	Slug del proveedor

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

Paso 5: Resolver campos y construir `paymentMethodData`

Recopile los campos en data.schema. Cuando un campo lleve x-resolution (como accountName arriba), llame al endpoint de resolución una vez que sus campos dependsOn sean válidos, luego almacene el resultado en ese campo.

Parámetro	Tipo	Requerido	Descripción
`assetId`	string	Sí	ID del activo stablecoin
`currency`	string	Sí	Moneda de pago ISO 4217
`amount`	string	Sí	Monto del retiro como cadena decimal
`paymentMethod`	string	Sí	`id` del método de pago
`paymentMethodData`	object	Sí	Valores actuales del formulario requeridos por la resolución
`provider`	string	No	Slug del proveedor seleccionado antes en el flujo

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

Después de resolver y validar, su paymentMethodData completo se ve así:

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

Paso 6: Obtener una cotización

Siempre obtenga una cotización antes de ejecutar para poder mostrar al usuario la tasa, las comisiones y el tiempo estimado de llegada. Envíe el paymentMethodData validado.

Parámetro	Tipo	Requerido	Descripción
`assetId`	string	Sí	ID del activo stablecoin a retirar
`amount`	string	Sí	Monto a retirar como cadena decimal
`currency`	string	Sí	Moneda de pago ISO 4217
`paymentMethod`	string	Sí	`id` del método de pago obtenido en el descubrimiento
`paymentMethodData`	object	Sí	Valores validados contra el esquema de requisitos
`isGaslessWithdraw`	boolean	No	Si Blockradar debe cubrir el gas on-chain cuando sea compatible
`provider`	string	No	Slug del proveedor. Omítalo para el enrutamiento automático

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

Paso 7: Ejecutar el retiro

Una vez que el usuario acepte la cotización, ejecute con los mismos datos. Agregue una reference opcional para idempotencia y seguimiento, además de metadata y note según sea necesario.

Parámetro	Tipo	Requerido	Descripción
`assetId`	string	Sí	ID del activo stablecoin a retirar
`amount`	string	Sí	Monto a retirar como cadena decimal
`currency`	string	Sí	Moneda de pago ISO 4217
`paymentMethod`	string	Sí	`id` del método de pago obtenido en el descubrimiento
`paymentMethodData`	object	Sí	Valores validados contra el esquema de requisitos
`isGaslessWithdraw`	boolean	No	Si Blockradar debe cubrir el gas on-chain cuando sea compatible
`reference`	string	No	Referencia única del cliente para conciliación y reintentos seguros
`metadata`	object	No	Metadatos de su aplicación adjuntos a la transacción
`note`	string	No	Nota legible para humanos sobre este retiro
`provider`	string	No	Slug del proveedor. Omítalo para el enrutamiento automático

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

Respuesta de ejecución

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

Retirar desde una Child Address

Para pagar desde una child address específica, cotice y ejecute contra los endpoints con alcance de dirección usando los mismos cuerpos de solicitud:

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

Webhooks

Haga seguimiento del estado del retiro con los siguientes eventos de webhook:

Evento	Descripción
`offramp.processing`	El retiro está siendo procesado
`offramp.success`	Retiro completado con éxito
`offramp.failed`	El retiro falló

Ejemplo de payload del webhook

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

Para la configuración de webhooks, la estructura del payload y el manejo de eventos, consulte la documentación de Webhooks.

Ejemplo de flujo completo

Una implementación v2 completa que muestra el flujo descubrir → requisitos → resolver → cotizar → ejecutar:

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

Respuestas de error

Datos del método de pago inválidos

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

Moneda no compatible

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

Activo no compatible

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

Funcionalidad no habilitada

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

Saldo insuficiente

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

Saldo nativo insuficiente

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

Buenas prácticas

Experiencia de usuario

Resuelva antes de cotizar: Confirme el nombre de la cuenta del beneficiario mediante el endpoint de resolución antes de mostrar una cotización.
Muestre el costo total: Presente la tasa, la comisión de transacción, la comisión de red y debitAmount.
Visibilice el estado de procesamiento: Use webhooks para actualizar a los usuarios en tiempo real.

Exactitud

Use el esquema devuelto: Recopile solo los campos del esquema de requisitos actual. No codifique de forma fija los campos del beneficiario — consulte Formularios dinámicos.
Preserve las cadenas: Envíe amount y los identificadores de cuenta como cadenas para evitar la pérdida de precisión.
Use referencias: Realice el seguimiento de los retiros con una reference única para reintentos seguros.
Confirme mediante webhooks: Trate offramp.success como la fuente final de verdad.

Rendimiento

Cachee las listas de activos y monedas: Refresque periódicamente en lugar de en cada solicitud.
Vuelva a consultar tasas y métodos por corredor: Las tasas y los métodos de pago dependen del activo, la moneda y el monto.
Reintente ante errores transitorios: Use retroceso exponencial para respuestas 5xx.

Referencia de API

v2 (recomendado)

Endpoint	Descripción
Get Supported Assets	Listar los activos stablecoin compatibles
Get Supported Currencies	Listar las monedas de pago compatibles
Get Exchange Rates	Consultar la tasa para un corredor
Get Payment Methods	Listar los métodos disponibles para el corredor
Get Payment Method Requirements	Consultar el esquema de campos de un método
Resolve Payment Method	Resolver campos como el nombre de la cuenta
Master Wallet Quote	Obtener una cotización desde la master wallet
Master Wallet Execute	Ejecutar un retiro desde la master wallet
Child Address Quote	Obtener una cotización desde una child address
Child Address Execute	Ejecutar un retiro desde una child address

Soporte

Correo: [email protected]
Chat en vivo: Disponible en el dashboard

En resumen
La API de Retiro a Fiat de Blockradar le permite convertir stablecoins compatibles a moneda fiat y transferir los fondos a cuentas bancarias. Puede consultar los activos compatibles, validar cuentas bancarias, obtener cotizaciones y ejecutar retiros tanto desde master wallets como desde child addresses.

Requisitos previos

Antes de utilizar Retiro a Fiat, asegúrese de contar con lo siguiente:

Requisito de cumplimiento

Complete el proceso de Diligencia Debida en el Dashboard: My wallets > Settings > Compliance

Clave de API

Obtenga su clave de API desde el Dashboard de Blockradar. Diríjase a Developers para generarla.

Wallet creada

Cree una wallet desde el dashboard. Necesitará el walletId para las operaciones de retiro.

Asset ID

Consulte los activos fiat compatibles utilizando Get Supported Assets.

Datos de la cuenta bancaria

Recopile un identificador de cuenta válido y un identificador de institución (código bancario).

Cómo funciona

Retiro a Fiat sigue una secuencia sencilla:

Descubrir activos

Consulte los activos compatibles para retiros.

Obtener monedas fiat

Recupere todas las monedas compatibles.

Obtener tasas

Consulte la tasa de cambio actual para el activo seleccionado.

Verificar cuenta

Valide los datos de la cuenta de la institución antes de iniciar un retiro.

Obtener cotización

Estime las comisiones y la tasa de cambio para el monto solicitado.

Ejecutar

Envíe el retiro para su procesamiento.

Monedas fiat compatibles

Moneda	Código
Chelín keniano	KES
Naira nigeriana	NGN
Chelín tanzano	TZS
Chelín ugandés	UGX
Real brasileño	BRL
Kwacha malauí	MWK

Master Wallet vs Child Address

Retiro a Fiat está disponible en dos niveles:

Master Wallet

Realice retiros desde la master wallet. Ideal para operaciones de tesorería.

Child Address

Realice retiros desde una child address específica. Útil para flujos por usuario.

Endpoints

Operación	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`

Flujo típico

Consulte los activos compatibles para elegir la stablecoin a retirar.
Liste las instituciones y seleccione un identificador de banco/institución.
Verifique la cuenta para confirmar el nombre y los datos de la cuenta.
Obtenga una cotización para mostrar las comisiones y la tasa antes de la ejecución.
Ejecute el retiro y haga seguimiento del estado en su sistema.

Paso 1: Obtener una cotización

Siempre obtenga una cotización antes de ejecutar un retiro para poder mostrar la tasa y las comisiones al usuario.

Parámetros de la solicitud

Parámetro	Tipo	Requerido	Descripción
`assetId`	string	Sí	ID del activo stablecoin a retirar
`amount`	string	Sí	Monto a retirar en las unidades del activo
`currency`	string	Sí	Moneda fiat de destino (p. ej., `NGN`)
`accountIdentifier`	string	Sí	Número o identificador de la cuenta bancaria
`institutionIdentifier`	string	Sí	Código del banco/institución

Ejemplo de cotización

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

Paso 2: Ejecutar el retiro

Una vez aceptada la cotización, ejecute el retiro con los mismos datos.

Parámetros de la solicitud

Parámetro	Tipo	Requerido	Descripción
`assetId`	string	Sí	ID del activo stablecoin a retirar
`amount`	string	Sí	Monto a retirar en las unidades del activo
`currency`	string	Sí	Moneda fiat de destino (p. ej., `NGN`)
`accountIdentifier`	string	Sí	Número o identificador de la cuenta bancaria
`institutionIdentifier`	string	Sí	Código del banco/institución
`reference`	string	No	Referencia del cliente para idempotencia/seguimiento
`metadata`	object	No	Metadatos clave-valor adjuntos a la transacción
`note`	string	No	Nota legible para humanos sobre este retiro

Ejemplo de ejecución

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

Respuesta de ejecución

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

Realice el seguimiento del estado del retiro con los siguientes eventos de webhook:

Evento	Descripción
`offramp.processing`	El retiro está siendo procesado
`offramp.success`	Retiro completado con éxito
`offramp.failed`	El retiro falló

Ejemplo de payload del webhook

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

Ejemplo de flujo completo

A continuación, una implementación completa que muestra el flujo verificar → cotizar → ejecutar:

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

Respuestas de error

Datos bancarios inválidos

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

Moneda no compatible

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

Activo no compatible

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

Funcionalidad no habilitada

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

Saldo insuficiente

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

Saldo nativo insuficiente

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

Saldo insuficiente en la Master Wallet

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

Buenas prácticas

Experiencia de usuario

Verifique las cuentas primero: Confirme siempre el nombre de la cuenta antes de mostrar una cotización
Muestre el costo total: Presente la tasa de cambio, la comisión de red y el monto total
Visibilice el estado de procesamiento: Use webhooks para actualizar a los usuarios en tiempo real

Seguridad

Valide las entradas: Asegúrese de que la moneda, la institución y los identificadores de cuenta estén bien formados
Use referencias: Realice el seguimiento de los retiros con un reference único
Confirme mediante webhooks: Trate offramp.success como la fuente final de verdad

Rendimiento

Cachee las listas de instituciones: Refresque periódicamente en lugar de hacerlo en cada solicitud
Reutilice los metadatos de los activos: Cachee los activos y monedas compatibles
Reintente ante errores transitorios: Use retroceso exponencial para respuestas 5xx

Referencia de la API

Endpoint	Descripción
Get Supported Assets	Listar los activos stablecoin compatibles
Get Institutions	Listar instituciones por moneda
Get Exchange Rates	Obtener la tasa de cambio para una cotización
Get Currencies	Listar monedas fiat compatibles
Verify Institution Account	Verificar los datos de la cuenta bancaria
Master Wallet Quote	Obtener cotización desde la master wallet
Master Wallet Execute	Ejecutar retiro desde la master wallet
Child Address Quote	Obtener cotización desde una child address
Child Address Execute	Ejecutar retiro desde una child address

Soporte

Correo: [email protected]
Documentación: Referencia de la API

​Requisitos previos

​Cómo funciona

Descubrir activos

Obtener monedas y tasas

Listar métodos de pago

Obtener requisitos

Resolver y cotizar

Ejecutar

​Monedas fiat compatibles

​Master Wallet vs Child Address

Master Wallet

Child Address

​Endpoints

​Flujo típico

​Paso 1: Obtener los activos compatibles

​Paso 2: Obtener monedas y tasa

​Paso 3: Listar métodos de pago

​Paso 4: Obtener los requisitos del método de pago

​Paso 5: Resolver campos y construir paymentMethodData

​Paso 6: Obtener una cotización

​Paso 7: Ejecutar el retiro

​Respuesta de ejecución

​Retirar desde una Child Address

​Webhooks

​Ejemplo de payload del webhook

​Ejemplo de flujo completo

​Respuestas de error

​Buenas prácticas

​Experiencia de usuario

​Exactitud

​Rendimiento

​Referencia de API

​v2 (recomendado)

​Soporte

​Requisitos previos

​Cómo funciona

Descubrir activos

Obtener monedas fiat

Obtener tasas

Verificar cuenta

Obtener cotización

Ejecutar

​Monedas fiat compatibles

​Master Wallet vs Child Address

Master Wallet

Child Address

​Endpoints

​Flujo típico

​Paso 1: Obtener una cotización

​Parámetros de la solicitud

​Ejemplo de cotización

​Paso 2: Ejecutar el retiro

​Parámetros de la solicitud

​Ejemplo de ejecución

​Respuesta de ejecución

​Webhooks

​Ejemplo de payload del webhook

​Ejemplo de flujo completo

​Respuestas de error

​Buenas prácticas

​Experiencia de usuario

​Seguridad

​Rendimiento

​Referencia de la API

​Soporte

Requisitos previos

Cómo funciona

Monedas fiat compatibles

Master Wallet vs Child Address

Endpoints

Flujo típico

Paso 1: Obtener los activos compatibles

Paso 2: Obtener monedas y tasa

Paso 3: Listar métodos de pago

Paso 4: Obtener los requisitos del método de pago

Paso 5: Resolver campos y construir `paymentMethodData`

Paso 6: Obtener una cotización

Paso 7: Ejecutar el retiro

Respuesta de ejecución

Retirar desde una Child Address

Webhooks

Ejemplo de payload del webhook

Ejemplo de flujo completo

Respuestas de error

Buenas prácticas

Experiencia de usuario

Exactitud

Rendimiento

Referencia de API

v2 (recomendado)

Soporte

Requisitos previos

Cómo funciona

Monedas fiat compatibles

Master Wallet vs Child Address

Endpoints

Flujo típico

Paso 1: Obtener una cotización

Parámetros de la solicitud

Ejemplo de cotización

Paso 2: Ejecutar el retiro

Parámetros de la solicitud

Ejemplo de ejecución

Respuesta de ejecución

Webhooks

Ejemplo de payload del webhook

Ejemplo de flujo completo

Respuestas de error

Buenas prácticas

Experiencia de usuario

Seguridad

Rendimiento

Referencia de la API

Soporte