Vault SDK
Make a managed vault another account scope in any terminal.
The public pre-1.0 vault SDK contains client code, API types, contract ABIs, Python support, MCP, and runnable examples—never executor keys, custody logic, infrastructure configuration, or signing policy. Discovery and public state are read-only; authenticated writes terminate at a vault-scoped gateway that validates policy and injects the mandatory builder immediately before a trade-only agent signs.
At a glance
- Markets
- HL + HIP-3/4 One vault-owned testnet account can expose validator, perp-deployer, and outcome markets.
- Clients
- TS + Python Both cover discovery, leader flows, bounded orders, managed TWAP, and data access.
- Automation
- REST + WS + MCP Delegated tokens are narrower than leader sessions and remain separate from x402 payment.
Why It Matters
What traders and researchers should take away
- A third-party terminal can reuse its normal ticket, private tables, and market data while changing only the explicit account scope.
- Followers can inspect public vaults and build contract deposit, claim, redemption, and withdrawal calls without receiving trading authority.
- Leaders can use manual wallet sessions, server bots, delegated agents, local MCP, WebSockets, batches, baskets, scaled orders, or managed TWAPs.
How it works
What the product uses behind the scenes
- Bootstrap from the terminal manifest so network, contracts, direct Hyperliquid reads, gateway, builder policy, and safety gates are not hard-coded.
- Use direct Hyperliquid subscriptions with the vault address for low-latency public state; route writes through the builder-enforcing gateway.
- Persist and reuse client_order_id after an ambiguous timeout; a new UUID represents a new order intent.
- Use separate credentials for vault execution, Omni keyed data, and x402 payments.
Notes
Things to know
- The SDK and platform are testnet preview software. Mainnet and public-money custody remain blocked pending reconciliation, recovery drills, and independent audit.
- The package is not yet published to npm; clone the public repository. Python is installed from its repository subdirectory.
- The current public testnet origin targets one configured executor; multi-vault routing remains a launch gate.
- Provisional points are not a token entitlement and remain subject to the published anti-Sybil policy.
Integrate another terminal
Keep personal and vault trading visually consistent but technically isolated.
- Discover vaults, performance, positions, open orders, and public trade history from the read client.
- Show Personal account or Vault 0x… as a persistent order-ticket and private-table scope.
- Exchange a wallet-signed, short-lived leader challenge and hold the vault session in memory only.
- Bind every account read, order, cancel, TWAP, and private table to the selected vault; never mix master-wallet state.
Choose a leader automation path
All write paths converge on the same policy and builder boundary.
git clone https://github.com/InTheta/hl-vault-sdk.git
cd hl-vault-sdk
npm install
npm run check
npm run example:one-click
npm run example:twap- Leader sessions support the full allowed policy; delegated agents carry explicit scopes, markets, notional, taker, and expiry limits.
- Run hl-vault-mcp locally with an opaque delegated token; MCP data payment never becomes execution authority.
- Use the external-terminal, simple-market, scaled, basket, liquidation-level, x402-gated, and emergency-cancel examples as focused recipes.
Add follower flows and Python services
Follower writes are wallet contract calls, not leader API calls.
cd hl-vault-sdk/python
python -m venv .venv
# Activate the virtual environment for your platform
python -m pip install -e ".[dev,evm]"
python -m pytest
python -m ruff check .
python -m mypy src- Build deposit, claim, redemption, and withdrawal transactions from the published contract ABIs.
- Treat testnet mock assets as having no monetary value.
- Use authoritative NAV and proof flags before displaying accounting as reconciled.
Builder fee and recovery boundary
The caller cannot omit, replace, or sign around the configured builder.
- Public order methods accept no builder override; the gateway removes untrusted signature, nonce, vault, and builder fields.
- Market-style orders are bounded IOC limits with an explicit reference and slippage cap; there is no unbounded market order.
- Cancel All signals managed TWAPs, reads authoritative open orders, cancels in bounded batches, and is idempotent when already clear.
- Funding, withdrawals, transfers, key management, builder changes, and unknown actions are outside the public trading interface.
References
Implementation references
HL Vault SDK
https://github.com/InTheta/hl-vault-sdkCanonical TypeScript, Python, OpenAPI, ABI, examples, and integration documentation.
External terminal guide
https://github.com/InTheta/hl-vault-sdk/blob/main/docs/INTEGRATION_GUIDE.mdAccount-scope, session, follower, execution, CORS, and release-gate integration contract.
API and agent guide
https://github.com/InTheta/hl-vault-sdk/blob/main/docs/API_AND_AGENT_TRADING.mdLeader tokens, delegation, MCP, order recipes, recovery, and data boundaries.
Python SDK
https://github.com/InTheta/hl-vault-sdk/tree/main/pythonTyped Python clients, signing examples, tests, and strategy recipes.