Tuo docs

Withdrawals

How to withdraw a Tuo position in two wallet calls, what happens in between, and the emergency exit that no one can block.

Withdrawal is two calls from the NFT owner's wallet. Tuo has no approval step and no veto. The vault gates the exit only on what it can measure: no open Hyperliquid lifecycle, which only the keeper's final return closes, so zero margin outstanding is not enough; on a 100% withdrawal, no open range, since it reverts LpsOutstanding while any is open; and enough idle USDC to pay the share you asked for.

Call 1: request

requestWithdraw(nftId, sharesBps) with the share in basis points, from 1 (0.01%) to 10,000 (100%). From that moment:

  • No new margin can be sent to Hyperliquid for the position.
  • Top-ups are blocked.
  • The keeper cannot mint a new range or swap the position's USDC into another token. It can still burn ranges and sell other tokens into USDC.
  • Tuo's exit chain starts. It authors an exit plan for the position within a minute and the keeper walks through it: burn every range, sell every priced balance back to USDC, then close the short and bring the margin home.
  • The 24-hour emergency clock starts.

Requesting again with a new share replaces the request and restarts the emergency clock. Requesting 0% cancels it.

Every share unwinds the whole position. A 10% request burns every range and closes the short exactly as a full exit does, because the hedge covers the ranges and closing part of either would leave the rest unhedged. After the payout, the remainder is idle USDC that the keeper redeploys. A partial withdrawal therefore costs the same swap spread as a full one.

Between the calls

The keeper's unwind order is fixed: ranges first, hedge last. The hedge covers the ranges, so closing it earlier would leave them exposed. When the short has closed, the margin comes back over the bridge and the vault credits the amount that actually arrived. The keeper's final return clears the position's outstanding margin and closes its Hyperliquid lifecycle, which is what makes the settlement value available again. A return that is not final never does, even when it repays all the margin that was sent: the hedge may have earned more than that, and the rest has to arrive before you can settle on it.

Under normal conditions the unwind completes within hours. It waits on the bridge's attestation, on the pool price staying within the vault's deviation gate, and on the keeper's action and loss budgets. The position page shows the withdrawal as ready when the vault's preview confirms the idle USDC covers your share; from then on the panel shows the vault's own figures, not an estimate.

If a small balance cannot be sold

The keeper sells each balance whole, so a sale leaves nothing behind. A balance that is priced but too small for the aggregator to route is the one case the keeper cannot clear by selling. The fix is a lift: the operator buys a small amount of the same token, at most 10 USDC, and the keeper sells the whole balance on its next pass. The vault applies its price floor and its keeper budgets to both swaps.

That purchase is a swap out of USDC, so the vault refuses it while a withdrawal request is armed. With a request armed, you have two ways out: take the emergency exit, or cancel the request, let the operator lift the balance, then request again. The emergency exit stays available throughout.

Call 2: withdraw

withdraw(nftId, withdrawalToken, minTokenOut, swapData). The vault:

  1. Checks that you own the NFT and a request exists. A 100% withdrawal also reverts LpsOutstanding here while any range is open.
  2. Computes the settlement value. While the Hyperliquid lifecycle is open, this reverts and the call fails cleanly; nothing moves. Only the keeper's final return closes the lifecycle.
  3. Computes the fee: 30% of the profit share being withdrawn, zero if there is no profit. See Performance fee.
  4. Checks that the position's idle USDC covers the gross amount. This check runs before the payout, so a shortfall stops the withdrawal whichever token you asked for. The keeper covers a shortfall by swapping idle WETH or WBTC to USDC through an allowlisted aggregator, so if the aggregator allowlist is ever empty, that conversion waits and so does the withdrawal. The emergency exit below needs no aggregator. A 100% request makes the gross the whole settlement value, so it settles only when every range is burned and every WETH or WBTC balance the vault prices above zero is converted completely into USDC. One priced unit left over stops the full exit. A 100% request also waits until every range is burned, even one worth zero at the average price. A WETH or WBTC balance too small to price is outside the settlement value: it does not block the full exit, and it is paid to you in kind, fee-free.
  5. Reduces the basis pro rata so a later withdrawal is measured against the right high-water mark.
  6. On a full exit, deactivates the position and burns the NFT before any payout.
  7. Pays you in USDC, or swaps to an allowlisted deposit token that the vault can price, through an allowlisted aggregator. For the swap, the vault imposes its own floor at the pool's average price less 0.5%, on top of the minimum you pass. A deposit token without a valuation pool is accepted on entry only: the vault cannot set a floor for its exit swap, so it refuses the swap. USDC is always available.

A partial withdrawal leaves the position active with the remaining share. The keeper redeploys it on the next engine cycle.

The emergency exit

emergencyWithdraw(nftId) is the door that always opens. Its properties:

PropertyDetail
Who can block itNo one. The pause affects deposits only, and no Tuo role can reach a deployed range
WhenImmediately if the position never sent margin to Hyperliquid, or if the keeper's final return has closed the hedge. Otherwise 24 hours after a withdrawal request, so the keeper has a window to bring the margin home the normal way
What it doesCloses every open range with no price floor and no deviation gate, so it works under any market condition, and pays every balance to you in kind: USDC, WETH, WBTC, whatever the position holds
Fee30% of the profit already certain, measured as on-chain value against the full basis at the pool's 30-minute average price, withheld in kind from each token. Profit that depends on the hedge result is charged as the hedge returns. If the pool price cannot be read, the fee is forgone rather than blocking the exit
Open hedgeBecomes a claim ticket on the position, whether or not any of the margin that was sent is still outstanding. The NFT is not burned. Whatever the hedge returns, above or below what was sent, the keeper routes it through the vault with settleHlClaim: the vault charges 30% of the profit realized so far, once, and pays the rest to the NFT owner, never to the keeper. A return never closes the claim. You close it with finalizeHlClaim, which writes off any margin that never came back and burns the NFT

The emergency exit closes ranges with no price protection. That is the price of a door that opens in any market: a bad price could not block it, so a bad price cannot be prevented either. It is exposed to sandwiching by design. The fee is measured against the pool's 30-minute average price while you are paid in the tokens themselves, so the amount withheld can be somewhat more or less than 30% of what the exit actually realizes. The protected path is the two-call withdrawal above. Use the emergency exit when the normal path has failed, not as a shortcut.

The claim ticket for outstanding margin is a ledger entry, not an escrow. If the keeper never settles it, the claim is not enforceable on-chain, and a hedge that lost money returns less than it was sent with no top-up from Tuo. You can always end the position yourself: finalizeHlClaim needs no keeper and no delay. This limitation is disclosed in the auditor note; see Custody model.

Transferring instead of withdrawing

The position NFT is a plain ERC-721. You can transfer it, and the new holder becomes the sole withdrawal authority. The only address refused as a recipient is the vault itself, which could not act on the position it holds. A pending withdrawal request travels with the position. This is also the escape for an owner whose address can no longer receive USDC: transfer the NFT to an address that can.

For integrators

  • Cancellation is WithdrawalRequested(nftId, 0); there is no separate cancel event.
  • There is no readiness flag. Derive "serviceable" from previewWithdraw(nftId) against idleBalance(nftId, USDC).
  • HlBridgeInboundCompleted carries the final-return flag. A projection that ignores it disagrees with the chain for the rest of the position's life. Only a final return closes the lifecycle (hlLifecycleOpen); settlementNav reverts until it does, whatever hlMarginBridged reads.
  • See Events and integration.

On this page