agentic

# Locker Protocol Agentic

**Your private key is nowhere: not on our servers, not on the agent's machine, not with anyone.**

The agent trades. It holds nothing.

- **Where the key is:** the account's private key stays in Locker Vault, an offline app on a phone or tablet. This computer only holds an agent key, sealed under a password, that expires on its own (six months by default, the longest Hyperliquid allows).
- **Who can withdraw:** only the vault, by a QR code a person scans and signs. Hyperliquid refuses the agent key every withdrawal and every send; the one movement of funds it accepts from that key is a deposit into a Hyperliquid vault, which lpa never signs (measured on mainnet, 2026-09-28).
- **What goes where:** orders and reads go to Hyperliquid, deposits and balances to Arbitrum nodes, and nothing else unless you turn it on (the list is below). No server of ours, no account, no telemetry.

**Documentation:** [doc.lockerprotocol.com/agent-wallet](https://doc.lockerprotocol.com/agent-wallet/agent): install, the setup in steps, how it trades and every command. **Website:** [hyperagentictrader.com](https://hyperagentictrader.com).

Locker Protocol Agentic is an agent wallet for Hyperliquid perps: the `lpa` command for people and for AI agents, an MCP server, and two SDK packages. It comes with a paper account on the real order book, a local policy checked before every order, and every movement of funds signed on the phone.

This repository is its home: the documentation, the changelog, the release log with the SHA-256 of every tarball, and the issue tracker. The four npm packages point their `repository` field here. The source is not published.

## How it works

Three places, and one rule: the key that owns the money never leaves the phone.

```text
  PHONE (offline)              THIS COMPUTER                              HYPERLIQUID
 +--------------------+      +-----------------------------------+      +----------------+
 | Locker Vault       |      | lpa   <- you, a script, or an AI  |      |                |
 |                    |      |  |       agent (shell or MCP)     |      |  order book    |
 | holds the ACCOUNT  |      |  |                                |      |                |
 | key; it never      |  QR  |  |  1. quote on the live book     |      |  your account  |
 | leaves the phone   |<---->|  |  2. local policy               |      |                |
 |                    |codes |  |  3. your go                    |      |                |
 | signs: the agent's |      |  v                                |      |                |
 | approval, deposits,|      | guardian (background process)     |      |                |
 | withdrawals, dex   |      |   holds the AGENT key in memory,  |----->|  orders,       |
 | transfers, revoke  |      |   checks the policy again, signs  |      |  cancels,      |
 +--------------------+      |   trading actions only            |      |  leverage,     |
                             +-----------------------------------+      |  TP/SL         |
                                                                        +----------------+
```

- **Locker Vault** is an app on a phone or tablet that stays offline. It holds the account's key and signs by QR code: the computer shows a request, the phone's camera reads it, the person reads on the phone what it does and signs, the phone shows the signature, the computer's webcam reads it back.
- **The agent key** is made on the computer by `lpa init`, approved once by the vault, sealed on disk under a password. Hyperliquid lets it trade, and refuses it every withdrawal and every send. It expires on its own.
- **The guardian** is a background process that `lpa unlock` starts. It holds the agent key in memory, checks every order against the policy a second time, and against the mandate once you sign one on the phone, and signs only a closed list of trading actions. It answers only requests that carry the token it writes at start, which a plugin cannot read. The agent that calls `lpa` never sees the password nor the key.

| What | Signed by | Where |
|---|---|---|
| Markets, quotes, positions, balances | nobody | public reads |
| Paper orders | nobody | simulated on the computer, on the live book |
| Open, close, cancel, modify | the agent key, in the guardian | after the quote, the policy and your go |
| Approve the agent, revoke it | Locker Vault | QR ceremony, on the phone |
| Deposit, withdraw, move margin between dexes | Locker Vault | QR ceremony, on the phone |
| The mandate: the agent's limits, signed once | Locker Vault | QR ceremony, on the phone |
| A live copy's orders | the agent key, in the guardian | under the policy and the mandate that names the trader |
| A plugin's commands | nothing for the real account | a separate process that reads its own folder only |

## The mandate, the live copies and the plugins

- **The mandate** is the agent's limits signed once on the phone: the policy's bounds, a ceiling on the notional opened per day, the fee recipient, and what the key may be used for. Locker Vault shows every bound on its own row. The guardian checks it before every opening and never lets it widen the local policy. The folder remembers the highest mandate signed and the revocation, so a file gone, an older one put back or a revoked one opens nothing, in this guardian and the next; `lpa mandate revoke` stops every opening until the phone signs a new one, and `lpa mandate release` (your password) goes back to the local policy alone.
- **A live copy** (`lpa copy start --live`) mirrors a trader on the real account. It needs the guardian unlocked by you and a mandate that names the trader, with room in its copy budget. Each order goes through the policy and the mandate like yours, signed by the agent key, never by the account's key. A reduction the guardian could not place is kept and tried again, never lost; the copy's budget stays counted while its positions are open; your own account is never copied. Paper stays the default.
- **A plugin** adds commands and MCP tools. It runs in a separate Node process that reads its own folder only: not your keys, not your settings, not the guardian's token. It does know your user name, the computer's name and its network addresses, and the install screen says so. It reaches your wallet only through the capabilities it declared and you approved, none of which signs for the real account. Its files are fingerprinted at install, and a changed plugin does not run.

## What the agent key can and cannot do

Measured on Hyperliquid mainnet on 2026-09-28, with an approved agent key:

| Action | Signed by the agent key |
|---|---|
| Place, modify and cancel orders, set leverage | accepted |
| `withdraw3`, `usdSend`, `spotSend`, `sendAsset`, `usdClassTransfer` | refused |
| `approveAgent` (approve another agent), `approveBuilderFee` | refused |
| `vaultTransfer` (deposit the account into a vault) | **accepted** |

A stolen agent key cannot withdraw, but it can lose money: by trading against an accomplice on a thin market, or by depositing the account into a vault run by someone else. `lpa` never signs `vaultTransfer` (its guardian signs a closed list of trading actions), but a thief with the key and the password does not need `lpa`. The real bound is a dedicated account that holds only what you are ready to risk.

How this compares with the other agent wallets, quote by quote and source by source: [`COMPARISON.md`](COMPARISON.md).

## The four packages

Each package's page on npm is its complete reference: how it works, then every command, tool or function with an example.

| Package | What it is | Reference |
|---|---|---|
| `@locker-protocol/agent-wallet-hyperliquid-trader` | The `lpa` command: an agent wallet for Hyperliquid perps whose keys stay offline in Locker Vault. Also a library. | [npm](https://www.npmjs.com/package/@locker-protocol/agent-wallet-hyperliquid-trader) |
| `@locker-protocol/agent-wallet-hyperliquid-trader-mcp` | The MCP server: the same commands as 42 tools over stdio, and the tools of the plugins you install, for Claude Code, Cursor, Codex and any MCP client. | [npm](https://www.npmjs.com/package/@locker-protocol/agent-wallet-hyperliquid-trader-mcp) |
| `@locker-protocol/agent-wallet-hyperliquid-signer` | Hyperliquid signing, orders, account reads and live data, for programs whose keys stay in Locker Vault. ESM and CommonJS, with types. | [npm](https://www.npmjs.com/package/@locker-protocol/agent-wallet-hyperliquid-signer) |
| `@locker-protocol/agent-wallet-vault` | The codec of Locker Vault: sign requests and signatures as QR codes, account sync. ESM and CommonJS, with types. | [npm](https://www.npmjs.com/package/@locker-protocol/agent-wallet-vault) |

The four versions move together, one version per release. Node 22.13 or later for the wallet and the MCP server; the two SDKs alone run on any Node 22.

What gets installed where: the one-line installers put `lpa` and the MCP server in `~/.lpa`, on one copy of the packages, with two launchers, `lpa` and `locker-mcp`, so both always run the same version. `npm install -g` installs `lpa` alone; an MCP client can then fetch the server with `npx` at `@latest`, the newest release at each start: when a version comes out, run the installer again so that `lpa` follows. Either way they share the `~/.lpa` folder and the guardian, and a guardian signs nothing for a program of another version.

## Install

```sh
npm install -g @locker-protocol/agent-wallet-hyperliquid-trader@latest
```

Or the one-line installers, which fetch Node when it is missing and put everything in `~/.lpa`, with no administrator rights.

On macOS and Linux:

```sh
curl -fsSL https://hyperagentictrader.com/agent-wallet-install.sh | sh
```

On Windows (PowerShell):

```powershell
irm https://hyperagentictrader.com/agent-wallet-install.ps1 | iex
```

## Start on paper

The paper account fills on Hyperliquid's real book, with the real fees, a