Vouches

Overview

The Vouches API allows you to query and analyze vouches in the Ethos network. Vouches represent a stake of Ethereum that one user places on another, indicating trust and confidence in that user. The API provides endpoints for retrieving vouches, getting vouch statistics, counting vouches, and more.

Endpoints

Query Vouches

POST /api/v1/vouches

Description: Retrieves vouches based on various filters such as IDs, author profile IDs, subject profile IDs, and more.

Authentication Required: No

Parameters

Request Body

{
  "ids": [1, 2, 3],
  "authorProfileIds": [123, 456],
  "subjectProfileIds": [789, 101],
  "subjectAddresses": ["0x1234...", "0x5678..."],
  "subjectAttestationHashes": ["0xabcd...", "0xef01..."],
  "archived": false,
  "duration": "90d",
  "orderBy": {
    "vouchedAt": "desc"
  },
  "limit": 10,
  "offset": 0
}

Property	Type	Required	Description
ids	array of numbers	No	Array of vouch IDs
authorProfileIds	array of numbers	No	Array of profile IDs of vouch authors
subjectProfileIds	array of numbers	No	Array of profile IDs of vouch subjects
subjectAddresses	array of strings	No	Array of Ethereum addresses of vouch subjects
subjectAttestationHashes	array of strings	No	Array of attestation hashes of vouch subjects
archived	boolean	No	Whether to include archived vouches
duration	string	No	Return vouches after this duration (e.g., “90d” for last 90 days)
orderBy	object	No	Sorting options
orderBy.balance or orderBy.vouchedAt or orderBy.updatedAt	string	No	Sort by field: “asc” or “desc”
limit	number	No	Number of results to return (default: 10, maximum 100)
offset	number	No	Offset for pagination (default: 0)

Responses

Success Response

Code: 200 OK

{
  "ok": true,
  "data": {
    "values": [
      {
        "id": 1,
        "authorProfileId": 123,
        "subjectProfileId": 789,
        "subjectAddress": "0x1234567890123456789012345678901234567890",
        "attestationHash": null,
        "staked": "2000000000000000000", // 2 ETH in wei
        "balance": "2000000000000000000",
        "vouchedAt": 1735689600,
        "updatedAt": 1735689600,
        "archivedAt": null,
        "archived": false,
        "mutualId": 2,
        "events": [
          {
            "id": 123,
            "txHash": "0x1234567890123456789012345678901234567890123456789012345678901234",
            "blockNumber": 12345678,
            "createdAt": 1735689500,
            "updatedAt": 1735689500
          }
        ],
        "attestationDetails": null
      }
    ],
    "limit": 10,
    "offset": 0,
    "total": 1
  }
}

Property	Type	Description
ok	boolean	Success status
data	object	Response data container
data.values	array	Array of vouch objects
data.values[].id	number	Vouch ID
data.values[].authorProfileId	number	Profile ID of the author
data.values[].subjectProfileId	number	Profile ID of the subject (if applicable)
data.values[].subjectAddress	string	Ethereum address of the subject (if applicable)
data.values[].attestationHash	string	Attestation hash of the subject (if applicable)
data.values[].staked	string	Amount of ETH staked in wei
data.values[].balance	string	Current balance of the vouch in wei
data.values[].vouchedAt	number	Unix timestamp of when the vouch was created
data.values[].updatedAt	number	Unix timestamp of when the vouch was last updated
data.values[].archivedAt	number	Unix timestamp of when the vouch was archived (if applicable)
data.values[].archived	boolean	Whether the vouch is archived
data.values[].mutualId	number	ID of the mutual vouch (if applicable)
data.values[].events	array	Blockchain events associated with the vouch
data.values[].attestationDetails	object	Details about the attestation (if applicable)
data.limit	number	Number of results returned
data.offset	number	Current pagination offset
data.total	number	Total number of results matching the query

Example

Request

http POST https://api.ethos.network/api/v1/vouches \
  subjectProfileIds:='[789]' \
  limit:=10 \
  offset:=0

Notes

• By default, results are sorted by vouch date in descending order (newest first).
• The API enforces a maximum of 100 vouches that can be requested at once.
• If a vouch references an attestation hash that corresponds to a Twitter account, the attestationDetails field will be populated.

---

Get Vouched Ethereum

POST /api/v1/vouches/vouched-ethereum

