Skip to content

Docs

Torii Vault money reference#

Compact facts for an agent that explains, plans or checks how USDC enters and leaves a Torii Vault (standard Hyperliquid perps vault, contract MandateVaultV2, HyperEVM chain 999 mainnet / 998 test). The people's version with screens is Putting money in and taking it out. Amounts are USDC with 6 decimals. Shares have 12 decimals. No return is promised.

Places money can be#

Names inside one Hyperliquid account, the same on every screen and in every language: Crypto perps = Hyperliquid main perp dex (dex 0; deposits and withdrawals arrive here), Stock perps (xyz) = a HIP-3 dex such as xyz (the dex name stays in brackets because there can be more than one), Spot. Screens never show the bare word "Main"; the API and the code say main / dex 0.

StateWhereWho can move it out
hl_accountThe person's own Hyperliquid account: Crypto perps (dex 0), Stock perps (the xyz dex), SpotThe person, by signing a Hyperliquid action with their own wallet
wallet_evmThe person's own wallet on HyperEVM (same address as the Hyperliquid account)The person
vault_cashThe vault contract's USDC on HyperEVMThe settler (to Hyperliquid), depositors (by withdrawal)
vault_hlThe vault's own Hyperliquid account: Crypto perps, Stock perps (xyz), SpotThe settler (back to HyperEVM), the operator (between the vault's own markets only)
queuedShares locked in the withdrawal queueThe vault, when it prices and pays the request
claimableUSDC booked to a depositor whose payout transfer failedThe depositor (claim), or anyone for them (claimFor)

Transitions#

From toCallCallerSignaturesRules
Crypto perps to SpotHyperliquid usdClassTransfer (toPerp false)the person1Part of the bring flow
Stock perps (xyz) or another dex to SpotHyperliquid sendAsset (destinationDex spot, destination is the signer's own address)the person1 per dexPart of the bring flow
Spot to wallet_evmHyperliquid spotSend of USDC to the USDC system address 0x2000000000000000000000000000000000000000the person1At least 5 USDC. 0.02 USDC always stays (a send of the whole balance is dropped). The money arrives at the signer's own address.
wallet_evm to the vaultUSDC approve(vault, amount) then deposit(assets, receiver)the person2 (1 when the allowance already covers it)At least the vault's minimum deposit (never below 5 USDC). A new depositor pays the higher of the price now and the price mark, so shares are never more than the lower-price count. Refused until the owner commits, except the owner's own deposit. Allow-list only when publicDeposits is false.
Owner commitcommit()the vault owner only1The owner's whole free share balance must be worth at least minCommitValue. Capacity becomes committed value x 100 and does not shrink. A later commit must be higher. Locked in thirds per commitLockPeriod (0 = no lock).
vault_cash to vault_hlmoveToCore(amount)settler role only (house)by the houseNeeds committedValue > 0 (the house job also checks it). The first move of a vault is at most 5 USDC and must show on Hyperliquid's ledger before a larger one. A per-move cap and a smallest move are house settings. One move per 20 blocks. Hyperliquid account must exist.
Between the vault's marketsmoveBetweenDexes(from, to, amount), from the operate page POST /torii/vaults/{id}/prepare with action: move_dexesthe vault owner (signs from the owner's wallet)1from and to are spot or a dex the vault lists, and differ. At least 5 USDC unless the whole balance. Once every 10 minutes. Not toward a trading dex while the queue is short of cash. Settles in up to 20 blocks. Only a vault that lists both markets shows it.
vault_hl to vault_cashpullFromPerp, moveBetweenDexes to spot, then pullFromCoresettler role (house)by the houseNever the whole Spot balance (a fee stays behind). Smallest return is a house setting. After a request waited 3 days anyone may call pullForQueue (at most once per hour).
Withdrawal requestrequestWithdrawTo(shares, maxLots, 0)the depositor1Shares must be free (not queued, not locked by a commitment). Worth at least 5 USDC at value now, unless it takes every free share. At most 20 lots per request; a wallet with more deposits leaves in parts.
CancelcancelWithdraw(id)the depositor1Only while the request is unpriced.
Price and paysettleWithdrawals(maxRequests)anyone (the house settler sends it)by the callerStrict first in, first out. Priced at the lower of value now and the price mark. A mark is needed: with none the call takes one and pricing resumes 15 minutes later. Paid from vault_cash, partly if short. A failed payout is booked to claimable.
Claimclaim(to) or claimFor(depositor)the depositor, or anyone0 or 1Final.

Who may do what#

ActorMayMay not
Depositordeposit, request, cancel, claimmove vault money anywhere else
Operator (owner)commit, move money between the vault's own markets, change the asset list inside platform rules, place, cancel and close orders (or one delegated AI account may)send vault money to an outside address; run the settler
Attached AIplace, cancel and close orders inside the vault's ruleseverything else
House settlermoveToCore, pullFromPerp, pullFromCore, settleWithdrawals, claimFeesanything outside the vault's own functions
AnyonesettleWithdrawals, claimFees, claimFor, markPrice, pullForQueue after 3 days

