userRole | Hyperliquid info

The info endpoint with type: “userRole” retrieves the role and account type information for a specific user on the Hyperliquid network.

POST /4f8d8f4040bdacd1577bff8058438274/info

info (userRole)

cURL

curl --request POST \
  --url https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "userRole",
  "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b"
}
'

200

{
  "role": "user"
}

This method is available on Chainstack. Not all Hyperliquid methods are available on Chainstack, as the open-source node implementation does not support them yet — see Hyperliquid methods for the full availability breakdown.

The info endpoint with type: "userRole" retrieves the role and account type information for a specific user on the Hyperliquid network. This endpoint is essential for understanding the account structure, permissions, and relationships within the Hyperliquid ecosystem.

Get your own node endpoint today

Start for free and get your app to production levels immediately. No credit card required.

You can sign up with your GitHub, X, Google, or Microsoft account.

Parameters

Request body

• type (string, required) — The request type. Must be "userRole" to retrieve user role information.
• user (string, required) — User address in 42-character hexadecimal format (e.g., 0x31ca8395cf837de08b24da3f660e77761dfb974b).

Response

The response varies based on the user’s role type. All responses include a role field, with additional data for certain role types:

Role types

User

{"role": "user"}

• role (string) — Standard user account with full trading capabilities

Agent

{"role": "agent", "data": {"user": "0x..."}}

• role (string) — Agent account that acts on behalf of another user
• data.user (string) — Address of the user this agent represents

Vault

{"role": "vault"}

• role (string) — Vault account for collective asset management

Sub-account

{"role": "subAccount", "data": {"master": "0x..."}}

• role (string) — Sub-account linked to a master account
• data.master (string) — Address of the master account

Missing

{"role": "missing"}

• role (string) — Unrecognized or non-existent account

Understanding user roles

User accounts:

• Standard individual or institutional trading accounts
• Full access to trading, staking, and governance features
• Independent account management and permissions

Agent accounts:

• Authorized to act on behalf of other users
• Used for automated trading, portfolio management, or custody services
• Maintains connection to the principal user account

Vault accounts:

• Collective investment vehicles or fund structures
• May have multiple participants or beneficiaries
• Often used for institutional asset management

Sub-accounts:

• Linked to a master account for organizational purposes
• Useful for separating trading strategies or risk management
• Master account typically maintains oversight and control

Missing accounts:

• Address exists but has no recognized role or activity
• May indicate new, inactive, or invalid addresses
• Useful for validation and error handling

Example request

Shell

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"type": "userRole", "user": "0x31ca8395cf837de08b24da3f660e77761dfb974b"}' \
  https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info

Use your own endpoint in your code. The code examples use a placeholder Chainstack endpoint (YOUR_CHAINSTACK_ENDPOINT) — replace it with your own Hyperliquid node endpoint from the Chainstack console. The curl above uses a shared public endpoint for quick checks only; do not use it in production.

Example response

{"role": "user"}

Use case

The info endpoint with type: "userRole" is essential for applications that need to:

• Access control: Determine appropriate permissions and features for different account types
• User interface: Customize UI elements based on account role and capabilities
• Compliance monitoring: Track different account types for regulatory requirements
• Risk management: Apply role-specific risk controls and limits
• Agent verification: Validate agent relationships and authorization
• Sub-account management: Display master-sub account hierarchies
• Vault operations: Identify collective investment accounts and structures
• Account validation: Verify account existence and type before operations
• Automated systems: Route operations based on account role and permissions
• Reporting systems: Categorize accounts for analytics and compliance
• Customer support: Understand account structure for troubleshooting
• Onboarding flows: Guide users through role-specific setup processes
• API integration: Implement role-based API access and functionality
• Audit trails: Track activities across different account types

This endpoint is particularly valuable for institutional platforms managing multiple account types, compliance systems requiring role-based monitoring, automated trading systems that need to understand account relationships, and applications providing differentiated services based on user roles on the Hyperliquid network.

Body

application/json

type · enum<string> · default: userRole · required

Request type to retrieve user's role information

Available options: userRole

user · string · default: 0x31ca8395cf837de08b24da3f660e77761dfb974b · required

User address in 42-character hexadecimal format

Response

200 - application/json

User's role information and associated data

Option 1

Option 2

Option 3

Option 4

Option 5

Regular user role

role · enum<string> · required

User role type

Available options: user