Authentication & errors

Managers trade programmatically through the same order gate the UI uses. The gate holds the vault's agent key server-side, validates every request against on-chain state, builds and signs the Hyperliquid action, and submits it. You send typed parameters only.

POST {GATE_URL}/vaults/{vaultAddress}/{action}
Authorization: Bearer <credential>
Content-Type: application/json

Scope — by design

The complete action surface is the nine routes documented in Actions. There is no route for any value-moving operation — no withdrawals, no transfers, no bridging. Requests containing raw action payloads, signatures, or nonces are rejected before anything else runs (400 — "raw action fields are not accepted").

Authentication

Two bearer credentials work on the same header:

• Per-vault bot API key — ideal for bots. Keep it secret: it grants order placement (never fund movement) on that vault while you remain the on-chain manager.
• Session identity token — what the web app uses after wallet sign-in.

Getting a bot key

Mint keys yourself from Manage → Trading agent → Bot API keys:

1. Sign in with the vault's manager wallet.
2. Give the key a label (e.g. arb-bot) and click Mint key.
3. Copy the secret immediately — it is shown once and never again (only a hash is stored).

Each key is scoped to that one vault, grants order placement only (never fund movement), and is listed with its created/last-used dates so you can revoke any key with one click. Minting and revoking are authorized by your manager-wallet session — a bot key cannot mint or revoke keys.

Rotation is: mint a new key, switch your bot to it, revoke the old one. Revocation takes effect on the key's next request. (Manager rotation or a protocol block also cuts every key immediately, since standing is checked on-chain per request.)

Prefer to run the web terminal on a bot key instead of a wallet session? Paste it under Manage → Trading agent → Use a key in this browser.

How keys are stored

Only a SHA-256 hash of each key is stored — never the key itself. The plaintext exists just long enough to be returned to you once at mint; the gate authorizes a request by hashing the incoming key and matching, so it never needs the plaintext back. A leak of the key store therefore can't be replayed against the gate: it yields hashes, and a key can't be derived from its hash.

The stored row is metadata only — vault, agent-wallet id, key hash, label, and created/last-used/revoked timestamps. It contains no wallet keys (the agent's signing key lives in the signing provider, not here) and no user secrets.

Both paths are re-authorized on-chain per request: the gate reads the vault's current manager and the manager registry freshly each time and fails closed. Rotating the vault's manager or a protocol block revokes API access on the very next call.

Error model

Two 400 families worth branching on:

• "...not on this vault's watchlist" — spot buy of an unregistered token. Register it first (a manager wallet transaction).
• "...dex is not whitelisted" — order routed to a dex outside the protocol's eligible set.

Rejections inside a 200

Hyperliquid can reject per-order inside a success envelope. Always check response.data.statuses[]:

{
  "status": "ok",
  "response": {
    "type": "order",
    "data": { "statuses": [ { "error": "Order has invalid size." } ] }
  }
}

A successful placement carries {"resting": {"oid": ...}} (or {"filled": {...}} with the average price and size) in the same slot.