Retirar Stablecoins - Blockradar

En resumen
La API de Withdraw de Blockradar le permite enviar activos stablecoin desde sus billeteras a direcciones blockchain externas. Soporta retiros individuales, retiros por lotes hacia múltiples destinatarios, y proporciona estimación de comisiones antes de la ejecución.

Requisitos previos

Antes de utilizar la API de Withdraw, asegúrese de contar con:

Clave API

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

Billetera creada

Cree una billetera mediante la API Create Wallet o desde el dashboard. Necesitará el walletId para las operaciones de retiro.

ID de activo

Obtenga el assetId del token que desea retirar desde Assets en el dashboard o mediante la API Get Assets.

Saldo suficiente

Asegúrese de que su billetera tenga suficiente saldo del activo a retirar, además del token nativo (ETH, BNB, MATIC, etc.) para cubrir las comisiones de red.

Cómo funciona

La API de Withdraw envía activos stablecoin desde su billetera de Blockradar a cualquier dirección blockchain externa:

Retiro individual

Envíe activos a una dirección de destinatario con una sola llamada API.

Retiro por lotes

Envíe activos a múltiples destinatarios en una sola llamada API, reduciendo la sobrecarga y simplificando los pagos masivos.

Estimación de comisiones

Calcule las comisiones de red antes de la ejecución para garantizar saldo suficiente y mostrar los costos a los usuarios.

Modo Sign-Only

Firme transacciones sin transmitirlas para casos de uso avanzados como firma offline o envío personalizado.

Master Wallet vs Child Address

La API de Withdraw está disponible en dos niveles:

Master Wallet

Retire directamente desde su master wallet. Ideal para operaciones de tesorería y gestión centralizada de fondos.

Child Address

Retire desde child addresses individuales. Perfecto para operaciones específicas de usuario y gestión segregada de fondos.

Endpoints

Operación	Master Wallet	Child Address
Withdraw	`POST /v1/wallets/{walletId}/withdraw`	`POST /v1/wallets/{walletId}/addresses/{addressId}/withdraw`
Comisión de red	`POST /v1/wallets/{walletId}/withdraw/network-fee`	`POST /v1/wallets/{walletId}/addresses/{addressId}/withdraw/network-fee`
Sign-Only	`POST /v1/wallets/{walletId}/withdraw/sign`	`POST /v1/wallets/{walletId}/addresses/{addressId}/withdraw/sign`

Retiro individual

Envíe activos a una sola dirección de destinatario.

Parámetros de la solicitud

Parámetro	Tipo	Requerido	Descripción
`assetId`	string	Sí*	El UUID del activo a retirar. Requerido si no se proporciona el array `assets`.
`address`	string	Sí*	La dirección de destino. Requerido si no se proporciona el array `assets`. Para los formatos de destinatario en Stellar, consulte Direcciones de destinatario en Stellar.
`amount`	string	Sí*	El monto del retiro. Debe ser mayor que 0. Requerido si no se proporciona el array `assets`.
`reference`	string	No	Su ID interno de seguimiento para el retiro.
`note`	string	No	Un mensaje breve o nota interna. En Stellar y Solana, se adjunta a la transacción como el memo en la cadena — consulte Memos en la cadena. No visible en la cadena en los demás casos.
`metadata`	object	No	Pares clave-valor personalizados para detalles adicionales de la transacción.

Los parámetros marcados con * son requeridos para retiros individuales pero no son necesarios si está utilizando el array assets para retiros por lotes.

Ejemplo de retiro individual

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/withdraw \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assetId": "asset-uuid-here",
    "address": "0xRecipientAddress...",
    "amount": "100",
    "reference": "payout-12345",
    "note": "Monthly payout",
    "metadata": {
      "userId": "user_abc123",
      "payoutType": "salary"
    }
  }'

