approveAgent payload (gRPC) | Hyperliquid API Docs

Decode Hyperliquid `approveAgent` payloads for API wallet authorization, returned through Dwellir's read-only L1 gRPC API.

Read-only action reference

Dwellir's Hyperliquid gRPC API returns this decoded action payload through StreamBlocks and GetBlock. It does not submit or execute this action. Submit supported user write actions through Hyperliquid's native POST /exchange endpoint.

The decoded approveAgent payload records authorization for an API wallet, also called an agent, to sign on behalf of a master account or its sub-accounts.

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 - Builder fee approvals
agentEnableDexAbstraction - Agent DEX abstraction settings

approveAgent payload - API Wallet Authorization