1. Trustless design overview
HyperAgent separates orchestration and signing. The BrainCenter plans trades, but every order signature is produced on the client via `client_signer/hyperagent_signer.py` or an MPC device. No private key is stored on our servers.
Core components:
- Python client signer CLI (repo `client_signer`)
- Optional MPC session with HSM/Fireblocks
- `TRUSTLESS_SETUP` webhook that registers public keys and scopes
- Redis heartbeat `agent:heartbeat:{user_id}` so the UI can attest the signer status
2. Desk prerequisites
1. Create Hyperliquid API keys with trade + read-only scopes.
2. Generate the signing key on a secure workstation or hardware wallet.
3. Install dependencies (`pip install -r client_signer/requirements.txt`) and set `.env` with `HYPERLIQUID_PK`, `WALLET_ADDRESS`, `WEBHOOK_URL`.
4. Allowlisted TLS or VPN back to HyperAgent Brain so signature payloads stay encrypted.
3. Client signer bootstrap
1. Run `python client_signer/hyperagent_signer.py --mode testnet`.
2. The signer opens a websocket and listens for `SIGN_REQUEST` messages.
3. Each request carries the digest (symbol, side, size, nonce). The signer returns `signature = sign(digest, private_key)` and nothing else.
4. Local logs only contain hashes + timestamps so SOC2 auditors can verify activity without exposing secrets.
4. Registering inside HyperAgent
- In Admin -> Agents choose 'Trustless Signing'. Provide the signer URL or public key; the UI never asks for a private key.
- Backend stores `public_key`, `webhook_url`, `max_notional`, `scopes` encrypted with FIPS 140-2 KMS.
- Activation challenge: the user signs a nonce, HyperAgent verifies it, then unlocks the API session.
5. Day-0 operations
1. Analyst -> Boss -> Executor produce strategy directives.
2. Executor emits a `SIGN_REQUEST` whenever an order is actionable.
3. The client signer returns the signature, HyperAgent forwards it to Hyperliquid. Timeout (800 ms) triggers an automatic abort for safety.
4. Every execution in the dashboard shows a 'Trustless' badge so compliance can prove custody never left the client.
6. Security best practices
- Separate hosts for testnet vs mainnet; always dry-run in testnet first.
- Rotate Hyperliquid API keys every 30 days. Since private keys stay local, only API scopes need to change.
- Ship signer logs to your SIEM (Elastic/Datadog) to maintain a continuous audit trail.
- Wire Slack/SES alerts when the signer misses a heartbeat or receives an out-of-scope request.
7. Troubleshooting
- **Signer offline**: restart the local process (check `kill_ghosts.py`) and confirm the heartbeat is back online.
- **Signature rejected**: usually caused by expired nonce or `max_notional` mismatch. Regenerate the signature; secrets remain on the client.
- **MPC migration**: call the `TRUSTLESS_SETUP` webhook with the new MPC provider. HyperAgent only stores references, never raw keys.