wiki

WIKI/AGENTS.md

@@ -0,0 +1,34 @@
+Agents and Keys
+
+This project supports running multiple agent identities (private keys) to place orders on Hyperliquid. Agents are lightweight keys authorized on-chain by your main wallet.
+
+Agent storage and environment
+
+- For security, agent private keys should be stored as environment variables and not checked into source control.
+- Supported patterns:
+  - `AGENT_PRIVATE_KEY` (single default agent)
+  - `<NAME>_AGENT_PK` or `<NAME>_AGENT_PRIVATE_KEY` (per-agent keys)
+
+Discovering agents
+
+- `trade_executor.py` scans environment variables for agent keys and loads them into `Exchange` objects so each agent can sign orders independently.
+
+Creating and authorizing agents
+
+- Use `create_agent.py` with your `MAIN_WALLET_PRIVATE_KEY` to authorize a new agent name. The script will attempt to call `exchange.approve_agent(agent_name)` and print the returned agent private key.
+
+Security notes
+
+- Never commit private keys to Git. Keep them in a secure secrets store or local `.env` file excluded from version control.
+- Rotate keys if they are ever exposed and re-authorize agents using your main wallet.
+
+Example `.env` snippet
+
+MAIN_WALLET_PRIVATE_KEY=<your-main-wallet-private-key>
+MAIN_WALLET_ADDRESS=<your-main-wallet-address>
+AGENT_PRIVATE_KEY=<agent-private-key>
+EXECUTOR_SCALPER_AGENT_PK=<agent-private-key-for-scalper>
+
+File `agents`
+
+- This repository may contain a local `agents` file used as a quick snapshot; treat it as insecure and remove it from the repo or add it to `.gitignore` if it contains secrets.