approveAgent (gRPC) | Hyperliquid API Docs

Authorize an API wallet (agent) to sign transactions on behalf of a master account on Hyperliquid.

Authorize an API wallet (also called an agent) to sign transactions on behalf of the master account or its sub-accounts. This enables programmatic trading while keeping the master private key secure.

Sample Data

JSON

{
  "signature": {
    "r": "0xa440cd8904dfbd812cb3669258413c6139c12dbc7083ea000b1f73e4ff4ef1e3",
    "s": "0x79c77f830c666018af5e13d229d8955e1e4f7fe89e225886cd9b8f638c2d8638",
    "v": 28
  },
  "action": {
    "type": "approveAgent",
    "signatureChainId": "0x2105",
    "hyperliquidChain": "Mainnet",
    "agentAddress": "0x9c0e10bb3ac3b461b2a24c4465ece3f343d6321a",
    "agentName": "DEFI_AGENT_3 valid_until 1768319711089",
    "nonce": 1768146911127
  },
  "nonce": 1768146911127
}

View this transaction on Hypurrscan

Field Reference

Action Fields

Field	Type	Description
`type`	string	Always `"approveAgent"`
`signatureChainId`	string	Chain ID for EIP-712 signing (e.g., `"0xa4b1"` for Arbitrum)
`hyperliquidChain`	string	Target chain: `"Mainnet"` or `"Testnet"`
`agentAddress`	string	Ethereum address of the agent wallet to authorize
`agentName`	string	Optional human-readable name for the agent
`nonce`	number	Timestamp-based nonce for replay protection

Agent Naming

Agents can be named or unnamed:

Named agents: Identified by agentName. Sending a new approveAgent with the same name replaces the previous agent.
Unnamed agents: No name specified. Only one unnamed agent can exist at a time.

Common agent names include wallet integrations like "rabby-mobile", "metamask", or custom names for trading bots.

Security Considerations

Agent wallets can only sign trading operations, not withdrawals
The master wallet must sign approveAgent actions directly
Once deregistered, an agent's nonce state may be pruned, potentially allowing replay of old signed actions
Generate new agent wallets rather than reusing addresses

Use Cases

Trading Bot Setup Detection

Monitor when new trading bots or API integrations are authorized:

Python

def process_approveAgent_action(action):
    agent_address = action.get('agentAddress')
    agent_name = action.get('agentName', 'unnamed')

    print(f"Agent authorized: {agent_name} ({agent_address})")

Wallet Integration Tracking

Track adoption of different wallet providers by monitoring agent names.

Security Monitoring

Detect unauthorized agent approvals for accounts you're monitoring.

approveBuilderFee - Approve builder fee rates
agentEnableDexAbstraction - Enable DEX abstraction for agents

approveAgent - Authorize API Wallets