Standby and manual liquidation
What triggers standby, what `/liquidate` does, why the rate changes, the 7-day window.
Standby is the most operationally important point of the offramp. It is the state in which the conversion is "stopped with money held", waiting for a decision from you. This page covers the reasons for standby, how to exit via /liquidate, and the abandoned outcome if you do not act within 7 days.
What triggers standby
Any of these scenarios puts the conversion in standby:
standby_reason | What happened |
|---|---|
under_funded | The on-chain deposit confirmed with received_amount < expected_source_amount. |
over_funded | The on-chain deposit confirmed with received_amount > expected_source_amount. |
window_expired | The 15-minute window passed with received_amount > 0 but still in awaiting_deposit. |
duplicate_deposit | More than one on-chain deposit was detected for the same conversion. |
wrong_address | A deposit arrived at an address that did not match the one issued for this conversion. |
late_post_window | A deposit landed after the window closed but was still accepted for resolution. |
In all three, the deposit is in BlendFi's custody and the conversion will not advance on its own. The policy is deliberate: any divergence requires an explicit decision from the partner, and the operation does not run automatically at an amount different from the contracted one.
What you see
conversion.standby webhook with payload containing standby_reason, received_amount, and expected_source_amount. The conversion in the response of GET /v1/conversions/:id shows status='standby', standby_at (when it entered), standby_expires_at (standby_at + 7 days).
The decision: liquidate or wait
You have three paths:
- Liquidate at the actually received amount via
POST /v1/conversions/:id/liquidate. BlendFi quotes a new rate server-side, executes settlement atreceived_amount, and the conversion ends incompleted(happy path) orfailed(execution error). - Do nothing for up to 7 days. The conversion stays in standby; late deposits keep being credited to
received_amountbut do not promote the conversion. After 7 days, it goes toabandoned(see Abandoned conversion). - Combine 1 and 2: hold while you evaluate, then liquidate any time within the 7-day window.
What /liquidate does
POST /v1/conversions/:id/liquidate is valid only in standby. The call, in a single transaction:
- Quotes a new rate server-side over the current
received_amount(not overexpected_source_amount). The new quote is recorded asquote(consumed)and referenced by the conversion vialiquidation_quote_id. - Adjusts the limit reservation to the actual operation amount.
- Creates the internal execution record and dispatches Pix settlement.
- Transitions the conversion to
liquidated(transient); the subsequent settlement leads tocompletedorfailed.
The response carries the conversion with liquidation_quote_id populated, status liquidated, and execution fields already in motion.
The `/liquidate` rate is new, not the original
The rate applied at manual liquidation is quoted at call time, not the original quote's exchange_rate. The end customer may receive a BRL value different from what was shown at accept, especially if the asset moved between accept and your decision to liquidate. Account for this in your UX.
Why the rate changes
The original quote was valid for 5 minutes at creation. The deposit window lasted 15 minutes from accept. When you liquidate in standby, the elapsed time may be hours or days. Applying the old rate would push market risk entirely onto BlendFi. The policy is symmetric: the partner who did not act inside the agreed window pays the rate at the moment of effective execution.
Common errors on /liquidate
- Conversion not in
standby: validation error. The operation is only accepted in standby. - Insufficient limit for the updated
received_amount: validation error. The adjusted reserve does not fit the end customer's current limit.
The full taxonomy lands in the API reference once published.
7-day TTL and abandoned
standby_expires_at = standby_at + 7 days. If you do not call /liquidate within that window, the conversion transitions to abandoned. Resolution of abandoned is manual and off-platform. See Abandoned conversion.
No reminder webhooks during the 7 days
BlendFi sends no reminder webhooks during the 7-day window. Tracking the deadline is your integration's responsibility. Consider a sweep over GET /v1/conversions?status=standby if the operation is sensitive to the window.
Reference coming soon
Detailed POST /v1/conversions/:id/liquidate documentation will appear here alongside API availability.
Next steps
- Cancellation: how to exit before any deposit arrives.
- Abandoned conversion: what happens after the 7 days.