Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,13 +61,13 @@ Use the mission `services.yaml` commands when working inside a Factory mission.

## Terminology and Selector Semantics

- Use "local signing account" for encrypted local private-key records, and "selected signer" for the key used to sign an authenticated action.
- Use "explicit local signer" for non-stored private-key, env/config private-key, or keystore signing paths, and "selected signer" for the key used to sign an authenticated action.
- Use "API wallet" and "agent wallet" only for delegated Hyperliquid trading keys approved by a master account. These can trade for the master account but cannot withdraw.
- Use "OWS wallet" for wallets managed by the Open Wallet Standard backend. OWS is the only managed wallet lifecycle backend for `hyperliquid-cli` — wallet creation, import, and listing flow through the OWS vault (default `~/.hyperliquid` or `HYPERLIQUID_OWS_VAULT_PATH` when set). The `--ows-signer` flag selects a specific OWS wallet by name or id for signing; explicit private-key, Foundry keystore, and stored local-account signing paths still exist outside OWS. When no explicit signer is specified, commands auto-detect the first OWS wallet with a Hyperliquid account. Direct `0x` addresses passed via `--ows-signer` require a resolved wallet for live signing; without a wallet, only identity previews are possible. Priority bids and headless OWS approval remain local-only/unsupported until separately designed.
- Use "OWS wallet" for wallets managed by the Open Wallet Standard backend. OWS is the only managed wallet lifecycle backend for `hyperliquid-cli` — wallet creation, import, and listing flow through the OWS vault (default `~/.hyperliquid` or `HYPERLIQUID_OWS_VAULT_PATH` when set). The `--ows-signer` flag selects a specific OWS wallet by name or id for signing; explicit private-key flag/env/config and Foundry keystore signing paths still exist outside OWS. When no explicit signer is specified, commands auto-detect the first OWS wallet with a Hyperliquid account. Direct `0x` addresses passed via `--ows-signer` require a resolved wallet for live signing; without a wallet, only identity previews are possible. Priority bids and headless OWS approval remain local-only/unsupported until separately designed.
- Use "protocol user address" or `USER` for public account-data lookup targets.
- Use `ACCOUNT_SELECTOR` for inputs that may accept a stored account alias, stored account id, or `0x` address.
- Use `*_ADDRESS` for explicit protocol object addresses such as transfer recipients, vaults, validators, and builders. Do not resolve local account aliases for these fields.
- Treat acting-account selectors such as `orders --on-behalf-of` and `subaccount transfer --subaccount` as their own documented selector class. They may resolve a subaccount/vault context for that signed action, but they do not imply aliases are safe for transfer recipients or other `*_ADDRESS` fields.
- Use `ACCOUNT_SELECTOR` for inputs that may accept an OWS wallet name, OWS wallet id, or `0x` address.
- Use `*_ADDRESS` for explicit protocol object addresses such as transfer recipients, vaults, validators, and builders. Do not resolve wallet names or local aliases for these fields.
- Treat acting-account selectors such as `orders --on-behalf-of` and `subaccount transfer --subaccount` as their own documented selector class. They may resolve an OWS wallet, subaccount, or vault context for that signed action, but they do not imply names or aliases are safe for transfer recipients or other `*_ADDRESS` fields.
- When schema metadata disagrees with README prose or examples, agents should treat schema `input_kind`, risk, dry-run, and confirmation metadata as authoritative.

## Testing Instructions
Expand Down
115 changes: 2 additions & 113 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 0 additions & 4 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -63,14 +63,10 @@ futures = "0.3"
either = "1"
rmp-serde = "1"
alloy-primitives = "1"
rusqlite = { version = "0.38", features = ["bundled"] }
aes-gcm = "0.10"
base64 = "0.22"
hex = "0.4"
rand = "0.10"
sha2 = "0.11"
rpassword = "7"
keyring = { version = "3", features = ["apple-native", "linux-native", "windows-native"] }
ows-lib = "1.3.2"

[features]
Expand Down
4 changes: 2 additions & 2 deletions README.ja-JP.md
Original file line number Diff line number Diff line change
Expand Up @@ -183,8 +183,8 @@ export OWS_PASSPHRASE=... # unlock encrypted OWS wallet

| Class | Accepted values | Used for |
| --- | --- | --- |
| `ACCOUNT_SELECTOR` | 保存済み account alias、保存済み account id、または `0x` address | `--account` で signer を選択する、または OWS wallet レコードを管理するため。 |
| `USER` | `0x` user address、または文書化された安全な stored-account selector | `account portfolio`、`orders status --user`、fee クエリなどの公開 lookup。 |
| `ACCOUNT_SELECTOR` | OWS wallet name、OWS wallet id、または `0x` address | `--account` で signer を選択する、または OWS wallet レコードを管理するため。 |
| `USER` | `0x` user address、または文書化された安全な OWS wallet selector | `account portfolio`、`orders status --user`、fee クエリなどの公開 lookup。 |
| `*_ADDRESS` | 明示的な `0x` protocol address のみ | 送金 recipient、vault、validator、builder、その他のプロトコルオブジェクト。ローカル alias がこれらのフィールドに代入されることはありません。 |

