User Progress

Operations for tracking user badge achievements and progress

Get user's badge progress

get

https://badges.decentraland.orghttps://badges.decentraland.zone

/users/{address}/badges

Returns detailed progress information for all badges associated with a specific user address.

This endpoint provides comprehensive tracking data including:

• Achieved badges: Badges the user has earned (at least one step completed)

• Progress tracking: Current steps completed vs. target steps for next tier

• Tier progression: For tiered badges, shows which tiers have been completed and when

• Completion status: Whether the badge/tier is fully completed

• Asset information: Current badge/tier images and metadata

The response is divided into two categories:

• achieved: Badges with at least one step or tier completed

• notAchieved: Badges not yet started (only included if includeNotAchieved=true)

For tiered badges, the progress tracks movement through tiers (Starter → Bronze → Silver → Gold → Platinum → Diamond). For single-tier badges, it tracks completion of a specific criteria.

Path parameters

addressstringRequired

User's Ethereum address (wallet address)

Example: 0x1234567890123456789012345678901234567890

Query parameters

includeNotAchievedbooleanOptional

If true, includes badges that the user hasn't started working toward yet

Default: false

Responses

200

Successfully retrieved user's badge progress

application/json

404

User address not found or invalid

application/json

get

/users/{address}/badges

HTTPcURLJavaScriptPython

GET /users/{address}/badges HTTP/1.1
Host: badges.decentraland.org
Accept: */*

{
  "data": {
    "achieved": [
      {
        "id": "traveler",
        "name": "Traveler",
        "description": "text",
        "category": "Explorer",
        "isTier": true,
        "completedAt": null,
        "assets": {
          "2d": {
            "normal": "https://badges.decentraland.org/assets/badge-2d.png"
          },
          "3d": {
            "normal": "text",
            "hrm": "text",
            "basecolor": "text"
          }
        },
        "progress": {
          "achievedTiers": [
            {
              "tierId": "traveler-bronze",
              "completedAt": 1
            }
          ],
          "stepsDone": 75,
          "nextStepsTarget": 250,
          "totalStepsTarget": 10000,
          "lastCompletedTierAt": null,
          "lastCompletedTierName": "Bronze",
          "lastCompletedTierImage": null
        }
      }
    ],
    "notAchieved": [
      {
        "id": "traveler",
        "name": "Traveler",
        "description": "text",
        "category": "Explorer",
        "isTier": true,
        "completedAt": null,
        "assets": {
          "2d": {
            "normal": "https://badges.decentraland.org/assets/badge-2d.png"
          },
          "3d": {
            "normal": "text",
            "hrm": "text",
            "basecolor": "text"
          }
        },
        "progress": {
          "achievedTiers": [
            {
              "tierId": "traveler-bronze",
              "completedAt": 1
            }
          ],
          "stepsDone": 75,
          "nextStepsTarget": 250,
          "totalStepsTarget": 10000,
          "lastCompletedTierAt": null,
          "lastCompletedTierName": "Bronze",
          "lastCompletedTierImage": null
        }
      }
    ]
  }
}

Get user's latest achieved badges

get

https://badges.decentraland.orghttps://badges.decentraland.zone

/users/{address}/preview

Returns a lightweight preview of the user's most recently achieved badges.

This endpoint is optimized for displaying user achievements in UI components like profile cards or leaderboards. It provides:

• Badge ID, name, and display image

• Tier name (if applicable) for the most recently achieved tier

• Appropriate badge imagery for the current tier level

Unlike /users/{address}/badges, this endpoint:

• Returns only completed badges (no progress tracking)

• Includes only the latest achievements

• Has a lighter payload optimized for quick loading

• Is ideal for preview cards, tooltips, and summary displays

Path parameters

addressstringRequired

User's Ethereum address

Example: 0x1234567890123456789012345678901234567890

Responses

200

Successfully retrieved user's badge preview

application/json

404

User address not found or invalid

application/json

get

/users/{address}/preview

HTTPcURLJavaScriptPython

GET /users/{address}/preview HTTP/1.1
Host: badges.decentraland.org
Accept: */*

{
  "data": {
    "latestAchievedBadges": [
      {
        "id": "traveler",
        "name": "Traveler",
        "tierName": "Bronze",
        "image": "https://badges.decentraland.org/assets/traveler-bronze-2d.png"
      }
    ]
  }
}