OnrampConceitos
Visão geral
Modelo mental do onramp em três entidades. O cliente final paga via Pix, recebe USDT on-chain.
Onramp é a operação que converte BRL em USDT e entrega o USDT on-chain a uma carteira de destino. O modelo mental tem três entidades.
Em três frases
- Você obtém uma cotação (
quote) para a taxa BRL → USDT no momento. - Você aceita a cotação e cria uma conversão (
conversion), que recebe um QR Pix. - O cliente final paga o QR e a BlendFi liquida USDT on-chain no endereço de destino.
A conversão é a entidade central. Ela representa a operação completa, do aceite da taxa até a liquidação on-chain, e é o recurso que você lê e aciona no resto da integração.
O ciclo em três passos
1. POST /v1/quotes → cotação válida por 15 minutos
2. POST /v1/quotes/:id/accept → cria a conversão, emite o QR Pix; janela de 15 minutos
3. cliente final paga o QR → liquidação automática em USDT on-chain; webhook anuncia o desfechoSe o cliente final paga dentro da janela, a conversão segue direto para completed sem ação adicional sua. Se a janela expira sem pagamento, a conversão termina em expired.
Convenções de termo
Vocabulário recorrente nesta seção. Identificadores entre crases são nomes de campo da API e nunca traduzem.
| Termo na prosa | Significado | Identificador |
|---|---|---|
| cotação | Snapshot imutável de taxa | quote, quote_id |
| conversão | Operação visível ao parceiro, do aceite até a liquidação | conversion, conversion_id |
| pago | Conversão que recebeu o pagamento Pix dentro da janela | status funded |
| QR Pix | Código gerado no aceite da cotação | pix_qr_code, pix_tx_id |
| endereço de destino | Carteira on-chain que recebe USDT | destination_wallet_address |
Próximos passos
- Cotação: o que uma cotação carrega e o que ela não faz.
- Conversão: a entidade central e seus estados.
- Lock por usuário e tipo: a regra de uma conversão aberta por cliente final.
- Implemente um onramp Pix → USDT: passo a passo executável.