Hyperliquid Agent Wallet: Non-Custodial Bots Explained

What a Hyperliquid agent wallet (API wallet) can and cannot do, how nonces and expiry work, and how Trigr runs agents without taking custody of funds.

Trigr Research6 min read
On this page
  1. What is a Hyperliquid agent wallet?
  2. What can an agent wallet do, and what can't it?
  3. How do nonces, expiry and pruning work?
  4. How does Trigr use agent wallets?
  5. What else protects your account?
  6. How does this compare with other ways to automate?
  7. Revoking and rotating keys
  8. Next steps

TL;DR: A Hyperliquid agent wallet (API wallet) is a secondary key your master wallet authorizes to trade on your account. It can place and cancel orders but cannot withdraw or send USDC, because Hyperliquid requires the master wallet to sign those actions. Trigr's autonomous agents use such a trade-only key, stored encrypted server-side, while you keep the master key and custody of funds.

What is a Hyperliquid agent wallet?

Every Hyperliquid account is controlled by a master wallet, the key that deposited the funds. Signing each order with that key is impractical for automation: a bot would need your most sensitive key sitting on a server.

Hyperliquid solves this with API wallets, also called agent wallets. You sign one approveAgent message with the master wallet, naming a new address. From then on, actions signed by that new key are accepted as if they came from your account, within a limited scope. Hyperliquid's nonces and API wallets documentation describes the mechanics.

One detail trips up many builders: the agent key signs on behalf of the account, but it does not have its own balance or positions. To read account data you query the master account (or subaccount) address, not the agent's address.

What can an agent wallet do, and what can't it?

The line is drawn by signature type. Hyperliquid's exchange endpoint reference marks certain actions as user-signed, which means the master wallet must sign them. Approving an agent, withdrawing and sending USDC all fall in that group.

Action Agent (API) wallet Master wallet
Place and cancel orders Yes Yes
Modify TP/SL orders Yes Yes
Approve a new agent No Yes
Approve a builder fee No Yes
Withdraw No Yes
Send USDC to another address No Yes

That table is the core of the non-custodial claim. A trade-only key cannot withdraw or send funds to another address. It can, however, trade them. A leaked agent key could open poor positions or close good ones, so "cannot withdraw" is not the same as "harmless." Good practice still applies: keep keys encrypted, rotate them, and revoke any you no longer use.

How do nonces, expiry and pruning work?

Hyperliquid does not use a simple incrementing nonce like Ethereum. Per its documentation, it stores the 100 highest nonces for each signer, and a new action must use a nonce larger than the smallest stored one and never used before. Nonces must also fall within a window around the block time, roughly two days behind to one day ahead.

Nonces are tracked per signer. If several processes trade through one account, giving each its own agent key avoids nonce collisions, which is why Hyperliquid allows multiple API wallets per account.

Agent approvals can also be pruned. Hyperliquid lists three cases: the agent is deregistered (for example, a new approval replaces it under the same name), it expires, or the account that registered it no longer has funds. The docs add an important warning: once an agent is deregistered, its used-nonce state may be pruned, so previously signed actions could become replayable. Do not reuse an old agent address after deregistering it; generate a fresh key instead.

Approvals can carry an expiry. Per the exchange endpoint reference, a custom expiration can be set at most 180 days in the future. Shorter expiries limit how long a leaked key stays useful.

In practice this means an automation setup should answer three questions up front: which process owns which key, when each key expires, and what happens to in-flight orders when a key is replaced. A bot that silently loses its approval does not crash; it simply stops getting orders accepted, which is worse if it was holding a position it meant to close.

How does Trigr use agent wallets?

Trigr uses two kinds of trade-only keys, for two different jobs.

Manual trading keys, per device

When you trade by hand in Trigr's trade page or terminal, a session key is generated locally in your browser. You approve it once with an EIP-712 signature, and it is encrypted on that device under a signature only your master wallet can produce. The key is valid for 180 days from approval, after which Trigr prompts you to rotate it. Opening Trigr on another browser starts a fresh approval for that device.

Autonomous agent key, per wallet

