Saltar al contenido principal
En resumen
La API de Retiro Fiat de Blockradar te permite convertir stablecoins compatibles en moneda fiat y transferir fondos a cuentas bancarias. Puedes consultar activos compatibles, validar cuentas bancarias, obtener cotizaciones y ejecutar retiros desde billeteras principales y direcciones hijas.
Interfaz de Retiro Fiat de Blockradar

Requisitos previos

Antes de usar Retiro Fiat, asegúrate de contar con lo siguiente:
1

Requisito de cumplimiento

Completa el onboarding de socios antes de solicitar acceso a Retiro Fiat (consulta Requisitos de cumplimiento más abajo).
2

Clave API

Obtén tu clave API desde el Panel de Blockradar. Ve a Developers para generar una.
3

Billetera creada

Crea una billetera desde el panel. Necesitarás el walletId para las operaciones de retiro.
4

ID del activo

Consulta los activos fiat compatibles usando Obtener activos compatibles.
5

Datos bancarios

Reúne un identificador de cuenta válido y un identificador de institución (código del banco).

Cómo funciona

Retiro Fiat sigue una secuencia simple:

Descubrir activos

Consulta los activos compatibles para retiros.

Obtener monedas fiat

Recupera todas las monedas compatibles.

Obtener tasas

Consulta el tipo de cambio actual para el activo seleccionado.

Verificar cuenta

Valida los datos de la cuenta bancaria antes de iniciar el retiro.

Obtener cotización

Estima comisiones y tipo de cambio para el monto solicitado.

Ejecutar

Envía el retiro para su procesamiento.

Requisitos de cumplimiento

Antes de acceder a Retiro Fiat, completa el proceso de onboarding de cumplimiento correspondiente a la cobertura de la moneda de pago que necesitas.

Elige tu ruta de onboarding

Si necesitas acceso tanto a NGN como a otras monedas africanas compatibles, completa ambos procesos de onboarding.

Requisito de aprobación

El acceso a Retiro Fiat se habilita después de la revisión de cumplimiento y la aprobación para la ruta de onboarding que hayas elegido.

Billetera principal vs dirección hija

Retiro Fiat está disponible en dos niveles:

Billetera principal

Retira desde la billetera principal. Ideal para operaciones de tesorería.

Dirección hija

Retira desde una dirección hija específica. Útil para flujos por usuario.

Endpoints

OperaciónBilletera principalDirección hija
Obtener activos compatiblesGET /v1/wallets/{walletId}/withdraw/fiat/assets
Obtener institucionesGET /v1/wallets/{walletId}/withdraw/fiat/institutions
Obtener tasas de cambioGET /v1/wallets/{walletId}/withdraw/fiat/rates
Obtener monedasGET /v1/wallets/{walletId}/withdraw/fiat/currencies
Verificar cuenta institucionalPOST /v1/wallets/{walletId}/withdraw/fiat/institution-account-verification
Obtener cotizaciónPOST /v1/wallets/{walletId}/withdraw/fiat/quotePOST /v1/wallets/{walletId}/addresses/{addressId}/withdraw/fiat/quote
EjecutarPOST /v1/wallets/{walletId}/withdraw/fiat/executePOST /v1/wallets/{walletId}/addresses/{addressId}/withdraw/fiat/execute

Flujo típico

  1. Consulta los activos compatibles para elegir la stablecoin a retirar.
  2. Lista instituciones y selecciona un identificador de banco/institución.
  3. Verifica la cuenta para confirmar nombre y datos de la cuenta.
  4. Obtén una cotización para mostrar comisiones y tasa antes de ejecutar.
  5. Ejecuta el retiro y da seguimiento al estado en tu sistema.

Paso 1: Obtener una cotización

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

Parámetros de la solicitud

ParámetroTipoRequeridoDescripción
assetIdstringID del activo stablecoin que deseas retirar
amountnumberMonto a retirar en las unidades del activo
currencystringMoneda fiat de destino (por ejemplo, NGN)
accountIdentifierstringNúmero de cuenta bancaria o identificador
institutionIdentifierstringCó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, ejecuta el retiro con los mismos datos (y cualquier código/OTP requerido).

Parámetros de la solicitud

ParámetroTipoRequeridoDescripción
assetIdstringID del activo stablecoin que deseas retirar
amountnumberMonto a retirar en las unidades del activo
currencystringMoneda fiat de destino (por ejemplo, NGN)
accountIdentifierstringNúmero de cuenta bancaria o identificador
institutionIdentifierstringCódigo del banco/institución
codestringNoCódigo de verificación si el proveedor lo requiere

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",
    "code": "445223"
  }'

Respuesta de ejecución

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

Webhooks

Haz seguimiento del estado del retiro con los siguientes eventos webhook:
EventoDescripción
offramp.processingEl retiro está siendo procesado
offramp.successEl retiro se completó correctamente
offramp.failedEl retiro falló

Ejemplo de payload 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 se muestra una implementación completa del flujo verificar → cotizar → ejecutar:
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",
});

Respuestas de error

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

Buenas prácticas

Experiencia de usuario

  • Verifica cuentas primero: Confirma siempre el nombre de la cuenta antes de mostrar una cotización
  • Muestra el costo total: Presenta tipo de cambio, comisión de red y monto total
  • Muestra el estado de procesamiento: Usa webhooks para actualizar a los usuarios en tiempo real

Seguridad

  • Valida entradas: Asegúrate de que moneda, institución e identificadores de cuenta tengan un formato correcto
  • Usa referencias: Rastrea retiros con una reference única
  • Confirma vía webhooks: Trata offramp.success como la fuente final de verdad

Rendimiento

  • Cachea listas de instituciones: Actualízalas periódicamente en lugar de hacerlo en cada solicitud
  • Reutiliza metadatos de activos: Cachea activos y monedas compatibles
  • Reintenta errores transitorios: Usa backoff exponencial para respuestas 5xx

Referencia de API

EndpointDescripción
Obtener activos compatiblesLista los activos stablecoin compatibles
Obtener institucionesLista instituciones por moneda
Obtener tasas de cambioConsulta el tipo de cambio para una cotización
Obtener monedasLista monedas fiat compatibles
Verificar cuenta institucionalVerifica los datos de una cuenta bancaria
Cotización de billetera principalObtiene una cotización desde la billetera principal
Ejecución de billetera principalEjecuta un retiro desde la billetera principal
Cotización de dirección hijaObtiene una cotización desde una dirección hija
Ejecución de dirección hijaEjecuta un retiro desde una dirección hija

Soporte