> ## Documentation Index
> Fetch the complete documentation index at: https://docs.killb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cotizaciones

> Comprendiendo precios, cotizaciones y tasas de cambio

## ¿Qué es una Cotización?

Una **Cotización** es una cotización de precio para convertir entre monedas. Bloquea una tasa de cambio por 30 segundos, permitiendo a los usuarios ver exactamente cuánto recibirán antes de comprometerse con una transacción.

<Info>
  Las cotizaciones son necesarias antes de crear cualquier ramp. Aseguran transparencia de precio y protección contra fluctuaciones de tasa.
</Info>

## Cómo Funcionan las Cotizaciones

<Steps>
  <Step title="Solicitar Cotización">
    Especifica monedas, monto y métodos de pago
  </Step>

  <Step title="Recibir Tasa">
    Obtén tasa bloqueada válida por 30 segundos
  </Step>

  <Step title="Mostrar al Usuario">
    Muestra montos exactos que el usuario enviará/recibirá
  </Step>

  <Step title="Crear Ramp">
    Usa el ID de la cotización para ejecutar transacción a la tasa cotizada
  </Step>
</Steps>

```mermaid theme={null}
sequenceDiagram
    participant User
    participant App
    participant KillB
    
    User->>App: Ingresar monto (100.000 COP)
    App->>KillB: POST /quotations
    KillB-->>App: Cotización (23,81 USDC, tasa 4.200)
    App-->>User: Mostrar: "Recibirás 23,81 USDC"
    User->>App: Confirmar
    App->>KillB: POST /ramps (con ID de cotización)
    KillB-->>App: Ramp creado
```

## Creando una Cotización

```bash theme={null}
POST /api/v2/quotations
```

**Solicitud:**

```json theme={null}
{
  "fromCurrency": "COP",
  "toCurrency": "USDC",
  "amount": 100000,
  "amountIsToCurrency": false,
  "cashInMethod": "PSE",
  "cashOutMethod": "POLYGON"
}
```

**Respuesta:**

```json theme={null}
{
  "id": "quot-9f8e7d6c-5b4a-3c2d-1e0f",
  "fromCurrency": "COP",
  "toCurrency": "USDC",
  "fromAmount": 100000,
  "toAmount": 23.81,
  "rate": 4200.50,
  "spotPrice": 4180.25,
  "expiresAt": 1704657630000,
  "cashInMethod": "PSE",
  "cashOutMethod": "POLYGON"
}
```

<CodeGroup>
  ```javascript Node.js theme={null}
  const getQuote = async (fromAmount, fromCurrency = 'COP', toCurrency = 'USDC') => {
    const response = await fetch('https://sandbox.killb.app/api/v2/quotations', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        fromCurrency,
        toCurrency,
        amount: fromAmount,
        amountIsToCurrency: false,
        cashInMethod: 'PSE',
        cashOutMethod: 'POLYGON'
      })
    });
    
    const quote = await response.json();
    console.log(`Tasa: ${quote.rate}, Recibes: ${quote.toAmount} ${toCurrency}`);
    return quote;
  };
  ```

  ```python Python theme={null}
  def get_quote(from_amount, from_currency='COP', to_currency='USDC', access_token):
      response = requests.post(
          'https://sandbox.killb.app/api/v2/quotations',
          headers={
              'Authorization': f'Bearer {access_token}',
              'Content-Type': 'application/json'
          },
          json={
              'fromCurrency': from_currency,
              'toCurrency': to_currency,
              'amount': from_amount,
              'amountIsToCurrency': False,
              'cashInMethod': 'PSE',
              'cashOutMethod': 'POLYGON'
          }
      )
      quote = response.json()
      print(f"Tasa: {quote['rate']}, Recibes: {quote['toAmount']} {to_currency}")
      return quote
  ```

  ```php PHP theme={null}
  <?php
  function getQuote($fromAmount, $fromCurrency = 'COP', $toCurrency = 'USDC', $token) {
      $ch = curl_init('https://sandbox.killb.app/api/v2/quotations');
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_POST, true);
      curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
          'fromCurrency' => $fromCurrency,
          'toCurrency' => $toCurrency,
          'amount' => $fromAmount,
          'amountIsToCurrency' => false,
          'cashInMethod' => 'PSE',
          'cashOutMethod' => 'POLYGON'
      ]));
      curl_setopt($ch, CURLOPT_HTTPHEADER, [
          'Content-Type: application/json',
          'Authorization: Bearer ' . $token
      ]);
      
      $response = curl_exec($ch);
      return json_decode($response, true);
  }
  ?>
  ```
</CodeGroup>

## Parámetros de la Cotización

### Dirección del Monto

El flag `amountIsToCurrency` determina qué monto es fijo:

<Tabs>
  <Tab title="Monto de Origen Fijo (false)">
    Usuario especifica **cuánto enviar**

    ```json theme={null}
    {
      "fromCurrency": "COP",
      "toCurrency": "USDC",
      "amount": 100000,
      "amountIsToCurrency": false
    }
    ```

    **Resultado:** "Envía 100.000 COP, recibe \~23,81 USDC"

    **Usar cuando:** Usuario quiere gastar monto exacto de fiat
  </Tab>

  <Tab title="Monto de Destino Fijo (true)">
    Usuario especifica **cuánto recibir**

    ```json theme={null}
    {
      "fromCurrency": "COP",
      "toCurrency": "USDC",
      "amount": 25,
      "amountIsToCurrency": true
    }
    ```

    **Resultado:** "Envía \~105.000 COP, recibe exactamente 25 USDC"

    **Usar cuando:** Usuario quiere recibir monto exacto de cripto
  </Tab>
