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
JavaScript
// 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`,
{
orderType: 'OFFRAMP',
executable: true,
originCurrencySymbol: 'USDC',
destinationCurrencySymbol: 'COP',
amountIn: 10, // 10 USDC
network: 'ETHEREUM' // Requerido para ONRAMP/OFFRAMP
},
{ headers: { 'Authorization': `Bearer ${token}` } }
);
console.log('Recibirás:', quote.data.finalAmountOut, 'COP'); // ej., 39,500 COP
console.log('Cotización válida por:', quote.data.validForSeconds, 'segundos');
// 2. Crear deal (¡no orden!)
const deal = await axios.post(
`https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
{
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ónIntegración Paso a Paso
Paso 1: Obtener Cotización
JavaScript
const quote = await axios.post(
`https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
{
orderType: 'OFFRAMP',
executable: true,
originCurrencySymbol: 'USDC',
destinationCurrencySymbol: 'COP',
amountIn: 10,
network: 'ETHEREUM' // Requerido para ONRAMP/OFFRAMP
},
{ headers: { 'Authorization': `Bearer ${token}` } }
);
// Mostrar al usuario
console.log('Vendiendo:', quote.data.finalAmountIn, 'USDC');
console.log('Recibirás:', quote.data.finalAmountOut, 'COP');
console.log('Tasa de cambio:', quote.data.exchangeRate);
console.log('Comisión:', quote.data.fee, 'COP');
console.log('Cotización válida por:', quote.data.validForSeconds, 'segundos');Paso 2: Crear Deal OFFRAMP
Pago Completo Requerido: A diferencia de ONRAMP, los deals OFFRAMP deben financiarse completamente. No se soportan pagos parciales.
JavaScript
const deal = await axios.post(
`https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
{
destinationAccountId: 'va_cop_12345', // Solo necesitas cuenta de destino
quoteId: quote.data.id
},
{ 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 criptoPaso 3: Enviar Criptomoneda
Después de crear la orden, envía la criptomoneda a la dirección de depósito proporcionada:
JavaScript
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
JavaScript
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
Dibujando diagrama…
Ejemplo Completo
JavaScript
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`,
{
orderType: 'OFFRAMP',
executable: true,
originCurrencySymbol: 'USDC',
destinationCurrencySymbol: 'COP',
amountIn: amount,
network: 'ETHEREUM' // Requerido para ONRAMP/OFFRAMP
},
{ headers: { 'Authorization': `Bearer ${token}` } }
);
console.log(`Vendiendo ${amount} USDC por ${quote.data.finalAmountOut} COP`);
console.log(`Tasa: 1 USDC = ${quote.data.exchangeRate} COP`);
console.log('Cotización válida por:', quote.data.validForSeconds, 'segundos');
// 2. Crear deal (¡no orden!)
const deal = await axios.post(
`https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
{
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.