delegations

Get detailed staking delegation information for a user, including validator assignments, amounts, and delegation history.

When to Use This Endpoint

The delegations endpoint is essential for:

• Staking Management — View detailed delegation information
• Validator Tracking — Monitor which validators you're delegating to
• Rewards Analysis — Track delegation performance and returns
• Portfolio Optimization — Analyze and rebalance delegation strategy

Request

Endpoint

POST https://api-hyperliquid-mainnet-info.n.dwellir.com/info

Headers

Header	Value	Required
Content-Type	application/json	Yes
X-Api-Key	Your API key	Yes

Parameters

Parameter	Type	Required	Description
type	string	Yes	Must be "delegations"
user	string	Yes	User's Ethereum wallet address

Example Request

{
  "type": "delegations",
  "user": "0x420a4ed7b6bb361da586868adec2f2bb9ab75e66"
}

Response

Success Response

[
  {
    "validator": "0x420a4ed7b6bb361da586868adec2f2bb9ab75e66",
    "amount": "12505.32462249",
    "lockedUntilTimestamp": 1762449026533
  }
]

Response Fields

The response is an array of delegation objects. Each delegation contains:

Field	Type	Description
validator	string	Ethereum address of the validator
amount	string	Amount of tokens delegated
lockedUntilTimestamp	integer	Unix timestamp (milliseconds) when delegation unlocks

Code Examples

cURL

curl -X POST 'https://api-hyperliquid-mainnet-info.n.dwellir.com/info' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "delegations",
    "user": "0x420a4ed7b6bb361da586868adec2f2bb9ab75e66"
  }'

JavaScript

const ENDPOINT = 'https://api-hyperliquid-mainnet-info.n.dwellir.com/info';
const API_KEY = 'your-api-key-here';

async function getDelegations(userAddress) {
  const response = await fetch(ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': API_KEY
    },
    body: JSON.stringify({
      type: 'delegations',
      user: userAddress
    })
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }

  return await response.json();
}

// Usage
const delegations = await getDelegations('0x420a4ed7b6bb361da586868adec2f2bb9ab75e66');
console.log(`Total delegations: ${delegations.length}`);

// Display delegation details
delegations.forEach(d => {
  console.log(`Validator: ${d.validator}`);
  console.log(`Amount: ${d.amount}`);
  console.log(`Unlocks: ${new Date(d.lockedUntilTimestamp).toISOString()}`);
});

Python

import requests
from typing import Dict

ENDPOINT = 'https://api-hyperliquid-mainnet-info.n.dwellir.com/info'
API_KEY = 'your-api-key-here'

def get_delegations(user_address: str) -> Dict:
    """Get user delegation information"""
    response = requests.post(
        ENDPOINT,
        json={
            'type': 'delegations',
            'user': user_address
        },
        headers={
            'Content-Type': 'application/json',
            'X-Api-Key': API_KEY
        },
        timeout=10
    )
    response.raise_for_status()
    return response.json()

# Usage
delegations = get_delegations('0x420a4ed7b6bb361da586868adec2f2bb9ab75e66')
print(f"Total delegations: {len(delegations['delegations'])}")

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

const (
    Endpoint = "https://api-hyperliquid-mainnet-info.n.dwellir.com/info"
    APIKey   = "your-api-key-here"
)

type DelegationsRequest struct {
    Type string `json:"type"`
    User string `json:"user"`
}

type DelegationsResponse struct {
    Delegations []interface{} `json:"delegations"`
}

func getDelegations(userAddress string) (*DelegationsResponse, error) {
    reqBody, _ := json.Marshal(DelegationsRequest{
        Type: "delegations",
        User: userAddress,
    })

    req, _ := http.NewRequest("POST", Endpoint, bytes.NewBuffer(reqBody))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-Api-Key", APIKey)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)

    var result DelegationsResponse
    if err := json.Unmarshal(body, &result); err != nil {
        return nil, err
    }

    return &result, nil
}

func main() {
    delegations, err := getDelegations("0x420a4ed7b6bb361da586868adec2f2bb9ab75e66")
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Printf("Total delegations: %d\n", len(delegations.Delegations))
}

Common Use Cases

1. View Delegation Portfolio

Display all active delegations:

