Profiles

Overview

The Profiles API allows you to access user profile information within the Ethos network. It provides endpoints for querying individual profiles, recent profiles, directory listings, and various leaderboards.

Endpoints

XP Leaderboard

GET /api/v1/profiles/xp-leaderboard

Description: Returns profiles ranked by XP points in descending order.

Authentication Required: No

Parameters

Query Parameters

Name	Type	Required	Description
since	string	No	Only include XP earned since this date/time (ISO date format like '2023-01-01' or duration string like '1month')
limit	number	No	Number of results to return (defaults to 50)

Responses

Success Response

Code: 200 OK

{
  "ok": true,
  "data": [
    {
      "id": 19867,
      "profileId": 17,
      "displayName": "sketch",
      "username": "eskacie",
      "avatarUrl": "https://pbs.twimg.com/profile_images/1874244830190329858/IcrIFc6L.jpg",
      "description": "Design / Code / Create / Collect",
      "score": 1964,
      "status": "ACTIVE",
      "totalXp": 3521336,
      "userkeys": [
        "profileId:17",
        "address:0x5586d438BE5920143c0f9B179835778fa81a544a",
        "address:0x6f95934abc01eedA154C832dF4a4E210cAF877eb",
        "service:x.com:1461538142217912326"
      ]
    }
  ]
}

Property	Type	Description
ok	boolean	Success status
data	array	Array of user objects
data[].id	number	Unique user ID
data[].profileId	number	Profile ID
data[].displayName	string	User's display name
data[].username	string	User's username
data[].avatarUrl	string	URL to the user's avatar
data[].description	string	User's description
data[].score	number	User's credibility score
data[].status	string	User's status (ACTIVE or INACTIVE)
data[].userkeys	array	Array of userkeys associated with the user
data[].totalXp	number	Total XP points accumulated

Example

Request

http GET https://api.ethos.network/api/v1/profiles/xp-leaderboard since:='2023-01-01' limit:=5

Response

{
  "ok": true,
  "data": [
    {
      "id": 19867,
      "profileId": 17,
      "displayName": "sketch",
      "username": "eskacie",
      "avatarUrl": "https://pbs.twimg.com/profile_images/1874244830190329858/IcrIFc6L.jpg",
      "description": "Design / Code / Create / Collect",
      "score": 1964,
      "status": "ACTIVE",
      "totalXp": 3521336,
      "userkeys": [
        "profileId:17",
        "address:0x5586d438BE5920143c0f9B179835778fa81a544a",
        "address:0x6f95934abc01eedA154C832dF4a4E210cAF877eb",
        "service:x.com:1461538142217912326"
      ]
    }
  ]
}

Notes

• By default, results are sorted by total XP in descending order (highest first).

• Limited to the top 50 profiles by default.

• The since parameter can be specified either as an ISO date string (e.g., '2023-01-01') or as a duration string (e.g., '1month', '1week').

• When using the since parameter, the API returns only users who have earned XP during the specified period. If no users have earned XP in that period, an empty array is returned.

• Results are cached for 5 minutes for better performance.

• Certain profiles, such as the main Ethos Network profile and administrative profiles, are excluded from the leaderboard.