Description: Calculates the total amount of Ethereum vouched for a specific target.

Authentication Required: No

Parameters

Request Body

{
  "target": "profileId:123"
}

Property	Type	Required	Description
target	string	Yes	Userkey of the target (profileId, address, or service:x.com:username:username)

Responses

Success Response

Code: 200 OK

{
  "ok": true,
  "data": {
    "vouchedEth": 5.0
  }
}

Property	Type	Description
ok	boolean	Success status
data	object	Response data
data.vouchedEth	number	Total amount of ETH vouched for the target

Example

Request

http POST https://api.ethos.network/api/v1/vouches/vouched-ethereum \
  target="profileId:123"

Notes

• This endpoint calculates the total amount of ETH currently vouched for the target.

---

Get Most Credible Vouchers

POST /api/v1/vouches/most-credible-vouchers

Description: Retrieves the most credible users who have vouched for a specific target.

Authentication Required: No

Parameters

Request Body

{
  "userkey": "profileId:123",
  "limit": 4
}

Property	Type	Required	Description
userkey	string	Yes	Userkey of the target to find vouchers for
limit	number	No	Maximum number of vouchers to return (default: 4, max: 50)

Responses

Success Response

Code: 200 OK

{
  "ok": true,
  "data": [
    {
      "authorProfileId": 456,
      "vouchId": 1,
      "score": 90
    },
    {
      "authorProfileId": 789,
      "vouchId": 2,
      "score": 85
    }
  ]
}

Property	Type	Description
ok	boolean	Success status
data	array	Array of credible voucher information
data[].authorProfileId	number	Profile ID of the voucher
data[].vouchId	number	ID of the vouch
data[].score	number	Credibility score of the voucher

Example

Request

http POST https://api.ethos.network/api/v1/vouches/most-credible-vouchers \
  userkey="profileId:123" \
  limit:=5

Notes

• The vouchers are sorted by their credibility score in descending order.
• Only active (non-archived) vouches are considered.

---

Get Mutual Vouchers

GET /api/v1/vouches/mutual-vouchers

Description: Retrieves a list of users who have mutual vouches with the specified target.

Authentication Required: No

Parameters

Query Parameters

Name	Type	Required	Description
userkey	string	Yes	Userkey of the target to find mutual vouchers for
limit	number	No	Maximum number of results to return (default: 10)

Responses

Success Response

Code: 200 OK

{
  "ok": true,
  "data": [
    {
      "profileId": 456,
      "outgoingVouchId": 1,
      "incomingVouchId": 2,
      "vouchedEth": 1.5
    },
    {
      "profileId": 789,
      "outgoingVouchId": 3,
      "incomingVouchId": 4,
      "vouchedEth": 1.0
    }
  ]
}

Property	Type	Description
ok	boolean	Success status
data	array	Array of mutual voucher information
data[].profileId	number	Profile ID of the mutual voucher
data[].outgoingVouchId	number	ID of the outgoing vouch (from target to voucher)
data[].incomingVouchId	number	ID of the incoming vouch (from voucher to target)
data[].vouchedEth	number	Amount of ETH in the mutual vouch

Example

Request

http GET https://api.ethos.network/api/v1/vouches/mutual-vouchers?userkey=profileId:123&limit=5

Notes

• Mutual vouches are pairs of vouches where two users have vouched for each other.
• Only active (non-archived) vouches are considered.

---

Get Vouch Rewards

POST /api/v1/vouches/rewards

Description: Calculates the rewards earned from vouches for a specific target.

Authentication Required: No

Parameters

Request Body

{
  "target": "profileId:123"
}

Property	Type	Required	Description
target	string	Yes	Userkey of the target to calculate rewards for

Responses

Success Response

Code: 200 OK

{
  "ok": true,
  "data": {
    "earned": 0.05,
    "potentialEarnings": 0.08,
    "totalStaked": 5.0
  }
}

Property	Type	Description
ok	boolean	Success status
data	object	Vouch rewards data
data.earned	number	Total ETH earned from vouches
data.potentialEarnings	number	Potential additional earnings from vouches
data.totalStaked	number	Total ETH staked in vouches

Example

Request

http POST https://api.ethos.network/api/v1/vouches/rewards \
  target="profileId:123"

Notes

• Rewards are earned based on the protocol’s reward distribution mechanism.
• Potential earnings represent the additional rewards that could be earned in the future from existing vouches.