`bullpen hyperliquid agent approve`¶

Last updated: July 13, 2026

Approve an agent wallet that can place and cancel Hyperliquid trades

Usage¶

bullpen hyperliquid agent approve [OPTIONS] --name <NAME> <AGENT_ADDRESS>

Live Help¶

Approve an agent wallet that can place and cancel Hyperliquid trades

Usage: bullpen hyperliquid agent approve [OPTIONS] --name <NAME> <AGENT_ADDRESS>

Arguments:
  <AGENT_ADDRESS>
          Agent wallet address to approve. Must not be the zero address

Options:
      --name <NAME>
          Hyperliquid agent name. Use 16 ASCII bytes or fewer

      --no-multi-wallet-warning
          Suppress the table-mode warning shown when multiple EVM wallet accounts exist

      --output <OUTPUT>
          Output format for command results

          [possible values: table, json]

      --env <ENV>
          Target environment to connect to (overrides config.toml)

          [env: BULLPEN_ENV=]
          [possible values: staging, production]

  -y, --yes
          Required confirmation flag for live Hyperliquid agent approval

      --config <CONFIG>
          Path to a custom config.toml file (overrides $BULLPEN_CONFIG and the default location).

          Explicit --config and BULLPEN_CONFIG paths fail closed: if the file is missing, the CLI exits validation instead of silently loading defaults. Credentials still resolve via BULLPEN_HOME, so set BULLPEN_HOME too when isolating a session.

      --preview
          Show the planned approval without signing or submitting

      --replace
          Allow this approval to replace an existing agent that already uses --name

      --read-only
          Enable read-only mode: blocks all mutating commands

      --non-interactive
          Suppress interactive prompts; does NOT imply --yes for money-moving commands

          [env: BULLPEN_NON_INTERACTIVE=]

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # Preview approving an agent wallet without signing or submitting
  bullpen hyperliquid agent approve 0x2222222222222222222222222222222222222222 --name bot1 --preview

  # Export the agent approval preview as JSON
  bullpen hyperliquid agent approve 0x2222222222222222222222222222222222222222 --name bot1 --preview --output json

AGENT WALLET BOUNDARY:
  This is delegated-agent management. Normal Hyperliquid trades do not create,
  approve, or consume Hyperliquid API/agent wallet slots; use approve only when
  intentionally granting delegated trading authority.

SLOT AND OVERWRITE GUARD:
  Hyperliquid named API-wallet slots are scarce. Before signing, the CLI reads
  extraAgents, reports the named-agent count/cap, fails closed if that state
  cannot be inspected, and warns when --name would re-point an existing agent.
  Preview JSON includes agent_can_trade, agent_can_withdraw,
  overwrites_existing, named_agent_count, named_agent_cap, slot_scarcity, and
  no-submit fields. Duplicate-name previews also include
  existing_agent_valid_until, existing_agent_valid_until_known,
  existing_agent_valid_until_display, existing_agent_validity_status, and
  optional existing_agent_valid_until_iso. Live duplicate-name approvals require
  --replace; inspect agent list validity fields before replacing, reusing, or
  revoking an existing agent slot.

BACKEND REGISTRY NOTE:
  This command manages Hyperliquid extraAgents directly. It is not the
  Bullpen-managed agent-wallet create/adopt flow; run `bullpen hl agent list
  --output json` before and after live use to compare exchange state with the
  Bullpen backend registry.

Example Commands¶

bullpen hyperliquid agent approve 0x2222222222222222222222222222222222222222 --name bot1 --preview
bullpen hyperliquid agent approve 0x2222222222222222222222222222222222222222 --name bot1 --preview --output json

JSON Output¶

Contract: JSON Output Contract.

Successful output is a single JSON document. The shape below is representative for this command family; commands may add fields without breaking the shared contract.

Schema version: 1 when a command emits schema_version; otherwise treat the current command shape as contract version 1.

Top-level Keys¶

