Get Stake Snapshots

Retrieve a user's staking history and 7-day average staked amount by wallet address.

Endpoint Details

Method: GET
Path: /api/staking/snapshots
Content-Type: application/json

Request Parameters

Request Headers

Header	Required	Description	Example
`X-API-KEY`	✅ Yes	Your YGG-provided API key	`your_api_key_here`
`Content-Type`	✅ Yes	Must be `application/json`	`application/json`

Response Headers (from YGG)

Header	Included	Description	Example
`X-API-SIGNATURE`	✅ Yes	HMAC signature of response (verify for data integrity)	`92aa703cc483ea2cc90488c05e699179...`

🔐

HMAC Signature: YGG includes X-API-SIGNATURE in all responses. Partners should verify this signature to ensure data integrity. See Authentication for verification details.

Body Parameters

Parameter	Type	Required	Default	Description
`walletAddress`	string	✅ Yes	-	User's wallet address (case-insensitive)
`lastDays`	integer	❌ No	`7`	Number of days of history to retrieve (1-30)

Parameter Details

💡

Wallet Address: Can be any valid Ethereum-compatible address. The API is case-insensitive.

⚠️

lastDays Range: Must be between 1 and 30. Values outside this range will return a validation error.

Request Example

⚠️

YGG_API_BASE_URL: The base URL is provided during integration.

⚠️

Production and Staging environments use different base URLs, API KEYS, and SHARED SECRETS.

# Request to YGG API
curl -v -X GET "<YGG_API_BASE_URL>/api/staking/snapshots?walletAddress=0x123&lastDays=7" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json"
 
# Response from YGG (use -v to see headers)
# HTTP/1.1 200 OK
# X-API-SIGNATURE: 92aa703cc483ea2cc90488c05e699179a1b2c3d4e5f6...
# Content-Type: application/json
 
{
  "walletAddress": "0x000000000abc",
  "requestedAt": "2025-11-08T08:05:00Z",
  "tokenSymbol": "$CHAD",
  "averageStakedAmount": 285.71,
  "stakingSnapshots": [...]
}
 
# Verify X-API-SIGNATURE to ensure data integrity
# See Authentication docs for verification process

Response Format

Success Response

HTTP Status: 200 OK

{
  "walletAddress": "0x000000000abc",
  "requestedAt": "2025-11-08T08:05:00Z",
  "tokenSymbol": "$CHAD",
  "tokenContract": "0x000",
  "stakeContract": "0x000",
  "averageStakedAmount": 285.71,
  "stakingSnapshots": [
    {
      "from": "2025-11-01T00:00:00Z",
      "to": "2025-11-01T23:59:59.999Z",
      "snapshotAmount": 0
    },
    {
      "from": "2025-11-02T00:00:00Z",
      "to": "2025-11-02T23:59:59.999Z",
      "snapshotAmount": 100
    },
    {
      "from": "2025-11-03T00:00:00Z",
      "to": "2025-11-03T23:59:59.999Z",
      "snapshotAmount": 300
    },
    {
      "from": "2025-11-04T00:01:00Z",
      "to": "2025-11-04T23:59:59.999Z",
      "snapshotAmount": 150
    },
    {
      "from": "2025-11-05T00:00:00Z",
      "to": "2025-11-05T23:59:59.999Z",
      "snapshotAmount": 150
    },
    {
      "from": "2025-11-06T00:00:00Z",
      "to": "2025-11-06T23:59:59.999Z",
      "snapshotAmount": 650
    },
    {
      "from": "2025-11-07T00:00:00Z",
      "to": "2025-11-07T23:59:59.999Z",
      "snapshotAmount": 650
    }
  ]
}

Response Fields

Field	Type	Description
`walletAddress`	string	User's wallet address (normalized)
`requestedAt`	string (ISO 8601)	Timestamp when request was received by YGG API
`tokenSymbol`	string	Symbol of the staked token (e.g., "$CHAD")
`tokenContract`	string	Token contract address
`stakeContract`	string	Staking contract address
`averageStakedAmount`	number	7-day average staked amount
`stakingSnapshots`	array	Array of daily staking snapshots

Snapshot Object

Each snapshot in the stakingSnapshots array contains:

Field	Type	Description
`from`	string (ISO 8601)	Start time of the snapshot (UTC)
`to`	string (ISO 8601)	End time of the snapshot (UTC)
`snapshotAmount`	number	Minimum snapshot amount for that day

📊

About averageStakedAmount: This is calculated as the sum of all stakedAmount values in the snapshots divided by the number of days requested.

Understanding the Data

7-Day Average Calculation

The averageStakedAmount is calculated using this formula:

averageStakedAmount = SUM(stakingSnapshots[].stakedAmount) / lastDays

For the example response above:

// Daily amounts
[0, 100, 300, 150, 150, 650, 650]
 
// Calculate average
Sum = 0 + 100 + 300 + 150 + 150 + 650 + 650 = 2000
Average = 2000 / 7 = 285.71

Daily Snapshot Logic

⏰

Important: Each daily stakedAmount represents the minimum staked balance during that 24-hour period (00:00 UTC to 23:59 UTC), not the balance at midnight.

This prevents users from gaming the system by:

Temporarily staking large amounts just before snapshot time
Unstaking immediately after snapshot

Snapshot Timestamps

All snapshots are taken at 00:00 UTC
Dates are in ISO 8601 format
The requestedAt field shows when YGG received the API request

Testing

🧪

Test your integration with various scenarios to ensure robust error handling.

Test Cases

Valid Address with Data
- Use a wallet address that has staking history
- Verify correct average calculation
- Check snapshot array length matches lastDays
Valid Address without Data
- Use a new wallet address with no staking
- Should return 404 error
- Handle gracefully (default to tier 1)
Invalid Address Format
- Use malformed wallet address
- Should return 400 error with appropriate message
Invalid lastDays Parameter
- Test with lastDays = 0 (should fail)
- Test with lastDays = 31 (should fail)
- Test with lastDays = -1 (should fail)
Missing API Key
- Make request without X-API-KEY header
- Should return 401 error
Invalid API Key
- Use incorrect API key
- Should return 401 error
Rate Limiting
- Make many rapid requests
- Should return 429 error
- Verify retry logic works

Performance Considerations

Best Practices

✅

Recommendations:

Cache data for player session duration (1 hour recommended)
Only query API on player login or session refresh
Log all API errors for monitoring

Next Steps

Review Getting Started for integration guidance
Check Authentication for security best practices
Implement tier-based rewards in your game
Test thoroughly before production launch

💬

Questions about the API? Contact our team for support.

Overview Changelog