# 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**

```json
{
  "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

```json
{
  "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**

```bash
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**

```json
{
  "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

```json
{
  "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**

```bash
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**

```json
{
  "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

```json
{
  "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**

```bash
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

```json
{
  "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**

```bash
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**

```json
{
  "target": "profileId:123"
}
```

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

#### Responses

**Success Response**

**Code**: 200 OK

```json
{
  "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**

```bash
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.ethos.network/api-documentation/api-v1-deprecated/vouches.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.