key	type	nullable	notes
`schema_version`	integer	yes	Mutation preview/report schema version when emitted
`kind`	string	yes	`hyperliquid_mutation_preview` for preview JSON
`action`	string	no	Always `agent-approve`
`account`	string	no	Active Hyperliquid master account
`intent`	object	no	Planned approval intent. Contains agent identity plus mirrored no-submit/slot guard fields for scripts that read only the intent object
`intent.agent_name`	string	no	Requested Hyperliquid agent name
`intent.agent_address`	string	no	Requested Hyperliquid agent wallet address
`intent.agent_can_trade`	boolean	yes	True when the planned agent can trade/cancel orders
`intent.agent_can_withdraw`	boolean	yes	Always false for Bullpen agent approvals
`intent.overwrites_existing`	boolean	yes	True when the requested name already points at another agent address
`intent.named_agent_count`	integer	yes	Named-agent count observed from Hyperliquid `extraAgents` before signing
`intent.named_agent_cap`	integer	yes	Hyperliquid named-agent slot cap, currently 3
`intent.named_agent_limit`	integer	yes	Backward-compatible alias for `intent.named_agent_cap`
`intent.named_agent_slots_remaining`	integer	yes	Named-agent slots remaining before this approval
`intent.would_exceed_named_agent_limit`	boolean	yes	True when approving a new name would exceed the master-account named-agent cap
`intent.slot_scarcity`	string	yes	Stable classification: `available`, `near_cap`, or `at_cap`
`intent.builder_fee_bps`	number	yes	Always 0 for agent approval intents; agent approval does not approve builder fees
`intent.reduce_only`	boolean	yes	Always false for agent approval intents
`agent_can_trade`	boolean	yes	True when the planned agent can trade/cancel orders
`agent_can_withdraw`	boolean	yes	Always false for Bullpen agent approvals
`overwrites_existing`	boolean	yes	True when the requested name already points at another agent address
`existing_agent_address`	string	yes	Existing agent address when `overwrites_existing` is true
`existing_agent_valid_until`	integer	yes	Raw Hyperliquid `validUntil` for the existing name when `overwrites_existing` is true
`existing_agent_valid_until_known`	boolean	yes	False when Hyperliquid reports `validUntil=0`; do not infer expiry from local time
`existing_agent_valid_until_iso`	string	yes	Parseable non-zero existing-agent expiry timestamp when Hyperliquid provides one
`existing_agent_valid_until_display`	string	yes	Display-safe expiry value; `unknown` for `validUntil=0`
`existing_agent_validity_status`	string	yes	Existing-agent validity classification such as `unknown` or `valid_until_reported`
`named_agent_count`	integer	yes	Named-agent count observed from Hyperliquid `extraAgents` before signing
`named_agent_cap`	integer	yes	Hyperliquid named-agent slot cap, currently 3
`named_agent_limit`	integer	yes	Backward-compatible alias for `named_agent_cap`
`named_agent_slots_remaining`	integer	yes	Named-agent slots remaining before this approval
`would_exceed_named_agent_limit`	boolean	yes	True when approving a new name would exceed the master-account named-agent cap
`slot_scarcity`	string	yes	Stable classification: `available`, `near_cap`, or `at_cap`
`slot_scarcity_warning`	string	yes	Optional human-readable warning when slots are scarce or full
`would_submit`	boolean	yes	False in preview output
`signature_requested`	boolean	yes	False in preview output
`exchange_request_submitted`	boolean	yes	False in preview output

Example¶

Example JSON output

bullpen hyperliquid agent approve 0x2222222222222222222222222222222222222222 --name bot1 --preview --output json

{
  "schema_version": 1,
  "kind": "hyperliquid_mutation_preview",
  "action": "agent-approve",
  "account": "0x1111111111111111111111111111111111111111",
  "intent": {
    "action": "agent-approve",
    "account": "0x1111111111111111111111111111111111111111",
    "agent_name": "bot1",
    "agent_address": "0x2222222222222222222222222222222222222222",
    "agent_can_trade": true,
    "agent_can_withdraw": false,
    "overwrites_existing": false,
    "named_agent_count": 1,
    "named_agent_cap": 3,
    "named_agent_limit": 3,
    "named_agent_slots_remaining": 2,
    "would_exceed_named_agent_limit": false,
    "slot_scarcity": "available",
    "builder_fee_bps": 0.0,
    "reduce_only": false
  },
  "agent_can_trade": true,
  "agent_can_withdraw": false,
  "overwrites_existing": false,
  "named_agent_count": 1,
  "named_agent_cap": 3,
  "named_agent_limit": 3,
  "named_agent_slots_remaining": 2,
  "would_exceed_named_agent_limit": false,
  "slot_scarcity": "available",
  "would_submit": false,
  "signature_requested": false,
  "exchange_request_submitted": false
}

Stability¶

Patch releases may add nullable or optional fields. Minor releases may add required fields or increment schema_version. Major releases may remove or rename fields.

bullpen hyperliquid agent approve¶