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.
| State | Where | Who can move it out |
|---|---|---|
hl_account | The person's own Hyperliquid account: Crypto perps (dex 0), Stock perps (the xyz dex), Spot | The person, by signing a Hyperliquid action with their own wallet |
wallet_evm | The person's own wallet on HyperEVM (same address as the Hyperliquid account) | The person |
vault_cash | The vault contract's USDC on HyperEVM | The settler (to Hyperliquid), depositors (by withdrawal) |
vault_hl | The vault's own Hyperliquid account: Crypto perps, Stock perps (xyz), Spot | The settler (back to HyperEVM), the operator (between the vault's own markets only) |
queued | Shares locked in the withdrawal queue | The vault, when it prices and pays the request |
claimable | USDC booked to a depositor whose payout transfer failed | The depositor (claim), or anyone for them (claimFor) |
Transitions#
| From to | Call | Caller | Signatures | Rules |
|---|---|---|---|---|
| Crypto perps to Spot | Hyperliquid usdClassTransfer (toPerp false) | the person | 1 | Part of the bring flow |
Stock perps (xyz) or another dex to Spot | Hyperliquid sendAsset (destinationDex spot, destination is the signer's own address) | the person | 1 per dex | Part of the bring flow |
Spot to wallet_evm | Hyperliquid spotSend of USDC to the USDC system address 0x2000000000000000000000000000000000000000 | the person | 1 | At 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 vault | USDC approve(vault, amount) then deposit(assets, receiver) | the person | 2 (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 commit | commit() | the vault owner only | 1 | The 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_hl | moveToCore(amount) | settler role only (house) | by the house | Needs 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 markets | moveBetweenDexes(from, to, amount), from the operate page POST /torii/vaults/{id}/prepare with action: move_dexes | the vault owner (signs from the owner's wallet) | 1 | from 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_cash | pullFromPerp, moveBetweenDexes to spot, then pullFromCore | settler role (house) | by the house | Never 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 request | requestWithdrawTo(shares, maxLots, 0) | the depositor | 1 | Shares 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. |
| Cancel | cancelWithdraw(id) | the depositor | 1 | Only while the request is unpriced. |
| Price and pay | settleWithdrawals(maxRequests) | anyone (the house settler sends it) | by the caller | Strict 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. |
| Claim | claim(to) or claimFor(depositor) | the depositor, or anyone | 0 or 1 | Final. |
Who may do what#
| Actor | May | May not |
|---|---|---|
| Depositor | deposit, request, cancel, claim | move 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 AI | place, cancel and close orders inside the vault's rules | everything else |
| House settler | moveToCore, pullFromPerp, pullFromCore, settleWithdrawals, claimFees | anything outside the vault's own functions |
| Anyone | settleWithdrawals, 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#
| Item | Who charges | Amount |
|---|---|---|
| Hyperliquid send from an account (bring flow) | Hyperliquid | about 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 HyperEVM | the network, in HYPE | small. A built-in Torii account tops up HYPE for a Cherry fee. |
| Deposit or withdrawal fee | the vault | none |
| Performance fee | the vault | the 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 fee | Torii | on each trade, see terms.builder_fee |
| Hyperliquid trading fee and return fee | Hyperliquid | separate from Torii's; the return fee comes out of the vault's value |
Refusals#
| Code or text | Where | Meaning | Fix |
|---|---|---|---|
NotAllowlisted | deposit | allow-list vault, caller not listed | ask the owner to list the address |
CapExceeded | deposit | above capacity (committed value x 100), or 0 before the owner commits | deposit less, or wait for the commit |
DepositTooSmall | deposit | below the vault minimum | raise |
PriceMarkPending | deposit, settle | price mark too young | try again after about 15 minutes |
IsPaused, IsRetired, Breached | deposit, owner calls | vault stopped | none; withdrawals still work |
CoreMoveSettling, MoveNotArrived | deposit, moves | a move to or from Hyperliquid is settling | wait a minute |
CoreReadFailed, PerpValueMissing, ForeignSpotHeld, RiskHold | deposit, price | a value read failed or a hold is on | wait; requests still work |
RequestTooSmall | request | worth under 5 USDC and not the whole free balance | raise, or take everything |
SharesStillLocked | request | operator commitment lock | wait for the unlock date |
CannotCancel | cancel | request already priced or cancelled | none |
CommitTooSmall, CommitNotHigher, CommitterMismatch | commit | below minCommitValue, not higher than before, or another address | deposit more, or sign with the first committing address |
MoveTooSoon, DexMoveAmount, BadDexMove, QueueNeedsSpot | move money | once per 10 minutes; at least 5 USDC and not above the source; the ends must differ; the queue needs cash | per the message |
tw_vault_would_revert (HTTP 409) | POST /torii/vaults/{vault_id}/prepare | the contract would refuse it now; contract_error names the error | per the message |
temporarily_unavailable (HTTP 503, scope chain) | POST /torii/vaults/{vault_id}/prepare | the 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 sent | repeat 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) | order | an 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 equal | move 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 this | send 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 it | send one of choices |
Insufficient USDC or HYPE balance for token transfer gas | Hyperliquid, first send from an account | the first-send fee is not covered | leave 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 forcommit,move_dexesand 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".