Onramp - Comprar Criptomoneda

Convierte moneda fiat a criptomoneda usando tu saldo virtual.

¿Qué es ONRAMP?

ONRAMP te permite comprar criptomoneda usando fondos fiat de tu cuenta virtual.

Criptomonedas soportadas: ver Redes Soportadas más abajo para los pares símbolo/red exactos que acepta la API.

Deals vs Órdenes

Importante: Las operaciones ONRAMP usan el endpoint /deals, no /orders. Un deal representa la intención de comprar cripto y puede pagarse completa o parcialmente. Cada pago crea una o más órdenes que ejecutan la compra.

Diferencias clave:

Deal: La intención de compra de cripto (puede financiarse parcialmente)
Orden: La ejecución real de la compra (creada automáticamente por el deal)
Pagos parciales: Puedes pagar un deal en múltiples cuotas para ONRAMP
Destino: Los deals solo necesitan la billetera/cuenta de destino

Ejecución Automática de Pagos

Saldo Requerido: Por defecto, necesitas saldo suficiente en tu cuenta virtual para cerrar un deal ONRAMP. Los pagos ONRAMP se ejecutan automáticamente cuando hay un crédito a tu saldo de moneda.

Cómo funciona:

Creas un deal ONRAMP por X cantidad de cripto
El deal requiere Y fiat en tu cuenta virtual
Cuando tu cuenta virtual recibe fondos (PAYIN, etc.), el deal se ejecuta automáticamente
Se crean órdenes y se compra el cripto

Comercios Pre-aprobados:

Algunos comercios pueden operar deals sin requerir saldo inicial
Esto permite crear deals antes de que los fondos estén disponibles
Contacta a Koywe para solicitar pre-aprobación de esta función

Ejemplo Rápido

JavaScript

// Comprar 10 USDC con COP
 
