Skip to main content

Diamonds

Read a collector's current diamond balance or the paginated diamond leaderboard. Both endpoints use the normal Read API key and accept read, commerce, or write scope. They do not award, transfer, reserve, or spend diamonds.

User balance​

GET /api/public/v1/users/{identifier}/diamonds

curl "https://www.dyli.io/api/public/v1/users/alex/diamonds" \
-H "x-api-key: $DYLI_API_KEY"

Example response (illustrative values):

{
"id": 12345,
"username": "alex",
"wallet": "0x0000000000000000000000000000000000000001",
"pfp": "https://api.dicebear.com/9.x/notionists/svg?seed=alex&scale=110",
"diamonds": 109600.5,
"profile_url": "https://www.dyli.io/profile/alex"
}

identifier accepts a DYLI username, @username, an EVM wallet address, or id:12345. Use the collector's current wallet for wallet lookups. Usernames are case-insensitive. The explicit id: prefix avoids ambiguity with usernames made entirely of digits.

id is the numeric DYLI user record ID, not a Privy DID, wallet address, product ID, or Commerce customer ID. The existing /users/{identifier} profile response is unchanged. An existing public user with no earned diamonds returns 0; missing, banned, or unnamed profiles return 404.

Both responses include wallet from the stored users.wallet field (null when unset), without substituting abstractWallet or a network-derived wallet. pfp is the saved profile image URL, or a DiceBear URL seeded with the username when no image is set. The API constructs the fallback URL without fetching an image.

Leaderboard​

GET /api/public/v1/diamonds/leaderboard

curl "https://www.dyli.io/api/public/v1/diamonds/leaderboard?page=1&pageSize=50" \
-H "x-api-key: $DYLI_API_KEY"
ParameterDefaultDescription
page1Positive integer, 1-based.
pageSize50Positive integer, maximum 100.
limit.Alias for pageSize; pageSize takes precedence.

Example response (illustrative values):

{
"items": [
{
"id": 12345,
"username": "alex",
"wallet": "0x0000000000000000000000000000000000000001",
"pfp": "https://api.dicebear.com/9.x/notionists/svg?seed=alex&scale=110",
"diamonds": 109600.5,
"rank": 1,
"profile_url": "https://www.dyli.io/profile/alex"
}
],
"pagination": {
"page": 1,
"page_size": 1,
"total": 120,
"total_pages": 120,
"has_more": true
}
}

The example pagination corresponds to pageSize=1. Follow has_more and increment page. A page past the end returns 200 with an empty items array and has_more: false.

The leaderboard uses DYLI's existing eligibility rules and additionally excludes banned or unnamed profiles. It sorts by current diamond balance descending, with a stable account tie-breaker. Ranks are sequential positions in this public leaderboard; tied balances have different ranks. No monthly/date filter is supported.

Balance and freshness​

  • diamonds is the current balance from the same trigger-maintained totals used by DYLI, not lifetime earnings or a purchase authorization. Fractional amounts are preserved.
  • Responses can be cached server-side for up to 30 seconds. Live balance changes can move users between pages, so a multi-page read is not a frozen snapshot.
  • Only public identity (including wallet and avatar), balance and rank are returned. Authentication IDs, emails and reward ledger entries are not part of these responses.
  • Invalid identifiers or pagination return 400; unavailable data may return 503 with Retry-After. Normal API-key, endpoint and rate-limit controls apply.