</Tabs>

## Tasas de Cambio

### Componentes de la Tasa

```json theme={null}
{
  "rate": 4200.50,
  "spotPrice": 4180.25
}
```

**spotPrice**: Tasa de mercado de proveedores de liquidez\
**rate**: Tasa final incluyendo tarifas y margen de KillB

**Cálculo:**

```
toAmount = fromAmount / rate
Spread = rate - spotPrice
Fee % = (spread / spotPrice) * 100
```

### Factores de la Tasa

Las tasas de cambio están influenciadas por:

1. **Tasa de Mercado** - Precio actual de mercado
2. **Método de Pago** - Diferentes métodos tienen costos diferentes
3. **Volumen** - Transacciones más grandes pueden obtener mejores tasas
4. **Red** - Red blockchain afecta tarifas
5. **Tier del Cliente** - Precio negociado de tu cliente

<Tip>
  Las cuentas pre-fondeadas típicamente reciben mejores tasas debido a costos operacionales reducidos.
</Tip>

## Expiración de la Cotización

<Warning>
  **Las cotizaciones expiran después de 30 segundos** para proteger contra volatilidad del mercado.
</Warning>

### Manejando la Expiración

```javascript theme={null}
async function createRampWithRetry(quoteId, userId, accountId) {
  try {
    const ramp = await createRamp(quoteId, userId, accountId);
    return ramp;
  } catch (error) {
    if (error.message.includes('expired')) {
      // Obtener nueva cotización
      const newQuote = await getQuotation(/* params */);
      return await createRamp(newQuote.id, userId, accountId);
    }
    throw error;
  }
}
```

### Temporizador de Cuenta Regresiva

Muestra a los usuarios el tiempo restante:

```javascript theme={null}
function QuoteTimer({ expiresAt, onExpire }) {
  const [timeLeft, setTimeLeft] = useState(30);
  
  useEffect(() => {
    const interval = setInterval(() => {
      const remaining = Math.max(0, Math.floor((expiresAt - Date.now()) / 1000));
      setTimeLeft(remaining);
      
      if (remaining === 0) {
        onExpire();
      }
    }, 1000);
    
    return () => clearInterval(interval);
  }, [expiresAt]);
  
  return <div>Cotización expira en: {timeLeft}s</div>;
}
```

## Modo de Simulación

Prueba cotizaciones sin crear ramps:

```bash theme={null}
POST /api/v2/quotations/simulation
```

**Mismos parámetros que cotización regular, pero:**

* No se retorna ID de cotización
* Tasa es solo indicativa
* No se puede usar para crear ramp
* Sin expiración

**Usar para:**

* Mostrar tasas estimadas
* Funcionalidad de calculadora
* Visualización de tasa de mercado
* Educación del usuario

```javascript theme={null}
// Obtener cotización simulada para visualización
const simulatedQuote = await fetch('/api/v2/quotations/simulation', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    fromCurrency: 'COP',
    toCurrency: 'USDC',
    amount: userAmount,
    amountIsToCurrency: false,
    cashInMethod: 'PSE',
    cashOutMethod: 'POLYGON'
  })
}).then(r => r.json());

// Mostrar tasa al usuario
console.log(`Tasa estimada: ${simulatedQuote.rate}`);
console.log(`Recibirías: ${simulatedQuote.toAmount} USDC`);

// Cuando el usuario confirme, obtener cotización real
const realQuote = await getQuotation(/* mismos params */);
```

## Mejores Prácticas de Visualización de Tasa

<AccordionGroup>
  <Accordion title="Mostrar Todos los Montos" icon="calculator">
    ```javascript theme={null}
    Mostrar:
    - Monto de origen: "100.000 COP"
    - Monto de destino: "23,81 USDC"  
    - Tasa de cambio: "1 USDC = 4.200,50 COP"
    - Información de tarifa: "Incluye tarifa de 0,5%"
    ```
  </Accordion>

  <Accordion title="Temporizador de Cuenta Regresiva" icon="clock">
    ```javascript theme={null}
    "Esta tasa expira en 28 segundos"

    - Mostrar cuenta regresiva visual
    - Avisar en 10 segundos restantes
    - Auto-actualizar en expiración
    ```
  </Accordion>

  <Accordion title="Actualizaciones de Tasa" icon="arrows-rotate">
    ```javascript theme={null}
    // Auto-actualizar cotizaciones periódicamente
    setInterval(async () => {
      const newQuote = await getQuotation(amount);
      updateDisplay(newQuote);
    }, 5000); // Cada 5 segundos
    ```
  </Accordion>

  <Accordion title="Contexto de Mercado" icon="chart-line">
    ```javascript theme={null}
    Mostrar:
    - "Tasa: 1 USDC = 4.200,50 COP"
    - "Tasa de mercado: 4.180,25 COP"
    - "Spread: 0,48%"
    - "Última actualización: hace 2 segundos"
    ```
  </Accordion>
</AccordionGroup>

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Crear Cotizaciones" icon="calculator" href="/api-reference/endpoint/quotations-create">
    Referencia de la API para cotizaciones
  </Card>

  <Card title="Construir Ramps" icon="arrow-right-arrow-left" href="/es/concepts/ramps">
    Aprende cómo usar cotizaciones en ramps
  </Card>

  <Card title="Guía de Precios" icon="tag" href="/es/resources/best-practices">
    Mejores prácticas para mostrar tasas
  </Card>

  <Card title="Pares Soportados" icon="link" href="/es/supported-networks">
    Ver todos los pares de monedas disponibles
  </Card>
</CardGroup>