const withdrawal = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/withdraw`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      assetId: 'asset-uuid-here',
      address: '0xRecipientAddress...',
      amount: '100',
      reference: 'payout-12345',
      note: 'Monthly payout',
      metadata: {
        userId: 'user_abc123',
        payoutType: 'salary'
      }
    })
  }
).then(r => r.json());

console.log('Withdrawal initiated:', withdrawal.data);

Respuesta del retiro individual

{
  "message": "Withdrawal initiated successfully",
  "statusCode": 200,
  "data": {
    "id": "tx-uuid-123",
    "hash": "0xabc123...",
    "status": "PENDING",
    "amount": "100",
    "recipientAddress": "0xRecipientAddress...",
    "reference": "payout-12345",
    "note": "Monthly payout",
    "metadata": {
      "userId": "user_abc123",
      "payoutType": "salary"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Memos en la cadena

En Stellar y Solana, el campo note de un retiro se escribe en la blockchain como el memo de la transacción. Los memos en la cadena son públicos — cualquiera puede leerlos en un explorador —, así que nunca incluya datos sensibles en una note en estas cadenas. En las demás cadenas, la nota no se publica en la cadena. En todos los casos, la note se almacena en el registro de transacción de Blockradar.

Memos en Stellar

En Stellar, el tipo de memo se deriva del contenido de la nota:

Su `note`	Resultado en la cadena
Solo dígitos, hasta `18446744073709551615` (el máximo de 64 bits sin signo)	Memo ID — el formato que la mayoría de los exchanges exigen para acreditar depósitos
Cualquier otro valor, de hasta 28 bytes en UTF-8	Memo de texto
Omitido	Sin memo

Para retirar a una cuenta de exchange que requiere un memo numérico, pase como note el memo ID emitido por el exchange:

{
  "assetId": "asset-uuid-here",
  "address": "GExchangeDepositAddress...",
  "amount": "100",
  "note": "10012345"
}

Stellar limita los memos de texto a 28 bytes. Una note más larga es aceptada por la API, pero el retiro falla durante el procesamiento y el motivo del fallo incluye Memo must be at most 28 bytes for Stellar text memos. En Stellar, mantenga las notas dentro de 28 bytes — o use solo dígitos para enviar un memo ID.

Nunca se adjuntan memos para destinatarios muxed (M...) ni de contrato (C...) — consulte Direcciones de destinatario en Stellar.

Memos en Solana

En Solana, la note se adjunta a la transacción de retiro como una instrucción del programa SPL Memo, tanto para retiros de SOL como de tokens:

El memo es siempre texto plano UTF-8 — Solana no tiene el tipo memo ID, por lo que una note de solo dígitos se escribe como texto literal.
El memo está firmado por la dirección remitente, de modo que los destinatarios y los indexadores pueden verificar que proviene del remitente.
El programa Memo acepta como máximo 566 bytes en UTF-8. Las notas más largas fallan durante el procesamiento — y cuanto más cortas mejor, ya que el memo cuenta para el límite de tamaño de transacción de Solana.

Direcciones de destinatario en Stellar

En Stellar, el campo address acepta tres formatos de destinatario. Las mismas reglas aplican a los retiros individuales, los retiros por lotes, la estimación de comisiones y el modo sign-only, tanto en los endpoints de master wallet como de child address.

Formato	Tipo de destinatario	Activos soportados
`G...`	Cuenta clásica	Todos los activos (XLM y tokens)
`M...`	Cuenta muxed	Todos los activos (XLM y tokens)
`C...`	Contrato Soroban	Solo activos token (p. ej. USDC, EURC)

Cuentas muxed (`M...`)

Una dirección muxed incorpora un ID de enrutamiento sobre una cuenta clásica G.... Los exchanges y las plataformas de custodia las utilizan para acreditar al usuario final correcto sin depender de un memo. Los fondos enviados a una dirección muxed se liquidan en su cuenta G... subyacente. Para destinatarios muxed, no se adjunta ningún memo — el ID de enrutamiento ya está incorporado en la propia dirección. Su note se almacena de todos modos en el registro de transacción de Blockradar.

Contratos Soroban (`C...`)

Los retiros de tokens a una dirección de contrato se ejecutan como una invocación transfer en el Stellar Asset Contract del token y se envían vía Soroban RPC. En la cadena, el resultado es una invocación de contrato en lugar de una operación de pago clásica — tenga esto en cuenta si las herramientas del destinatario solo monitorean operaciones de pago. Los destinatarios de contrato están soportados solo para activos token:

Soportado: retiros de tokens (p. ej. USDC, EURC), la estimación de comisión de red correspondiente y el modo sign-only.
No soportado: retiros de XLM nativo — enviar XLM a una dirección C... devuelve un error 400. Los destinos de retiros a fiat, swaps y liquidaciones automáticas también requieren una dirección clásica G... o muxed M....

Los retiros de tokens a destinatarios G... o M... requieren que la cuenta de destino exista y tenga una trustline para el activo (consulte Activación de Direcciones). Los destinatarios de contrato no tienen requisito de trustline, y no se adjunta ningún memo a las transferencias de contrato.

Retiros por lotes

Envíe activos a múltiples destinatarios en una sola llamada API. Los retiros por lotes se ejecutan secuencialmente, y cada retiro se procesa como una transacción blockchain independiente.

Cuándo usar retiros por lotes

Pagos masivos: Pague a múltiples empleados, proveedores o socios a la vez
Distribuciones: Envíe activos a múltiples direcciones
Transferencias multi-destinatario: Envíe diferentes montos a diferentes direcciones
Eficiencia operativa: Reduzca las llamadas API y simplifique la lógica de pagos

Parámetros de la solicitud por lotes

Para retiros por lotes, utilice el array assets en lugar de parámetros individuales:

Parámetro	Tipo	Requerido	Descripción
`assets`	array	Sí	Array de objetos de retiro (máximo 20 por lote)

Cada elemento del array assets:

Campo	Tipo	Requerido	Descripción
`id`	string	Sí	El UUID del activo a retirar
`address`	string	Sí	La dirección de destino. Para los formatos de destinatario en Stellar, consulte Direcciones de destinatario en Stellar.
`amount`	string	Sí	El monto del retiro. Debe ser mayor que 0.
`reference`	string	No	Nota de referencia opcional para este retiro
`note`	string	No	Un mensaje breve o nota interna. En Stellar y Solana, se adjunta a la transacción como el memo en la cadena — consulte Memos en la cadena. No visible en la cadena en los demás casos.
`metadata`	object	No	Pares clave-valor personalizados para detalles adicionales de la transacción.

Ejemplo de retiro por lotes

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/withdraw \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assets": [
      {
        "id": "asset-uuid-usdc",
        "address": "0xRecipient1...",
        "amount": "100",
        "reference": "payout-001",
        "note": "January salary"
      },
      {
        "id": "asset-uuid-usdc",
        "address": "0xRecipient2...",
        "amount": "150",
        "reference": "payout-002",
        "note": "January salary"
      },
      {
        "id": "asset-uuid-usdt",
        "address": "0xRecipient3...",
        "amount": "200",
        "reference": "payout-003",
        "note": "Vendor payment"
      }
    ]
  }'

const batchWithdrawal = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/withdraw`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      assets: [
        {
          id: 'asset-uuid-usdc',
          address: '0xRecipient1...',
          amount: '100',
          reference: 'payout-001',
          note: 'January salary'
        },
        {
          id: 'asset-uuid-usdc',
          address: '0xRecipient2...',
          amount: '150',
          reference: 'payout-002',
          note: 'January salary'
        },
        {
          id: 'asset-uuid-usdt',
          address: '0xRecipient3...',
          amount: '200',
          reference: 'payout-003',
          note: 'Vendor payment'
        }
      ]
    })
  }
).then(r => r.json());

