Offramp - Vender Criptomoneda

Convierte criptomoneda a moneda fiat en tu cuenta virtual.

¿Qué es OFFRAMP?

OFFRAMP te permite vender criptomoneda y recibir fondos fiat en tu cuenta virtual.

Casos de uso:

Convertir tenencias cripto a fiat
Realizar ganancias cripto
Preparar fiat para operaciones
Aceptar pagos cripto y convertir a fiat

Ejemplo Rápido


// Vender 10 USDC por COP
 
// 1. Obtener cotización
const quote = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
  {
    type: 'OFFRAMP',
    originCurrencySymbol: 'USDC',
    destinationCurrencySymbol: 'COP',
    amountIn: 10,  // 10 USDC
    network: 'ETHEREUM'  // Requerido para cotizaciones cripto
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Recibirás:', quote.data.amountOut, 'COP'); // ej., 39,500 COP
console.log('Cotización válida por:', quote.data.validFor || '10-15', 'segundos');
 
// 2. Crear deal (¡no orden!)
const deal = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
  {
    type: 'OFFRAMP',
    destinationAccountId: 'va_cop_12345',  // Tu cuenta virtual COP
    quoteId: quote.data.id
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Deal OFFRAMP creado:', deal.id);
console.log('El deal debe pagarse completamente');
// Los fondos se acreditarán a la cuenta virtual COP después de confirmación

Integración Paso a Paso

Paso 1: Obtener Cotización


const quote = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
  {
    type: 'OFFRAMP',
    originCurrencySymbol: 'USDC',
    destinationCurrencySymbol: 'COP',
    amountIn: 10,
    network: 'ETHEREUM'  // Requerido para cotizaciones cripto
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
// Mostrar al usuario
console.log('Vendiendo:', quote.data.amountIn, 'USDC');
console.log('Recibirás:', quote.data.amountOut, 'COP');
console.log('Tasa de cambio:', quote.data.exchangeRate);
console.log('Comisión:', quote.data.koyweFee, 'COP');
console.log('Cotización válida por:', quote.data.validFor || '10-15', 'segundos');

Paso 2: Crear Deal OFFRAMP

Pago Completo Requerido: A diferencia de ONRAMP, los deals OFFRAMP deben financiarse completamente. No se soportan pagos parciales.


const deal = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
  {
    type: 'OFFRAMP',
    destinationAccountId: 'va_cop_12345',  // Solo necesitas cuenta de destino
    quoteId: quote.data.id,
    externalId: `offramp-${Date.now()}`
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Deal creado:', deal.data.id);
console.log('Estado:', deal.data.status); // "PENDING"
console.log('Dirección de depósito:', deal.data.cryptoDestinationWallet); // Dónde enviar cripto

Paso 3: Enviar Criptomoneda

Después de crear la orden, envía la criptomoneda a la dirección de depósito proporcionada:


const orderDetails = await axios.get(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders/${order.data.id}`,
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Enviar cripto a:', orderDetails.data.depositAddress);
console.log('Monto a enviar:', orderDetails.data.amountIn, orderDetails.data.originCurrencySymbol);
console.log('Red:', orderDetails.data.network);

Paso 4: Esperar Confirmación


app.post('/webhooks/koywe', (req, res) => {
  const event = JSON.parse(req.body);
  
  if (event.type === 'order.paid' && event.data.type === 'OFFRAMP') {
    console.log('¡Cripto recibida y confirmada!');
  }
  
  if (event.type === 'order.completed' && event.data.type === 'OFFRAMP') {
    console.log('¡Fiat acreditado a cuenta virtual!');
    console.log('Monto:', event.data.amountOut, event.data.destinationCurrencySymbol);
  }
  
  res.status(200).send('OK');
});

Flujo de Orden

Ejemplo Completo


async function sellUSDC(amount) {
  try {
    const token = await authenticate();
    
    // 1. Obtener cotización
    const quote = await axios.post(
      `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
      {
        type: 'OFFRAMP',
        originCurrencySymbol: 'USDC',
        destinationCurrencySymbol: 'COP',
        amountIn: amount,
        network: 'ETHEREUM'  // Requerido para cotizaciones cripto
      },
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    
    console.log(`Vendiendo ${amount} USDC por ${quote.data.amountOut} COP`);
    console.log(`Tasa: 1 USDC = ${quote.data.exchangeRate} COP`);
    console.log('Cotización válida por:', quote.data.validFor || '10-15', 'segundos');
    
    // 2. Crear deal (¡no orden!)
    const deal = await axios.post(
      `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
      {
        type: 'OFFRAMP',
        destinationAccountId: 'va_cop_12345',  // Solo necesitas cuenta de destino
        quoteId: quote.data.id
      },
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    
    console.log('✓ Deal OFFRAMP creado:', deal.data.id);
    console.log('📍 Enviar USDC a:', deal.data.cryptoDestinationWallet);
    console.log('💰 Monto:', deal.data.amountIn, 'USDC');
    console.log('🌐 Red:', deal.data.network || 'Ethereum');
    console.log('⚠️ Debe pagarse completamente - sin pagos parciales');
    
    return {
      dealId: deal.data.id,
      cryptoDestinationWallet: deal.data.cryptoDestinationWallet,
      amount: deal.data.amountIn,
      currency: deal.data.originCurrencySymbol
    };
    
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
    throw error;
  }
}
 
// Uso
const offramp = await sellUSDC(10);
console.log('Envía tu USDC a la dirección de depósito arriba');

Notas Importantes

Confirmaciones Blockchain: Las órdenes OFFRAMP requieren confirmaciones blockchain. El tiempo de liquidación varía por red:

Ethereum: 12-15 minutos (12 confirmaciones)
Polygon: 2-5 minutos (128 confirmaciones)
BSC: 3-5 minutos (15 confirmaciones)
Bitcoin: 30-60 minutos (3 confirmaciones)

Dirección de Uso Único: Cada orden OFFRAMP genera una dirección de depósito única. No reutilices direcciones de órdenes anteriores.

Próximos Pasos

₿Onramp - Comprar Cripto

Comprar criptomoneda con fiat

👛Cuentas Virtuales

Comprender gestión de saldo

🧪Pruebas

Probar operaciones cripto en sandbox

📖Referencia API

Documentación completa de API