> ## 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.

# Cotações

> Entendendo preços, cotações e taxas de câmbio

## O que é uma Cotação?

Uma **Cotação** é uma cotação de preço para conversão entre moedas. Ela bloqueia uma taxa de câmbio por 30 segundos, permitindo que os usuários vejam exatamente quanto receberão antes de se comprometer com uma transação.

<Info>
  Cotações são necessárias antes de criar qualquer ramp. Elas garantem transparência de preço e proteção contra flutuações de taxa.
</Info>

## Como as Cotações Funcionam

<Steps>
  <Step title="Solicitar Cotação">
    Especifique moedas, valor e métodos de pagamento
  </Step>

  <Step title="Receber Taxa">
    Obtenha taxa bloqueada válida por 30 segundos
  </Step>

  <Step title="Mostrar ao Usuário">
    Exiba valores exatos que o usuário enviará/receberá
  </Step>

  <Step title="Criar Ramp">
    Use o ID da cotação para executar transação na taxa cotada
  </Step>
</Steps>

```mermaid theme={null}
sequenceDiagram
    participant User
    participant App
    participant KillB
    
    User->>App: Inserir valor (100.000 COP)
    App->>KillB: POST /quotations
    KillB-->>App: Cotação (23,81 USDC, taxa 4.200)
    App-->>User: Mostrar: "Você receberá 23,81 USDC"
    User->>App: Confirmar
    App->>KillB: POST /ramps (com ID da cotação)
    KillB-->>App: Ramp criado
```

## Criando uma Cotação

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

**Requisição:**

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

**Resposta:**

```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(`Taxa: ${quote.rate}, Você recebe: ${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"Taxa: {quote['rate']}, Você recebe: {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 da Cotação

### Direção do Valor

A flag `amountIsToCurrency` determina qual valor é fixo:

<Tabs>
  <Tab title="Valor de Origem Fixo (false)">
    Usuário especifica **quanto enviar**

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

    **Resultado:** "Envie 100.000 COP, receba \~23,81 USDC"

    **Use quando:** Usuário quer gastar valor exato de fiat
  </Tab>

  <Tab title="Valor de Destino Fixo (true)">
    Usuário especifica **quanto receber**

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

    **Resultado:** "Envie \~105.000 COP, receba exatamente 25 USDC"

    **Use quando:** Usuário quer receber valor exato de cripto
  </Tab>
</Tabs>

## Taxas de Câmbio

### Componentes da Taxa

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

**spotPrice**: Taxa de mercado dos provedores de liquidez\
**rate**: Taxa final incluindo taxas e margem da KillB

**Cálculo:**

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

### Fatores da Taxa

As taxas de câmbio são influenciadas por:

1. **Taxa de Mercado** - Preço atual de mercado
2. **Método de Pagamento** - Diferentes métodos têm custos diferentes
3. **Volume** - Transações maiores podem obter melhores taxas
4. **Rede** - Rede blockchain afeta taxas
5. **Tier do Cliente** - Preço negociado do seu cliente

<Tip>
  Contas pré-financiadas normalmente recebem melhores taxas devido aos custos operacionais reduzidos.
</Tip>

## Expiração da Cotação

<Warning>
  **Cotações expiram após 30 segundos** para proteger contra volatilidade do mercado.
</Warning>

### Lidando com Expiração

```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')) {
      // Obter nova cotação
      const newQuote = await getQuotation(/* params */);
      return await createRamp(newQuote.id, userId, accountId);
    }
    throw error;
  }
}
```

### Temporizador de Contagem Regressiva

Mostre aos usuários o tempo 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>Cotação expira em: {timeLeft}s</div>;
}
```

## Modo de Simulação

Teste cotações sem criar ramps:

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

**Mesmos parâmetros que cotação regular, mas:**

* Nenhum ID de cotação retornado
* Taxa é apenas indicativa
* Não pode ser usada para criar ramp
* Sem expiração

**Use para:**

* Mostrar taxas estimadas
* Funcionalidade de calculadora
* Exibição de taxa de mercado
* Educação do usuário

```javascript theme={null}
// Obter cotação simulada para exibição
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 taxa ao usuário
console.log(`Taxa estimada: ${simulatedQuote.rate}`);
console.log(`Você receberia: ${simulatedQuote.toAmount} USDC`);

// Quando o usuário confirmar, obter cotação real
const realQuote = await getQuotation(/* mesmos params */);
```

## Melhores Práticas de Exibição de Taxa

<AccordionGroup>
  <Accordion title="Mostrar Todos os Valores" icon="calculator">
    ```javascript theme={null}
    Exibir:
    - Valor de origem: "100.000 COP"
    - Valor de destino: "23,81 USDC"  
    - Taxa de câmbio: "1 USDC = 4.200,50 COP"
    - Informação de taxa: "Inclui taxa de 0,5%"
    ```
  </Accordion>

  <Accordion title="Temporizador de Contagem Regressiva" icon="clock">
    ```javascript theme={null}
    "Esta taxa expira em 28 segundos"

    - Mostrar contagem regressiva visual
    - Avisar em 10 segundos restantes
    - Auto-atualizar na expiração
    ```
  </Accordion>

  <Accordion title="Atualizações de Taxa" icon="arrows-rotate">
    ```javascript theme={null}
    // Auto-atualizar cotações periodicamente
    setInterval(async () => {
      const newQuote = await getQuotation(amount);
      updateDisplay(newQuote);
    }, 5000); // A cada 5 segundos
    ```
  </Accordion>

  <Accordion title="Contexto de Mercado" icon="chart-line">
    ```javascript theme={null}
    Mostrar:
    - "Taxa: 1 USDC = 4.200,50 COP"
    - "Taxa de mercado: 4.180,25 COP"
    - "Spread: 0,48%"
    - "Última atualização: 2 segundos atrás"
    ```
  </Accordion>
</AccordionGroup>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Criar Cotações" icon="calculator" href="/api-reference/endpoint/quotations-create">
    Referência da API para cotações
  </Card>

  <Card title="Construir Ramps" icon="arrow-right-arrow-left" href="/pt/concepts/ramps">
    Aprenda como usar cotações em ramps
  </Card>

  <Card title="Guia de Preços" icon="tag" href="/pt/resources/best-practices">
    Melhores práticas para exibir taxas
  </Card>

  <Card title="Pares Suportados" icon="link" href="/pt/supported-networks">
    Ver todos os pares de moedas disponíveis
  </Card>
</CardGroup>