Conversion
Central onramp entity. Represents the operation from quote accept to on-chain settlement. State list.
The conversion is the central entity of the onramp. It exists from the quote accept and traverses the full lifecycle to either on-chain settlement or an alternative terminal outcome. It is the resource you read (GET /v1/conversions/:id) and act on (/cancel).
Why conversion is separate from quote
Quote and conversion answer different questions:
- Quote answers: "what is the rate now?". A frozen, disposable price with no side effect.
- Conversion answers: "what operation is in flight, in what state?". The executable operation, with Pix QR, window, limit reservation, and state machine.
Separating them keeps discarded quotes from polluting the history of real operations and keeps the state machine compact.
State diagram
States, one by one
| State | Meaning | What you are waiting for | Available actions |
|---|---|---|---|
awaiting_deposit | Conversion created, Pix QR issued, 15-minute window running | The end customer to pay the Pix | cancel |
funded | Pix payment confirmed within the window | On-chain settlement to advance automatically | (none) |
completed | USDT delivered to the destination address. Terminal | (terminal) | (none) |
failed | Irrecoverable error after funded. See failure_reason. Terminal | (terminal) | (none) |
expired | Window passed with no payment. Reserve released. Terminal | (terminal) | (none) |
canceled | You canceled in awaiting_deposit. Reserve released. Terminal | (terminal) | (none) |
Onramp has no standby
Unlike offramp, onramp has no standby, liquidated, or abandoned. Pix is atomic: either the exact amount is paid within the window, or it is not confirmed. No amount divergence to resolve.
Key fields
The conversion exposes (among others):
id,quote_id,status,transaction_type(pix_onramp).expected_source_amount(BRL expected),received_amount(BRL actually received).pix_qr_code,pix_tx_id,deposit_window_expires_at.destination_wallet_address,destination_wallet_network.- Execution fields populated after settlement: USDT transaction hash, timestamps,
failure_reason.
The complete field list lands in the API reference.
Webhooks per transition
| Transition | Event |
|---|---|
(creation) → awaiting_deposit | conversion.created |
funded → completed | conversion.completed |
funded → failed | conversion.failed |
awaiting_deposit → expired | conversion.expired |
awaiting_deposit → canceled | conversion.canceled |
There is no intermediate webhook for funded. The event of interest is the outcome (completed, failed, expired, canceled).
Next steps
- Per-user, per-type lock: the rule of one open conversion per end customer.
- Receiving the payment: what happens after the end customer pays.