エージェントにとって、`hyperliquid --format json schema ...` のツールスキーマは、例や説明文と矛盾する場合の入力セマンティクスの信頼できる情報源です。
Expand Down
8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -170,7 +170,7 @@ See [`SKILL.md`](SKILL.md) for the agent operating guide.

| Domain | Examples |
| --- | --- |
| Local signing account / OWS wallet account record | An OWS wallet record managed by `account add`, `account ls`, `account set-default`, and related commands. |
| OWS wallet account record | An OWS wallet record managed by `account add`, `account ls`, `account set-default`, and related commands. |
| Selected signer | The key used to sign authenticated actions, chosen from flags, environment/config, global `--account`, or the OWS selector. |
| Protocol user address | A public Hyperliquid user address used for info queries such as fills, portfolio, fees, or order status. |
| Master account | The protocol owner account that can approve API wallets and own subaccounts. |
Expand All @@ -183,8 +183,8 @@ Address-like command inputs fall into three safety classes:

| Class | Accepted values | Used for |
| --- | --- | --- |
| `ACCOUNT_SELECTOR` | Stored account alias, stored account id, or `0x` address | Selecting a signer with `--account` or managing OWS wallet records. |
| `USER` | `0x` user address, or a documented safe stored-account selector | Public lookups such as `account portfolio`, `orders status --user`, or fee queries. |
| `ACCOUNT_SELECTOR` | OWS wallet name, OWS wallet id, or `0x` address | Selecting a signer with `--account` or managing OWS wallet records. |
| `USER` | `0x` user address, or a documented safe OWS wallet selector | Public lookups such as `account portfolio`, `orders status --user`, or fee queries. |
| `*_ADDRESS` | Explicit `0x` protocol address only | Transfer recipients, vaults, validators, builders, and other protocol objects. Local aliases are not substituted for these fields. |

For agents, `hyperliquid --format json schema ...` tool schemas are the authoritative source for input semantics when they conflict with examples or prose.
Expand Down Expand Up @@ -273,7 +273,7 @@ Canonical top-level aliases accepted by the CLI:

API wallets can sign trading actions for the approving master account, but they cannot withdraw. Use the master or subaccount address for info queries. When `api-wallet create` generates a local agent keypair, it prints the private key once before submitting `approveAgent` for that address; store that key securely because the CLI does not automatically recover it later.

Signer and acting-account flags intentionally share the same selector grammar where it is safe: raw `0x` address, stored wallet/account alias, or stored wallet/account id. Their roles differ. Global `--account` / `--wallet` selects the key that signs the action; per-command `--on-behalf-of` selects the protocol account, subaccount, or vault supplied as Hyperliquid `vaultAddress` for that action.
Signer and acting-account flags intentionally share the same selector grammar where it is safe: raw `0x` address, OWS wallet name, or OWS wallet id. Their roles differ. Global `--account` / `--wallet` selects the key that signs the action; per-command `--on-behalf-of` selects the protocol account, subaccount, or vault supplied as Hyperliquid `vaultAddress` for that action.

### Trading and transfers

Expand Down
4 changes: 2 additions & 2 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -183,8 +183,8 @@ export OWS_PASSPHRASE=... # unlock encrypted OWS wallet

| 类别 | 接受的值 | 用于 |
| --- | --- | --- |
| `ACCOUNT_SELECTOR` | Stored account alias、stored account id 或 `0x` address | 使用 `--account` 选择签名者,或管理 OWS wallet records。 |
| `USER` | `0x` user address,或有文档说明的安全 stored-account selector | 公共查询,例如 `account portfolio`、`orders status --user` 或 fee queries。 |
| `ACCOUNT_SELECTOR` | OWS wallet name、OWS wallet id 或 `0x` address | 使用 `--account` 选择签名者,或管理 OWS wallet records。 |
| `USER` | `0x` user address,或有文档说明的安全 OWS wallet selector | 公共查询,例如 `account portfolio`、`orders status --user` 或 fee queries。 |
| `*_ADDRESS` | 仅显式 `0x` protocol address | Transfer recipients、vaults、validators、builders 和其他 protocol objects。Local aliases 不会替换到这些字段。 |

对于代理,当 `hyperliquid --format json schema ...` 工具 schema 与示例或说明性文字冲突时,它们是输入语义的权威来源。
Expand Down
Loading
Loading