console.log('Batch withdrawal result:', batchWithdrawal.data);

Respuesta del retiro por lotes

{
  "message": "Batch withdrawal initiated successfully",
  "statusCode": 200,
  "data": {
    "success": [
      {
        "index": 0,
        "id": "tx-uuid-1",
        "hash": "0xabc...",
        "status": "PENDING",
        "amount": "100",
        "recipientAddress": "0xRecipient1...",
        "reference": "payout-001"
      },
      {
        "index": 1,
        "id": "tx-uuid-2",
        "hash": "0xdef...",
        "status": "PENDING",
        "amount": "150",
        "recipientAddress": "0xRecipient2...",
        "reference": "payout-002"
      },
      {
        "index": 2,
        "id": "tx-uuid-3",
        "hash": "0xghi...",
        "status": "PENDING",
        "amount": "200",
        "recipientAddress": "0xRecipient3...",
        "reference": "payout-003"
      }
    ],
    "errors": []
  }
}

Manejo de fallos parciales

Los retiros por lotes admiten éxito parcial. Si algunos retiros fallan, los demás se ejecutarán igualmente:

const result = await batchWithdrawal.json();

// Process successful withdrawals
result.data.success.forEach(tx => {
  console.log(`✓ ${tx.reference}: ${tx.hash}`);
});

