OnrampConcepts
Overview
Mental model of the onramp in three entities. End customer pays via Pix, receives USDT on-chain.
Onramp is the operation that converts BRL to USDT and delivers the USDT on-chain to a destination wallet. The mental model has three entities.
In three sentences
- You obtain a quote for the current BRL → USDT rate.
- You accept the quote and create a conversion, which gets a Pix QR.
- The end customer pays the QR and BlendFi settles USDT on-chain to the destination address.
The conversion is the central entity. It represents the full operation, from rate acceptance to on-chain settlement, and is the resource you read and act on throughout the rest of the integration.
The lifecycle in three steps
1. POST /v1/quotes → quote valid for 15 minutes
2. POST /v1/quotes/:id/accept → creates the conversion, issues the Pix QR; 15-minute window
3. end customer pays the QR → automatic on-chain USDT settlement; webhook announces the outcomeIf the end customer pays within the window, the conversion proceeds straight to completed with no further action on your side. If the window expires without payment, the conversion ends in expired.
Term conventions
Recurring vocabulary in this section. Identifiers in backticks are API field names and are never translated.
| Prose term | Meaning | Identifier |
|---|---|---|
| quote | Immutable rate snapshot | quote, quote_id |
| conversion | Partner-visible operation, from accept to settlement | conversion, conversion_id |
| paid | Conversion that received Pix payment within the window | status funded |
| Pix QR | Code generated at quote accept | pix_qr_code, pix_tx_id |
| destination address | On-chain wallet that receives USDT | destination_wallet_address |
Next steps
- Quote: what a quote carries and what it does not do.
- Conversion: the central entity and its states.
- Per-user, per-type lock: the rule of one open conversion per end customer.
- Build a PIX → USDT checkout: runnable step-by-step.