Attestations
Overview
The Attestations API allows you to query service verifications and attestations in the Ethos network. Attestations are proofs that a user owns a particular service account (like a Twitter account) or has verified a specific claim.
Endpoints
Query Attestations
POST /api/v1/attestations
Description: Retrieves attestations based on profile IDs, attestation hashes, or both.
Authentication Required: No
Parameters
Request Body
{
"profileIds": [1, 2, 3],
"attestationHashes": ["0x1234...", "0x5678..."],
"archived": false,
"orderBy": {
"createdAt": "desc"
},
"limit": 10,
"offset": 0
}
profileIds
array of numbers
No*
Array of profile IDs to filter by
attestationHashes
array of strings
No*
Array of attestation hashes to filter by
archived
boolean
No
Whether to include archived attestations
orderBy
object
No
Sorting options
orderBy.createdAt
string
No
Sort by creation date: "asc" or "desc"
orderBy.updatedAt
string
No
Sort by update date: "asc" or "desc"
limit
number
Yes
Number of results to return (maximum 100)
offset
number
Yes
Offset for pagination
*At least one of profileIds
or attestationHashes
must be provided.
Responses
Success Response
Code: 200 OK
{
"ok": true,
"data": {
"values": [
{
"hash": "0x1234...",
"profileId": 1,
"service": "x.com",
"account": "123456789",
"createdAt": 1735689600,
"updatedAt": 1735689600,
"archived": false
}
],
"limit": 10,
"offset": 0,
"total": 1
}
}
ok
boolean
Success status
data
object
Response data container
data.values
array
Array of attestation objects
data.values[].hash
string
Attestation hash
data.values[].profileId
number
Profile ID
data.values[].service
string
Service name (e.g., "x.com")
data.values[].account
string
Account ID on the service
data.values[].createdAt
number
Unix timestamp of when the attestation was created
data.values[].updatedAt
number
Unix timestamp of when the attestation was last updated
data.values[].archived
boolean
Whether the attestation is archived
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 attestationHashes or profileIds",
"fields": ["attestationHashes", "profileIds"]
}
}
Example
Request
http POST https://api.ethos.network/api/v1/attestations \
profileIds:='[1]' \
limit=10 \
offset=0
Response
{
"ok": true,
"data": {
"values": [
{
"hash": "0x1234567890123456789012345678901234567890123456789012345678901234",
"profileId": 1,
"service": "x.com",
"account": "123456789",
"createdAt": 1735689600,
"updatedAt": 1735689600,
"archived": false
}
],
"limit": 10,
"offset": 0,
"total": 1
}
}
Notes
By default, results are sorted by creation date in descending order (newest first).
The API enforces a maximum of 100 attestations that can be requested at once.
Query Extended Attestations
POST /api/v1/attestations/extended
Description: Retrieves attestations with extended information. Currently, this endpoint is optimized for X (Twitter) attestations by including additional Twitter profile information.
Authentication Required: No
Parameters
Request Body
{
"profileIds": [1, 2, 3],
"attestationHashes": ["0x1234...", "0x5678..."],
"archived": false,
"orderBy": {
"createdAt": "desc"
},
"limit": 10,
"offset": 0
}
profileIds
array of numbers
No*
Array of profile IDs to filter by
attestationHashes
array of strings
No*
Array of attestation hashes to filter by
archived
boolean
No
Whether to include archived attestations
orderBy
object
No
Sorting options
orderBy.createdAt
string
No
Sort by creation date: "asc" or "desc"
orderBy.updatedAt
string
No
Sort by update date: "asc" or "desc"
limit
number
Yes
Number of results to return (maximum 100)
offset
number
Yes
Offset for pagination
*At least one of profileIds
or attestationHashes
must be provided.
Responses
Success Response
Code: 200 OK
{
"ok": true,
"data": {
"values": [
{
"attestation": {
"hash": "0x1234...",
"id": 1,
"profileId": 1,
"service": "x.com",
"account": "123456789",
"createdAt": 1735689600,
"updatedAt": 1735689600,
"archived": false
},
"extra": {
"attestationHash": "0x1234...",
"id": "123456789",
"username": "twitterusername",
"name": "Twitter Display Name",
"biography": "Twitter bio",
"avatar": "https://pbs.twimg.com/profile_images/1234567890/image.jpg",
"followersCount": 1000,
"isBlueVerified": true,
"joinedAt": 1703222331000,
"website": "https://example.com"
}
}
],
"limit": 10,
"offset": 0,
"total": 1
}
}
ok
boolean
Success status
data
object
Response data container
data.values
array
Array of extended attestation objects
data.values[].attestation
object
Attestation object (same as in the basic query)
data.values[].attestation.id
number
Internal attestation ID
data.values[].attestation.hash
string
Attestation hash
data.values[].attestation.profileId
number
Profile ID
data.values[].attestation.service
string
Service name (e.g., "x.com")
data.values[].attestation.account
string
Account ID on the service
data.values[].attestation.createdAt
number
Unix timestamp of when the attestation was created
data.values[].attestation.updatedAt
number
Unix timestamp of when the attestation was last updated
data.values[].attestation.archived
boolean
Whether the attestation is archived
data.values[].extra
object
Additional information about the attestation
data.values[].extra.attestationHash
string
Hash of the attestation
data.values[].extra.id
string
Twitter user ID
data.values[].extra.username
string
Twitter username
data.values[].extra.name
string
Twitter display name
data.values[].extra.biography
string
Twitter bio
data.values[].extra.avatar
string
URL to the Twitter profile image
data.values[].extra.followersCount
number
Number of followers
data.values[].extra.isBlueVerified
boolean
Whether the account is Twitter Blue verified
data.values[].extra.joinedAt
number
Unix timestamp of when the account joined Twitter
data.values[].extra.website
string
Website URL from Twitter profile
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 attestationHashes or profileIds",
"fields": ["attestationHashes", "profileIds"]
}
}
Code: 404 Not Found
{
"ok": false,
"error": {
"code": "NOT_FOUND",
"message": "Attestation details not found"
}
}
Example
Request
http POST https://api.ethos.network/api/v1/attestations/extended \
profileIds:='[1]' \
limit=10 \
offset=0
Response
{
"ok": true,
"data": {
"values": [
{
"attestation": {
"hash": "0x1234567890123456789012345678901234567890123456789012345678901234",
"id": 1,
"profileId": 1,
"service": "x.com",
"account": "123456789",
"createdAt": 1735689600,
"updatedAt": 1735689600,
"archived": false
},
"extra": {
"attestationHash": "0x1234567890123456789012345678901234567890123456789012345678901234",
"id": "123456789",
"username": "twitterusername",
"name": "Twitter Display Name",
"biography": "Twitter bio",
"avatar": "https://pbs.twimg.com/profile_images/1234567890/image.jpg",
"followersCount": 1000,
"isBlueVerified": true,
"joinedAt": 1703222331000,
"website": "https://example.com"
}
}
],
"limit": 10,
"offset": 0,
"total": 1
}
}
Notes
Currently, this endpoint only provides extended information for X (Twitter) attestations.
For non-Twitter attestations, the extended information may be limited or not available.
The extended information includes the Twitter username, display name, bio, and profile image URL.
Last updated