// 1. Obtener cotización
const quote = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
  {
    orderType: 'ONRAMP',
    executable: true,
    originCurrencySymbol: 'COP',
    destinationCurrencySymbol: 'USDC',
    amountIn: 50000,  // 50,000 COP
    network: 'ETHEREUM'  // Requerido para ONRAMP/OFFRAMP
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Recibirás:', quote.data.finalAmountOut, 'USDC'); // ej., 12.34 USDC
console.log('Comisión:', quote.data.fee, 'COP');
 
// 2. Crear deal (¡no orden!)
const deal = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
  {
    // Id de tu cuenta CRYPTO en K3 — no una dirección de billetera
    destinationAccountId: 'acc_77a80cf9-496c-4d72-9c33-fca3c8d5bcfe',
    quoteId: quote.data.id
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Deal ONRAMP creado:', deal.id);
console.log('El deal puede pagarse completa o parcialmente');

Integración Paso a Paso

Paso 1: Obtener tu Cuenta Cripto de Destino

Los deals ONRAMP entregan la cripto a una cuenta de K3 con kind: "CRYPTO". Lo que el deal necesita es el id de esa cuenta (acc_…), así que búscalo primero:

JavaScript

// Busca tu cuenta CRYPTO para la moneda y red en las que vas a comprar
const accounts = await axios.get(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/accounts/search`,
  {
    params: { kind: 'CRYPTO', currencySymbol: 'USDC', network: 'ETHEREUM' },
    headers: { 'Authorization': `Bearer ${token}` }
  }
);
 
const cryptoAccount = accounts.data[0];
 
if (!cryptoAccount) {
  throw new Error('No hay cuenta USDC en ETHEREUM — registra o provisiona una primero');
}
 
console.log('Id de cuenta de destino:', cryptoAccount.id);  // acc_… — esto es lo que recibe el deal
console.log('Dirección de billetera:', cryptoAccount.address);  // 0x… — solo informativo
console.log('Red:', cryptoAccount.network);

Pasa el id, no la dirección: destinationAccountId es un id de cuenta de K3 (acc_…). Una dirección de billetera (0x…) no es un valor válido.

¿Aún no tienes cuenta cripto? Registra tu propia billetera como cuenta cripto externa con POST /accounts y kind: "CRYPTO" — ver Cuentas Externas del Comercio. Las billeteras integradas gestionadas por Koywe se provisionan con passkey — ver Passkeys y Aprobaciones.

Paso 2: Verificar Saldo Fiat

JavaScript

const balances = await axios.get(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/accounts/balances`,
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
const copBalance = balances.data.find(b => b.currencySymbol === 'COP');
 
if (copBalance.availableBalance < 50000) {
  throw new Error('Saldo COP insuficiente');
}

Paso 3: Obtener Cotización

JavaScript

const quote = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
  {
    orderType: 'ONRAMP',
    executable: true,
    originCurrencySymbol: 'COP',
    destinationCurrencySymbol: 'USDC',
    amountIn: 50000,
    network: 'ETHEREUM'  // Requerido para ONRAMP/OFFRAMP
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
// Mostrar al usuario
console.log('Tasa de cambio:', quote.data.exchangeRate);
console.log('Recibirás:', quote.data.finalAmountOut, 'USDC');
console.log('Comisión:', quote.data.fee, 'COP');
console.log('Costo total:', quote.data.finalAmountIn, 'COP');
console.log('Cotización expira en:', quote.data.validForSeconds, 'segundos');

Paso 4: Crear Deal

Saldo Requerido: A menos que tu comercio esté pre-aprobado, necesitas saldo suficiente para cerrar el deal. El deal se ejecutará automáticamente cuando los fondos estén disponibles.

JavaScript

const deal = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
  {
    destinationAccountId: cryptoAccount.id,  // Solo necesitas destino (del Paso 1)
    quoteId: quote.data.id
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Deal creado:', deal.data.id);
console.log('Estado:', deal.data.status); // "PENDING"
console.log('Los deals pueden pagarse completa o parcialmente');

Qué sucede después: El deal creará órdenes automáticamente conforme se procesan los pagos. Puedes financiar el deal en un pago o múltiples pagos parciales.

Paso 5: Monitorear Deal y Órdenes

// Vía webhooks (recomendado)
app.post('/webhooks/koywe', (req, res) => {
  const event = JSON.parse(req.body);
  
  // Actualizaciones de estado del deal
  if (event.type === 'deal.completed' && event.data.type === 'ONRAMP') {
    console.log('¡Deal completado!');
    console.log('ID del Deal:', event.data.id);
  }
  
  // Órdenes creadas por el deal
  if (event.type === 'order.completed' && event.data.type === 'ONRAMP') {
    console.log('¡Cripto recibida!');
    console.log('ID de Orden:', event.data.id);
    console.log('Monto:', event.data.amountOut, event.data.destinationCurrencySymbol);
  }
  
  res.status(200).send('OK');
});

// O consultar estado del deal
async function checkDealStatus(dealId) {
  const deal = await axios.get(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals/${dealId}`,
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  
  console.log('Estado del deal:', deal.data.status);
  console.log('Órdenes creadas:', deal.data.orders); // Array de IDs de orden
  
  return deal.data;
}

Redes Soportadas

Red	Cadena	Monedas
`ETHEREUM`	Ethereum	`ETH` · `USDC` · `USDT`
`POLYGON`	Polygon	`MATIC` · `USDC` · `USDT`
`SOLANA`	Solana	`SOL` · `USDC` · `USDT`
`BASE`	Base	`ETH` · `USDC` · `USDT` · `EURC`
`ALGORAND`	Algorand	`USDC` · `USDT`
`TRON`	Tron	`TRX` · `USDT`
`BSC`	BNB Smart Chain	`USDT`
`BITCOIN`	Bitcoin	`BTC`

Solo estos pares son válidos. Cualquier otra combinación de símbolo y red es rechazada por la API.

Selección de Red: Pasa network en la cotización y asegúrate de que tu cuenta cripto de destino esté registrada en esa misma red.

Ejemplo Completo

JavaScript

async function buyUSDC(amount) {
  try {
    const token = await authenticate();
    
    // 1. Verificar saldo COP
    const balances = await getBalances(token, orgId, merchantId);
    const copBalance = balances.find(b => b.currencySymbol === 'COP');
    
    if (copBalance.availableBalance < amount) {
      throw new Error('Saldo COP insuficiente');
    }
    
    // 2. Buscar la cuenta CRYPTO que recibirá la cripto
    const accounts = await axios.get(
      `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/accounts/search`,
      {
        params: { kind: 'CRYPTO', currencySymbol: 'USDC', network: 'ETHEREUM' },
        headers: { 'Authorization': `Bearer ${token}` }
      }
    );
    const cryptoAccount = accounts.data[0];
    
    if (!cryptoAccount) {
      throw new Error('No hay cuenta USDC en ETHEREUM — registra o provisiona una primero');
    }
    
    // 3. Obtener cotización
    const quote = await axios.post(
      `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
      {
        orderType: 'ONRAMP',
        executable: true,
        originCurrencySymbol: 'COP',
        destinationCurrencySymbol: 'USDC',
        amountIn: amount,
        network: 'ETHEREUM'  // Requerido para ONRAMP/OFFRAMP
      },
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
 
    console.log(`Convirtiendo ${amount} COP a ${quote.data.finalAmountOut} USDC`);
    console.log(`Tasa: 1 USDC = ${quote.data.exchangeRate} COP`);
    console.log('Cotización válida por:', quote.data.validForSeconds, 'segundos');
 
    // 4. Crear deal (¡no orden!)
    const deal = await axios.post(
      `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
      {
        destinationAccountId: cryptoAccount.id,  // Id de cuenta, no la dirección
        quoteId: quote.data.id
      },
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    
    console.log('Deal ONRAMP creado:', deal.data.id);
    console.log('Se ejecutará automáticamente cuando haya saldo suficiente');
    
    return deal.data;
    
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
    throw error;
  }
}
 
// Uso
await buyUSDC(50000); // Comprar USDC con 50,000 COP

Próximos Pasos

Offramp - Vender Cripto

Vender criptomoneda por fiat

Órdenes y Tipos

Comprender tipos de orden cripto

Pruebas

Probar operaciones cripto en sandbox

Referencia API

Documentación completa de API