Pular para o conteúdo principal

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

​
Como as Cotações Funcionam

1

Solicitar Cotação

Especifique moedas, valor e métodos de pagamento
2

Receber Taxa

Obtenha taxa bloqueada válida por 30 segundos
3

Mostrar ao Usuário

Exiba valores exatos que o usuário enviará/receberá
4

Criar Ramp

Use o ID da cotação para executar transação na taxa cotada

​
Criando uma Cotação

POST /api/v2/quotations
Requisição: 
{
  "fromCurrency": "COP",
  "toCurrency": "USDC",
  "amount": 100000,
  "amountIsToCurrency": false,
  "cashInMethod": "PSE",
  "cashOutMethod": "POLYGON"
}
Resposta: 
{
  "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"
}

const getQuote = async (fromAmount, fromCurrency = 'COP', toCurrency = 'USDC') => {
  const response = await fetch('https://teste-94u93qnn.uc.gateway.dev/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;
};

​
Parâmetros da Cotação

​
Direção do Valor

A flag amountIsToCurrency determina qual valor é fixo:
Usuário especifica quanto enviar
{
  "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

​
Taxas de Câmbio

​
Componentes da Taxa

{
  "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
Contas pré-financiadas normalmente recebem melhores taxas devido aos custos operacionais reduzidos.

​
Expiração da Cotação

Cotações expiram após 30 segundos para proteger contra volatilidade do mercado.

​
Lidando com Expiração

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: 
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: 
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
// 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

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%"

"Esta taxa expira em 28 segundos"

- Mostrar contagem regressiva visual
- Avisar em 10 segundos restantes
- Auto-atualizar na expiração

// Auto-atualizar cotações periodicamente
setInterval(async () => {
  const newQuote = await getQuotation(amount);
  updateDisplay(newQuote);
}, 5000); // A cada 5 segundos

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"

​
Próximos Passos

Criar Cotações

Referência da API para cotações

Construir Ramps

Aprenda como usar cotações em ramps

Guia de Preços

Melhores práticas para exibir taxas

Pares Suportados

Ver todos os pares de moedas disponíveis