A trading agent has to act when your laptop is closed. For that, Trigr generates a separate trade-only key for your wallet and stores it encrypted at rest in its execution vault. Key facts:

  • It is valid for about 90 days, then you re-approve with one signature.
  • It cannot withdraw funds or send them to another address.
  • It can sign two account-management actions on your behalf: creating a subaccount and moving USDC between your own main account and subaccounts. Funds only ever move between accounts you own.
  • Reconnecting replaces the previous autonomous key.
  • One autonomous key is active per wallet; several compatible agents can use it on their assigned accounts.
  • Trigr checks Hyperliquid's list of approved agents when it loads the agent. If the key has been overwritten from another device, the agent pauses in a "needs reconnect" state.

This is a real trade-off and it is worth stating plainly. Trigr does hold the autonomous trade-only key, because an always-on agent cannot work otherwise. What Trigr never holds is your master wallet key, and the funds stay in your own Hyperliquid account.

What else protects your account?

The agent key's limits are the first layer. Trigr adds operational rails on top:

  • Reduce-only protection. When a strategy defines take-profit and stop-loss levels, each entry ships with reduce-only exit orders, and failed placements are retried about once a minute.
  • Reconciliation. Each agent is checked against Hyperliquid's real account state every 10 minutes while it holds positions, and realized P&L comes from Hyperliquid fills.
  • Exclusive-account fence. Assigning an agent reserves that exact account for Trigr execution. If Trigr detects external trading on it, it safety-pauses every bound agent, blocks new entries and emails you, while verified exits and reconciliation continue.
  • Builder-fee cap. You approve a maximum builder fee once; Trigr charges up to 0.05% per trade, collected by Hyperliquid.

For stronger isolation, Hyperliquid lets accounts with at least $100,000 of volume create subaccounts. A dedicated subaccount for your agents keeps their margin separate from anything else you hold and removes the chance of a manual order racing an agent order. Note that different markets inside one account still share margin; Hyperliquid's margining documentation explains cross and isolated margin.

How does this compare with other ways to automate?

Approach Where the key lives Can it withdraw? Always on?
Master key on a server Your server Yes Yes
Your own script with an API wallet Your server No If you keep it running
Browser session key (manual trading) Your browser, encrypted No Only while open
Trigr autonomous agent Trigr execution vault, encrypted No Yes

Running your own script with an API wallet gives you full control of the key, at the cost of hosting, monitoring and reconciliation work. Putting a master key on any server is the one setup to avoid entirely.

The same principle, least privilege, shapes Trigr's AI integration. An assistant connected over MCP can backtest and create paused paper agents, but cannot start execution, place live trades or withdraw. The reasoning is covered in AI trading agent safety and approvals.

Revoking and rotating keys

Treat agent keys as something you rotate, not set and forget:

  1. Pause every agent bound to the account and let managed positions settle.
  2. Revoke or replace the approval from your master wallet.
  3. Reconnect in Trigr when you want to resume; a fresh key is generated.

Disconnecting a key does not by itself release an account assignment in Trigr, so move or delete agents assigned to an account before you trade it manually. The live trading documentation lists the exact steps.

Trade-only keys reduce custody risk; they do not reduce market risk. Perpetual futures are leveraged and can lose more than you expect, whoever signs the orders.

Next steps

Walk through the full Connect Hyperliquid guide, then follow deploying a strategy as a Hyperliquid agent from backtest to live. If you are still testing, a paper trading agent needs no keys at all.

Frequently asked questions

What is a Hyperliquid agent wallet?

An agent wallet, which Hyperliquid also calls an API wallet, is a separate key that your master wallet approves to sign trading actions on your account. It can place and cancel orders, but withdrawals and USDC sends are user-signed actions that need the master wallet.

Can a Hyperliquid API wallet withdraw funds?

No. Hyperliquid classifies withdrawals and USDC transfers to other addresses as user-signed actions, so they require the master wallet's signature. An agent key that leaks can still open or close trades on the account, though, so it should be treated as sensitive.

Does Trigr hold my keys?

Trigr never holds your master wallet key. For autonomous agents that keep trading while your browser is closed, Trigr stores the trade-only agent key encrypted server-side. That key cannot withdraw or send funds to another address, expires after about 90 days, and can be revoked from your master wallet.

How long does a Hyperliquid agent approval last?

Hyperliquid lets an agent approval carry an expiry of up to 180 days. Trigr's autonomous agent key is valid for about 90 days, after which you re-approve it with one signature.

Put the idea to an honest test.

Describe a strategy in plain English or from your own AI assistant, backtest it on point-in-time data, and forward-test it on paper before any real money is involved.