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

Query Profiles

POST /api/v1/profiles

Description: Retrieves profile information for the specified profile IDs or addresses.

Authentication Required: No

Parameters

Request Body

{
  "ids": [1, 2, 3],
  "addresses": ["0x1234...5678", "0xabcd...ef12"],
  "archived": false,
  "useCache": true,
  "limit": 10,
  "offset": 0
}

Property	Type	Required	Description
ids	array of numbers	No*	Array of numeric profile IDs to query (maximum 100)
addresses	array of strings	No*	Array of Ethereum addresses to query (maximum 100)
archived	boolean	No	Whether to include archived profiles
useCache	boolean	No	Whether to use cached results (defaults to true)
limit	number	Yes	Number of results to return (maximum 100)
offset	number	Yes	Offset for pagination

*At least one of ids or addresses must be provided.

Responses

Success Response

Code: 200 OK

{
  "ok": true,
  "data": {
    "values": [
      {
        "id": 1,
        "archived": false,
        "createdAt": 1737052979,
        "updatedAt": 1743189764,
        "invitesAvailable": 25,
        "invitedBy": 1
      }
    ],
    "limit": 10,
    "offset": 0,
    "total": 1
  }
}

Property	Type	Description
ok	boolean	Success status
data	object	Response data container
data.values	array	Array of profile objects
data.values[].id	number	Unique profile ID
data.values[].archived	boolean	Whether the profile is archived
data.values[].createdAt	number	Unix timestamp of when the profile was created
data.values[].updatedAt	number	Unix timestamp of when the profile was last updated
data.values[].invitesAvailable	number	Number of invites available to this profile
data.values[].invitedBy	number	ID of the profile that invited this user
data.limit	number	Number of results returned
data.offset	number	Current pagination offset
data.total	number	Total number of results matching the query

Error Responses

Code: 400 Bad Request

{
  "ok": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Must specify either ids or addresses",
    "fields": ["ids", "addresses"]
  }
}

Example

Request

http POST https://api.ethos.network/api/v1/profiles \
  ids:='[1]' \
  limit=10 \
  offset=0

Response

{
  "ok": true,
  "data": {
    "values": [
      {
        "id": 1,
        "archived": false,
        "createdAt": 1737052979,
        "updatedAt": 1743189764,
        "invitesAvailable": 25,
        "invitedBy": 1
      }
    ],
    "limit": 10,
    "offset": 0,
    "total": 1
  }
}

Notes

• The API enforces a maximum of 100 profiles that can be requested at once.

• Results are returned in descending order by creation date (newest first).

• For performance reasons, it's recommended to use the useCache parameter.

• Timestamps are returned in Unix epoch format (seconds since January 1, 1970).

---

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.