userRole | Hyperliquid API Docs

Get role information for a user on Hyperliquid. Check user permissions, access levels, and account capabilities.

Get role information for a user on Hyperliquid, including permissions, access levels, and account capabilities.

Authenticate HyperCore Info requests by sending your Dwellir API key in the x-api-key header to https://api-hyperliquid-mainnet-info.n.dwellir.com/info.

When to Use This Endpoint

The userRole endpoint is essential for:

Permission Checking — Verify user access levels and capabilities
Access Control — Implement role-based access in applications
Feature Gating — Enable/disable features based on user role
Account Management — Understand account type and permissions

Common Use Cases

1. Check User Permissions

Verify user role for access control:

JavaScript

async function checkUserPermissions(userAddress) {
  const roleData = await getUserRole(userAddress);

  console.log('=== User Permissions ===\n');
  console.log(`Role: ${roleData.role}`);

  return roleData.role;
}

// Usage
const role = await checkUserPermissions('0x63E8c7C149556D5f34F833419A287bb9Ef81487f');

2. Role-Based Feature Access

Implement role-based feature gating:

JavaScript

async function canAccessFeature(userAddress, featureName) {
  const roleData = await getUserRole(userAddress);

  // Define feature access by role
  const featureAccess = {
    standard: ['basic_trading', 'view_data'],
    vip: ['basic_trading', 'view_data', 'advanced_analytics', 'priority_support'],
    market_maker: ['basic_trading', 'view_data', 'advanced_analytics', 'market_making', 'api_access']
  };

  const userFeatures = featureAccess[roleData.role] || [];
  const hasAccess = userFeatures.includes(featureName);

  console.log(`Feature "${featureName}": ${hasAccess ? 'Granted' : 'Denied'}`);
  return hasAccess;
}

// Usage
const canUseAdvancedAnalytics = await canAccessFeature(
  '0x63E8c7C149556D5f34F833419A287bb9Ef81487f',
  'advanced_analytics'
);

3. Display Role Badge

Show user role in UI:

JavaScript

async function getUserRoleBadge(userAddress) {
  const roleData = await getUserRole(userAddress);

  const badges = {
    standard: { label: 'Standard', color: 'gray' },
    vip: { label: 'VIP', color: 'gold' },
    market_maker: { label: 'Market Maker', color: 'blue' }
  };

  return badges[roleData.role] || { label: 'User', color: 'gray' };
}

// Usage
const badge = await getUserRoleBadge('0x63E8c7C149556D5f34F833419A287bb9Ef81487f');
console.log(`Display badge: ${badge.label} (${badge.color})`);

4. Build Access Control System

Create comprehensive access control:

JavaScript

class AccessControl {
  constructor(userAddress) {
    this.userAddress = userAddress;
    this.role = null;
  }

  async initialize() {
    const roleData = await getUserRole(this.userAddress);
    this.role = roleData.role;
    return this.role;
  }

  hasPermission(permission) {
    const permissions = {
      standard: ['read', 'basic_trade'],
      vip: ['read', 'basic_trade', 'advanced_trade', 'analytics'],
      market_maker: ['read', 'basic_trade', 'advanced_trade', 'analytics', 'market_make', 'api']
    };

    const userPermissions = permissions[this.role] || [];
    return userPermissions.includes(permission);
  }

  getPermissions() {
    const permissions = {
      standard: ['read', 'basic_trade'],
      vip: ['read', 'basic_trade', 'advanced_trade', 'analytics'],
      market_maker: ['read', 'basic_trade', 'advanced_trade', 'analytics', 'market_make', 'api']
    };

    return permissions[this.role] || [];
  }
}

// Usage
const acl = new AccessControl('0x63E8c7C149556D5f34F833419A287bb9Ef81487f');
await acl.initialize();

if (acl.hasPermission('advanced_trade')) {
  console.log('User can access advanced trading');
}

5. Role-Based Dashboard

Customize dashboard based on user role:

JavaScript

async function buildRoleBasedDashboard(userAddress) {
  const roleData = await getUserRole(userAddress);

  const dashboardConfig = {
    standard: {
      widgets: ['account_summary', 'basic_charts', 'order_book'],
      features: ['basic_trading']
    },
    vip: {
      widgets: ['account_summary', 'advanced_charts', 'order_book', 'analytics'],
      features: ['basic_trading', 'advanced_trading', 'analytics']
    },
    market_maker: {
      widgets: ['account_summary', 'advanced_charts', 'order_book', 'analytics', 'api_stats'],
      features: ['basic_trading', 'advanced_trading', 'analytics', 'market_making', 'api_access']
    }
  };

  const config = dashboardConfig[roleData.role] || dashboardConfig.standard;

  return {
    role: roleData.role,
    dashboard: config,
    timestamp: new Date().toISOString()
  };
}

// Usage
const dashboard = await buildRoleBasedDashboard('0x63E8c7C149556D5f34F833419A287bb9Ef81487f');
console.log('Dashboard configuration:', dashboard);

Best Practices

Cache role data — Role changes infrequently, cache for 5-10 minutes
Validate addresses — Ensure user addresses are valid Ethereum addresses
Default to least privilege — Use most restrictive role as default
Handle unknown roles — Have fallback for unrecognized roles
Implement feature flags — Combine with feature flags for flexible access control

Performance Tips

Cached Role Checker

JavaScript

class CachedRoleChecker {
  constructor(cacheDurationMs = 300000) {
    this.cache = new Map();
    this.cacheDurationMs = cacheDurationMs; // 5 minutes
  }

  async getRole(userAddress) {
    const cached = this.cache.get(userAddress);
    const now = Date.now();

    if (cached && (now - cached.timestamp) < this.cacheDurationMs) {
      return cached.role;
    }

    const roleData = await getUserRole(userAddress);
    this.cache.set(userAddress, {
      role: roleData.role,
      timestamp: now
    });

    return roleData.role;
  }

  invalidate(userAddress) {
    this.cache.delete(userAddress);
  }

  clearAll() {
    this.cache.clear();
  }
}

// Usage
const roleChecker = new CachedRoleChecker();
const role = await roleChecker.getRole('0x63E8c7C149556D5f34F833419A287bb9Ef81487f');

extraAgents — Get agent information
subAccounts — Get sub-account details
clearinghouseState — Get account state
userFees — Get fee information (may vary by role)

Implement role-based access control with Dwellir's HyperCore Info Endpoint. Get your API key →

userRole - HyperCore Info Endpoint

When to Use This Endpoint

Common Use Cases

1. Check User Permissions

2. Role-Based Feature Access

3. Display Role Badge

4. Build Access Control System

5. Role-Based Dashboard

Best Practices

Performance Tips

Cached Role Checker

On this page