Cotação
Snapshot imutável da taxa USDT → BRL, válido por 5 minutos. Não compromete nada e não emite endereço de depósito.
Cotação (quote) é um snapshot de preço. Ela trava a taxa USDT → BRL no momento da criação por 5 minutos. Não cria conversão, não emite endereço de depósito, não reserva limite. Cotar é barato e descartável.
O que a cotação carrega
id: identificador estável da cotação.exchange_rate: a taxa snapshotada para o par USDT → BRL, considerando o modo de taxas configurado para sua organização (veja Modelo de taxas).source_amountetarget_amount: valores em USDT e BRL implicados pela taxa.expires_at: timestamp em que a cotação deixa de ser aceitável.
Os campos exatos da resposta vão na referência da API quando ela for publicada.
O que a cotação não faz
- Não emite endereço de depósito. O endereço só nasce quando você aceita a cotação. Veja Aceitando a cotação.
- Não reserva limite. A reserva acontece no aceite.
- Não bloqueia o cliente final. O lock por
(user_id, transaction_type)é criado na conversão, não na cotação. - Não pode ser modificada. Cotações são imutáveis. Se a taxa mudar antes do aceite, crie outra cotação.
TTL de 5 minutos
A janela curta é deliberada: a integração offramp é programática, e a cotação serve para capturar a taxa no instante imediatamente anterior ao aceite. Se a sua UX precisa de mais tempo entre obter a taxa e confirmar com o cliente final, o caminho correto é cotar de novo no momento do aceite, não estender a validade.
Não fique fazendo polling de cotações
Cotação é descartável. Crie uma quando precisar de uma taxa fresca para mostrar ao cliente final ou para aceitar imediatamente. Não consulte cotações em loop, não armazene cotação para reuso fora da janela de 5 minutos, e não trate cotação como recurso persistente.
Pré-requisitos para criar cotação
A cotação precisa de:
- Cliente final com KYC aprovado.
- Chave Pix do destinatário registrada no cliente final.
- Valor em USDT (
source_amount) ou em BRL (target_amount).
Sem esses três, a chamada falha com erro de validação. O catálogo de erros vai na referência da API quando publicada.
Cotação consumida
Quando você aceita uma cotação, ela transita para consumed e fica vinculada à conversão criada (campo consumed_by_conversion_id). Não dá para aceitar a mesma cotação duas vezes.
Há um caso especial: a liquidação manual de uma conversão em standby gera uma segunda cotação server-side, registrada como consumed e vinculada à conversão original via liquidation_quote_id. Essa cotação não passa pela sua mão e não tem TTL exposta. Detalhes em Standby e liquidação manual.
Próximos passos
- Conversão: para onde a cotação é levada quando você aceita.
- Criando uma cotação: o passo a passo da chamada.