# Hyperliquid account vs agent-wallet credential gate

Use when wiring Hyperliquid read-only reconciliation, testnet signed smokes, or live-preview gates.

## Durable lesson

Do not treat the exchange account address and the API/agent wallet address as interchangeable.

Preferred env names:

- `HL_ACCOUNT_ADDRESS`: normal Hyperliquid account/subaccount address. Use this for all Info/read-only requests and as SDK `account_address`.
- `HL_AGENT_PRIVATE_KEY`: private key of the Hyperliquid API/agent wallet. Use this only for signed actions.
- `HL_AGENT_WALLET_ADDRESS`: public address of the API/agent wallet. It must equal the address derived from `HL_AGENT_PRIVATE_KEY`.

Legacy aliases may be accepted for migration, but should be reported as legacy:

- `HL_WALLET_ADDRESS` -> `HL_ACCOUNT_ADDRESS`
- `HL_API_PRIVATE_KEY` -> `HL_AGENT_PRIVATE_KEY`
- `API Key`, `API_KEY`, `API_Wallet_Adress`, `API_Wallet_Address` -> `HL_AGENT_WALLET_ADDRESS`

## Required credential checks

Before any testnet or live signed action:

1. Load only the environment-specific file (`Testnet.env` for testnet, `Mainnet.env` for mainnet); never parse testnet/mainnet from shared comment blocks.
2. Derive the agent public address from `HL_AGENT_PRIVATE_KEY`.
3. Require `derived_agent_address == HL_AGENT_WALLET_ADDRESS`.
4. Require `HL_ACCOUNT_ADDRESS != HL_AGENT_WALLET_ADDRESS`.
5. Use `HL_ACCOUNT_ADDRESS` for Info/read-only requests and SDK `account_address`.
6. Use `HL_AGENT_PRIVATE_KEY` only as the signer/secret for signed actions.
7. If Hyperliquid returns `User or API Wallet ... does not exist`, mark signed gates blocked and do not proceed to order smokes.

## Read-only vs signed validation

Read-only reconciliation should not need a private key. If the agent wallet/private key is missing or mismatched, read-only tools may still run using `HL_ACCOUNT_ADDRESS`, but must report warnings and `private_key_used=false`.

Signed tools must fail closed on credential mismatch. Do not run `scheduleCancel`, ALO+Cancel, Fill+Stop, or any other signed smoke until the credential check is green.

## Reporting

Reports should mask all addresses and never print private keys. Include:

- env name and env-file path
- masked account address
- masked agent address from env
- masked agent address derived from private key
- whether the derived address matches the env agent address
- whether account address equals agent address
- whether signed smokes are safe to run
- warning/error list

## Pitfall

A local private key can be syntactically valid and still unusable on Hyperliquid testnet/mainnet if its derived agent address is not registered for the account. Do not weaken gates or call that a network/tool failure; keep signed actions blocked until the account-agent relationship is valid on the exchange.