// Handle failed withdrawals
result.data.errors.forEach(error => {
  console.error(`✗ Index ${error.index}: ${error.error}`);
  // Retry logic or error reporting here
});

Reglas de retiro por lotes

Regla	Valor
Tamaño máximo del lote	20 retiros por solicitud
Tamaño mínimo del lote	1 retiro
Orden de ejecución	Secuencial
Manejo de errores	Éxito parcial (los fallos no detienen los retiros posteriores)

Estimación de comisiones de red

Estime siempre las comisiones antes de ejecutar retiros para asegurar saldo suficiente del token nativo y mostrar costos precisos a los usuarios.

Estimación de comisión individual

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/withdraw/network-fee \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assetId": "asset-uuid-here",
    "address": "0xRecipientAddress...",
    "amount": "100"
  }'

const fee = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/withdraw/network-fee`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      assetId: 'asset-uuid-here',
      address: '0xRecipientAddress...',
      amount: '100'
    })
  }
).then(r => r.json());

console.log('Network fee:', fee.data.networkFee);
console.log('Fee in USD:', fee.data.networkFeeInUSD);

Respuesta de comisión individual

{
  "message": "Network fee fetched successfully",
  "statusCode": 200,
  "data": {
    "networkFee": "0.00001247904",
    "networkFeeInUSD": "0.01",
    "transactionFee": "0",
    "nativeBalance": "0.5",
    "nativeBalanceInUSD": "450.00",
    "estimatedArrivalTime": 30
  }
}

Estimación de comisiones por lotes

Estime comisiones para múltiples retiros a la vez:

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/withdraw/network-fee \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assets": [
      {
        "id": "asset-uuid-1",
        "address": "0xRecipient1...",
        "amount": "100"
      },
      {
        "id": "asset-uuid-2",
        "address": "0xRecipient2...",
        "amount": "50"
      }
    ]
  }'

const batchFee = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/withdraw/network-fee`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      assets: [
        {
          id: 'asset-uuid-1',
          address: '0xRecipient1...',
          amount: '100'
        },
        {
          id: 'asset-uuid-2',
          address: '0xRecipient2...',
          amount: '50'
        }
      ]
    })
  }
).then(r => r.json());

console.log('Total network fee:', batchFee.data.totalNetworkFee);
console.log('Total fee in USD:', batchFee.data.totalNetworkFeeInUSD);

Respuesta de comisión por lotes

{
  "message": "Network fee fetched successfully",
  "statusCode": 200,
  "data": {
    "fees": [
      {
        "index": 0,
        "assetId": "asset-uuid-1",
        "address": "0xRecipient1...",
        "amount": "100",
        "networkFee": "0.00001247904",
        "transactionFee": "0",
        "estimatedArrivalTime": 30
      },
      {
        "index": 1,
        "assetId": "asset-uuid-2",
        "address": "0xRecipient2...",
        "amount": "50",
        "networkFee": "0.00000504",
        "transactionFee": "0",
        "estimatedArrivalTime": 30
      }
    ],
    "totalNetworkFee": "0.00001751904",
    "totalNetworkFeeInUSD": "0.02",
    "totalTransactionFee": "0",
    "nativeBalance": "0.073690520542044578",
    "nativeBalanceInUSD": "66.54",
    "estimatedArrivalTime": 60,
    "errors": []
  }
}

Campos de la respuesta de comisión