async function viewDelegationPortfolio(userAddress) {
  const data = await getDelegations(userAddress);

  console.log('=== Delegation Portfolio ===\n');
  console.log(`Total delegations: ${data.delegations.length}`);

  if (data.delegations.length === 0) {
    console.log('No active delegations');
  } else {
    console.log('Delegation details available');
  }
}

// Usage
await viewDelegationPortfolio('0x420a4ed7b6bb361da586868adec2f2bb9ab75e66');

2. Monitor Delegation Status

Track delegation changes over time:

async function monitorDelegationStatus(userAddress) {
  const data = await getDelegations(userAddress);

  return {
    delegationCount: data.delegations.length,
    hasActiveDelegations: data.delegations.length > 0,
    timestamp: new Date().toISOString()
  };
}

// Usage
const status = await monitorDelegationStatus('0x420a4ed7b6bb361da586868adec2f2bb9ab75e66');
console.log('Delegation status:', status);

3. Build Staking Dashboard

Create a comprehensive staking dashboard:

async function getStakingDashboard(userAddress) {
  try {
    const data = await getDelegations(userAddress);

    return {
      status: 'success',
      delegations: data.delegations,
      totalDelegations: data.delegations.length,
      isStaking: data.delegations.length > 0,
      lastUpdated: new Date().toISOString()
    };
  } catch (error) {
    return {
      status: 'error',
      error: error.message
    };
  }
}

// Usage
const dashboard = await getStakingDashboard('0x420a4ed7b6bb361da586868adec2f2bb9ab75e66');
console.log('Staking Dashboard:', dashboard);

4. Check Delegation Diversity

Analyze delegation distribution:

async function analyzeDelegationDiversity(userAddress) {
  const data = await getDelegations(userAddress);

  const analysis = {
    totalDelegations: data.delegations.length,
    isDiversified: data.delegations.length > 1,
    delegationStatus: data.delegations.length > 0 ? 'active' : 'none'
  };

  if (analysis.isDiversified) {
    console.log('Portfolio is diversified across multiple validators');
  } else if (analysis.totalDelegations === 1) {
    console.log('Portfolio concentrated in single validator');
  } else {
    console.log('No active delegations');
  }

  return analysis;
}

5. Track Delegation History

Monitor delegation changes:

class DelegationTracker {
  constructor(userAddress) {
    this.userAddress = userAddress;
    this.history = [];
  }

  async recordSnapshot() {
    const data = await getDelegations(this.userAddress);

    const snapshot = {
      timestamp: Date.now(),
      delegationCount: data.delegations.length,
      delegations: data.delegations
    };

    this.history.push(snapshot);
    return snapshot;
  }

  getHistory() {
    return this.history;
  }

  detectChanges() {
    if (this.history.length < 2) return null;

    const latest = this.history[this.history.length - 1];
    const previous = this.history[this.history.length - 2];

    return {
      countChange: latest.delegationCount - previous.delegationCount,
      timestamp: latest.timestamp
    };
  }
}

// Usage
const tracker = new DelegationTracker('0x420a4ed7b6bb361da586868adec2f2bb9ab75e66');
await tracker.recordSnapshot();

Error Handling

Common Errors

Error	Cause	Solution
401 Unauthorized	Invalid API key	Verify your API key is correct
400 Bad Request	Missing or invalid user address	Ensure valid Ethereum address format
429 Too Many Requests	Rate limit exceeded	Implement request throttling
500 Internal Server Error	Server issue	Retry with exponential backoff

Error Response Example

{
  "error": "Missing required parameter: user",
  "code": "MISSING_PARAMETER"
}

Robust Error Handling

async function safeGetDelegations(userAddress, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await getDelegations(userAddress);
    } catch (error) {
      if (error.response?.status === 429) {
        await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
      } else if (error.response?.status === 400) {
        throw new Error('Invalid user address');
      } else if (i === maxRetries - 1) {
        throw error;
      }
    }
  }
}

Best Practices

1. Validate addresses — Ensure user addresses are valid Ethereum addresses
2. Cache strategically — Cache delegation data for several minutes
3. Handle empty states — Account for users with no delegations
4. Monitor regularly — Track changes for portfolio management
5. Compare snapshots — Store historical data to detect changes

Related Endpoints

• delegatorSummary — Get delegation summary
• validatorL1Votes — Get validator voting information
• clearinghouseState — Get account state
• userFees — Get user fee information

---

Access real-time Hyperliquid delegation data with Dwellir's HyperCore Info Endpoint. Get your API key →