Money leaves the vault only through a depositor's own withdrawal (fees accrued to the owner and the platform are paid by claimFees).

Settler timing#

State it as: usually within about 10 minutes; if the automatic run is paused it waits for the house. Do not state a fixed time. A return from Hyperliquid can take several runs because each move waits for the move window (20 blocks) and the ledger check.

Costs#

ItemWho chargesAmount
Hyperliquid send from an account (bring flow)Hyperliquidabout 0.008 USDC per send; the first send ever from an account also took a one-time 1 USDC fee plus about 0.0012 gas (observed 1.001179 USDC in total). Rule of thumb: leave about 1.01 USDC extra the first time.
Network fee on HyperEVMthe network, in HYPEsmall. A built-in Torii account tops up HYPE for a Cherry fee.
Deposit or withdrawal feethe vaultnone
Performance feethe vaultthe vault's own rate (10, 20 or 30 percent of gain above each deposit's high-water mark), taken in shares when a withdrawal is priced or at a month start. A fifth goes to the platform.
Torii trading feeToriion each trade, see terms.builder_fee
Hyperliquid trading fee and return feeHyperliquidseparate from Torii's; the return fee comes out of the vault's value

Refusals#

Code or textWhereMeaningFix
NotAllowlisteddepositallow-list vault, caller not listedask the owner to list the address
CapExceededdepositabove capacity (committed value x 100), or 0 before the owner commitsdeposit less, or wait for the commit
DepositTooSmalldepositbelow the vault minimumraise
PriceMarkPendingdeposit, settleprice mark too youngtry again after about 15 minutes
IsPaused, IsRetired, Breacheddeposit, owner callsvault stoppednone; withdrawals still work
CoreMoveSettling, MoveNotArriveddeposit, movesa move to or from Hyperliquid is settlingwait a minute
CoreReadFailed, PerpValueMissing, ForeignSpotHeld, RiskHolddeposit, pricea value read failed or a hold is onwait; requests still work
RequestTooSmallrequestworth under 5 USDC and not the whole free balanceraise, or take everything
SharesStillLockedrequestoperator commitment lockwait for the unlock date
CannotCancelcancelrequest already priced or cancellednone
CommitTooSmall, CommitNotHigher, CommitterMismatchcommitbelow minCommitValue, not higher than before, or another addressdeposit more, or sign with the first committing address
MoveTooSoon, DexMoveAmount, BadDexMove, QueueNeedsSpotmove moneyonce per 10 minutes; at least 5 USDC and not above the source; the ends must differ; the queue needs cashper the message
tw_vault_would_revert (HTTP 409)POST /torii/vaults/{vault_id}/preparethe contract would refuse it now; contract_error names the errorper the message
temporarily_unavailable (HTTP 503, scope chain)POST /torii/vaults/{vault_id}/preparethe vault could not be read on chain, also on the one retry the server makes (after a short pause, on the chain's public RPC when a custom one is set; never for a revert or a rule mismatch). Nothing was prepared or sentrepeat the same call after a moment. The screens say "The vault could not be read on chain just now, so nothing was prepared and nothing was sent. Try again in a moment." with a Try again button
tw_vault_mandate_refused (HTTP 403, rule)orderan order broke a vault rule; LeverageTooHigh is counted on the whole account and then on the order's own market account. The vault's leverage limit = the mandate's max leverage field (its current step, leverage.usable_x in the operator read; 3x below 1.30 x the start share price, one more x per compounding +30% step up to 10x, lowered at once below a step, raised at most once a day; leverage.reason / reason_text say why, next_step_at_price is the price the next step needs), or the operator's own lower whole-number setting (leverage.effective_x, capped_by "operator"); Hyperliquid's margin setting is separate and normally equalmove USDC to that market with move_dexes, or send less
tw_vault_margin_not_set (HTTP 409, margin_x)order (opening only)Torii could not set the vault's Hyperliquid margin setting for the asset to the vault's current leverage limit before the order, so it sent nothing. A closing (reduce-only) order is never held by thissend the same order again
tw_vault_leverage_setting_invalid (HTTP 422, choices, usable_x)POST /torii/vaults/{vault_id}/leverage-setting (operator only)the operator's own leverage setting must be a whole number from 1x up to the vault's current limit ("Choose a whole number between 1x and 3x."), or {"x": null} to clear itsend one of choices
Insufficient USDC or HYPE balance for token transfer gasHyperliquid, first send from an accountthe first-send fee is not coveredleave about 1.01 USDC extra

The full list of Torii refusal codes is in Refusals.

Reads#

  • GET /torii/vaults: public list. A vault whose owner has not committed is left out.
  • GET /torii/vaults/{vault_id}/terms: committed, capacity, remaining capacity, commitment_terms (min_commit_usdc, lock_seconds_per_third, house_vault), allowlist_only, dexes.
  • GET /torii/vaults/operated: the caller's own vaults, including an uncommitted one.
  • POST /torii/vaults/{vault_id}/prepare: calldata for commit, move_dexes and asset changes. Simulated as the owner; the owner's own wallet signs.
  • Never show a number that was not read as 0. Say "not read".