Campo	Descripción
`networkFee`	Comisión de gas en unidades de token nativo (retiro individual)
`networkFeeInUSD`	Comisión de gas convertida a USD (retiro individual)
`fees`	Array de estimaciones individuales de comisión (retiro por lotes)
`totalNetworkFee`	Suma de todas las comisiones de red (retiro por lotes)
`totalNetworkFeeInUSD`	Comisión total de red en USD (retiro por lotes)
`transactionFee`	Comisión de transacción de la plataforma (si aplica)
`nativeBalance`	Saldo actual del token nativo
`nativeBalanceInUSD`	Saldo del token nativo en USD
`estimatedArrivalTime`	Tiempo de confirmación esperado en segundos
`errors`	Array de cualquier estimación fallida (retiro por lotes)

Modo Sign-Only

Firme transacciones sin transmitirlas a la blockchain. Útil para:

Firma offline: Prepare transacciones para envío posterior
Flujos multi-firma: Recolecte firmas antes del envío
Inspección de transacciones: Revise detalles de la transacción antes de transmitirla

Ejemplo de Sign-Only

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/withdraw/sign \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assetId": "asset-uuid-here",
    "address": "0xRecipientAddress...",
    "amount": "100"
  }'

const signedTx = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/withdraw/sign`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      assetId: 'asset-uuid-here',
      address: '0xRecipientAddress...',
      amount: '100'
    })
  }
).then(r => r.json());

console.log('Signed transaction:', signedTx.data.signedTransaction);

Respuesta de Sign-Only

{
  "message": "Transaction signed successfully",
  "statusCode": 200,
  "data": {
    "id": "tx-uuid-123",
    "signedTransaction": "0xf86c...",
    "status": "SIGNED",
    "amount": "100",
    "recipientAddress": "0xRecipientAddress...",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Retiros desde Child Address

Retire desde child addresses individuales en lugar de la master wallet:

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/withdraw \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "assetId": "asset-uuid-here",
    "address": "0xRecipientAddress...",
    "amount": "50",
    "reference": "user-withdrawal-123"
  }'

const childWithdrawal = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/addresses/${addressId}/withdraw`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      assetId: 'asset-uuid-here',
      address: '0xRecipientAddress...',
      amount: '50',
      reference: 'user-withdrawal-123'
    })
  }
).then(r => r.json());

console.log('Child address withdrawal:', childWithdrawal.data);

Los retiros desde child address también admiten operaciones por lotes utilizando el array assets, siguiendo el mismo formato que los retiros por lotes desde master wallet.

Eventos de Webhook

Monitoree la finalización de los retiros mediante webhooks:

Evento	Descripción
`withdraw.success`	Retiro completado y confirmado en la blockchain
`withdraw.failed`	El retiro no pudo ejecutarse
`withdraw.cancelled`	El retiro fue cancelado antes de completarse

Payload del Webhook

{
  "event": "withdraw.success",
  "data": {
    "id": "081d6315-159f-4c38-b02a-c4708836c5bd",
    "reference": "payout-12345",
    "senderAddress": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a",
    "recipientAddress": "0x2455eC6700092991Ce0782365A89d5Cd89c8Fa22",
    "amount": "100",
    "amountPaid": "100",
    "fee": null,
    "currency": "USD",
    "blockNumber": 6928833,
    "hash": "0x5fcb7dd11cbb5a6d64da08cf7e0d63c1a1e7b9d1b89e3e8d1c6a5f4b3a2c1d0e",
    "status": "SUCCESS",
    "type": "WITHDRAW",
    "note": "Monthly payout",
    "asset": {
      "id": "asset-uuid",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6
    },
    "wallet": {
      "id": "wallet-uuid",
      "name": "Main Treasury"
    },
    "blockchain": {
      "id": "blockchain-uuid",
      "name": "ethereum",
      "network": "mainnet"
    },
    "metadata": {
      "userId": "user_abc123",
      "payoutType": "salary"
    },
    "networkFee": {
      "amount": "0.00027",
      "symbol": "ETH",
      "amountUsd": "0.702040"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:31:00Z"
  }
}

networkFee es la comisión de red total que pagaron tus billeteras por este pago, en el token nativo de la cadena y en USD. Úsala para trasladar el costo exacto a tu cliente. El desglose por transacción está disponible en el campo networkFees, consulta Comisiones de red en los payloads de webhooks.

Ejemplo de flujo completo

A continuación se muestra una implementación completa del flujo: estimación de comisión → confirmación del usuario → retiro:

async function processWithdrawal(walletId, assetId, recipientAddress, amount) {
  const apiKey = process.env.BLOCKRADAR_API_KEY;
  const baseUrl = 'https://api.blockradar.co/v1';

  // Step 1: Estimate network fee
  const feeResponse = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw/network-fee`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        assetId,
        address: recipientAddress,
        amount
      })
    }
  ).then(r => r.json());

  // Step 2: Check if we have enough native balance for gas
  const fee = feeResponse.data;
  if (parseFloat(fee.nativeBalance) < parseFloat(fee.networkFee)) {
    throw new Error(`Insufficient gas: need ${fee.networkFee}, have ${fee.nativeBalance}`);
  }

  // Step 3: Display fee to user (in your UI)
  console.log(`Network fee: ${fee.networkFee} (≈$${fee.networkFeeInUSD})`);
  console.log(`Estimated time: ${fee.estimatedArrivalTime}s`);

  // Step 4: Execute withdrawal (after user confirmation)
  const withdrawal = await fetch(
    `${baseUrl}/wallets/${walletId}/withdraw`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        assetId,
        address: recipientAddress,
        amount,
        reference: `withdraw-${Date.now()}`
      })
    }
  ).then(r => r.json());

  console.log('Withdrawal initiated:', withdrawal.data.id);
  console.log('Transaction hash:', withdrawal.data.hash);

  // Step 5: Listen for webhook to confirm completion
  return withdrawal.data;
}

// Usage
processWithdrawal(
  'wallet-uuid',
  'asset-uuid-usdc',
  '0xRecipientAddress...',
  '100'
);

Respuestas de error

Saldo insuficiente

{
  "message": "Insufficient balance for withdrawal",
  "statusCode": 400,
  "error": "INSUFFICIENT_BALANCE",
  "data": {
    "required": "100",
    "available": "50.25",
    "asset": "USDC"
  }
}

Gas insuficiente

{
  "message": "Insufficient native token balance for gas",
  "statusCode": 400,
  "error": "INSUFFICIENT_GAS",
  "data": {
    "required": "0.005",
    "available": "0.001",
    "token": "ETH"
  }
}

Dirección inválida

{
  "message": "Invalid recipient address",
  "statusCode": 400,
  "error": "INVALID_ADDRESS",
  "data": {
    "address": "invalid_address_here"
  }
}

Activo no encontrado

{
  "message": "Asset not found",
  "statusCode": 404,
  "error": "ASSET_NOT_FOUND",
  "data": {
    "assetId": "invalid-asset-uuid"
  }
}

Monto demasiado bajo

{
  "message": "Amount must be greater than 0",
  "statusCode": 400,
  "error": "INVALID_AMOUNT",
  "data": {
    "amount": "0"
  }
}

Tamaño de lote excedido

{
  "message": "Batch size exceeds maximum limit",
  "statusCode": 400,
  "error": "BATCH_SIZE_EXCEEDED",
  "data": {
    "maximum": 20,
    "provided": 25
  }
}

Mejores prácticas

Seguridad

Valide direcciones: Verifique siempre las direcciones de los destinatarios antes de iniciar retiros — el endpoint Validate Address comprueba si una dirección es válida para una blockchain determinada y devuelve la forma con checksum para direcciones EVM
Use referencias: Rastree los retiros con IDs de referencia únicos para conciliación
Implemente webhooks: Escuche los eventos withdraw.success y withdraw.failed para confirmar el estado
Verifique AML: Blockradar detecta automáticamente las direcciones; revise cualquier transacción marcada

Gestión de comisiones

Estime antes de la ejecución: Llame siempre al endpoint network-fee antes de los retiros
Monitoree el saldo nativo: Asegure suficiente ETH/BNB/MATIC para las comisiones de gas
Use lotes para mayor eficiencia: Agrupe múltiples retiros para reducir las llamadas API y la sobrecarga operativa

Manejo de errores

Maneje fallos parciales: En retiros por lotes, revise tanto los arrays success como errors
Implemente reintentos: Use backoff exponencial para fallos transitorios
Registre todas las transacciones: Almacene IDs y hashes de transacciones para depuración y conciliación

Rendimiento

Use tamaños de lote adecuados: Lotes más grandes reducen las llamadas API pero aumentan el tiempo de cada solicitud
Almacene los IDs de activos en caché: Guarde los IDs de activos localmente para evitar consultas repetidas
Implemente limitación de tasa: Respete los límites de tasa de la API para evitar throttling

Referencia API

Endpoints de Master Wallet

Endpoint	Descripción
Withdraw	Ejecutar retiro individual o por lotes
Network Fee	Estimar comisiones de retiro
Sign-Only	Firmar sin transmitir

Endpoints de Child Address

Endpoint	Descripción
Withdraw	Ejecutar retiro individual o por lotes
Network Fee	Estimar comisiones de retiro
Sign-Only	Firmar sin transmitir

Soporte

Email: [email protected]
Documentación: Referencia API
Guía de Webhooks: Webhooks

La API de Withdraw proporciona una interfaz flexible para enviar activos stablecoin a direcciones externas. Comience con retiros individuales y estimación de comisiones, e incorpore operaciones por lotes para pagos masivos a medida que sus necesidades crezcan.

​Requisitos previos

​Cómo funciona

Retiro individual

Retiro por lotes

Estimación de comisiones

Modo Sign-Only

​Master Wallet vs Child Address

Master Wallet

Child Address

​Endpoints

​Retiro individual

​Parámetros de la solicitud

​Ejemplo de retiro individual

​Respuesta del retiro individual

​Memos en la cadena

​Memos en Stellar

​Memos en Solana

​Direcciones de destinatario en Stellar

​Cuentas muxed (M...)

​Contratos Soroban (C...)

​Retiros por lotes

​Cuándo usar retiros por lotes

​Parámetros de la solicitud por lotes

​Ejemplo de retiro por lotes

​Respuesta del retiro por lotes

​Manejo de fallos parciales

​Reglas de retiro por lotes

​Estimación de comisiones de red

​Estimación de comisión individual

​Respuesta de comisión individual

​Estimación de comisiones por lotes

​Respuesta de comisión por lotes

​Campos de la respuesta de comisión

​Modo Sign-Only

​Ejemplo de Sign-Only

​Respuesta de Sign-Only

​Retiros desde Child Address

​Eventos de Webhook

​Payload del Webhook

​Ejemplo de flujo completo

​Respuestas de error

​Mejores prácticas

​Seguridad

​Gestión de comisiones

​Manejo de errores

​Rendimiento

​Referencia API

​Endpoints de Master Wallet

​Endpoints de Child Address

​Soporte

Requisitos previos

Cómo funciona

Master Wallet vs Child Address

Endpoints

Retiro individual

Parámetros de la solicitud

Ejemplo de retiro individual

Respuesta del retiro individual

Memos en la cadena

Memos en Stellar

Memos en Solana

Direcciones de destinatario en Stellar

Cuentas muxed (`M...`)

Contratos Soroban (`C...`)

Retiros por lotes

Cuándo usar retiros por lotes

Parámetros de la solicitud por lotes

Ejemplo de retiro por lotes

Respuesta del retiro por lotes

Manejo de fallos parciales

Reglas de retiro por lotes

Estimación de comisiones de red

Estimación de comisión individual

Respuesta de comisión individual

Estimación de comisiones por lotes

Respuesta de comisión por lotes

Campos de la respuesta de comisión

Modo Sign-Only

Ejemplo de Sign-Only

Respuesta de Sign-Only

Retiros desde Child Address

Eventos de Webhook

Payload del Webhook

Ejemplo de flujo completo

Respuestas de error

Mejores prácticas

Seguridad

Gestión de comisiones

Manejo de errores

Rendimiento

Referencia API

Endpoints de Master Wallet

Endpoints de Child Address

Soporte