Project Votes

Cast a vote for a listings project

post

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

projectIdinteger · max: 2147483647Required

Body

application/json

voteTypestring · enumRequiredPossible values:

amountintegerRequired

voteReasonstring · min: 1 · max: 50Optional

Responses

200

Successful response

application/json

successbooleanRequired

messagestring · min: 1Required

400

Invalid input data

application/json

401

Authorization not provided

application/json

403

Insufficient access

application/json

500

Internal server error

application/json

post

/projects/{projectId}/votes

HTTPcURLJavaScriptPython

POST /api/v2/projects/{projectId}/votes HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 53

{
  "voteType": "BULLISH",
  "amount": 1,
  "voteReason": "text"
}

{
  "success": true,
  "message": "text",
  "newBalance": {
    "bullishVotesRemaining": 1,
    "bearishVotesRemaining": 1,
    "bullishVotesSpent": 1,
    "bearishVotesSpent": 1,
    "allocationResetDate": "text"
  }
}

Get the current user's vote balance, optionally for a specific listings project and season

get

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

projectIdinteger · max: 2147483647Optional

yearintegerOptional

periodintegerOptional

Responses

200

Successful response

application/json

400

Invalid input data

application/json

401

Authorization not provided

application/json

403

Insufficient access

application/json

404

Not found

application/json

500

Internal server error

application/json

get

/projects/votes/balance

HTTPcURLJavaScriptPython

GET /api/v2/projects/votes/balance HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "balance": {
    "bullishVotesRemaining": 1,
    "bearishVotesRemaining": 1,
    "bullishVotesSpent": 1,
    "bearishVotesSpent": 1,
    "allocationResetDate": "text"
  },
  "projectHistory": {
    "bullishVotesSpent": 1,
    "bearishVotesSpent": 1
  }
}

Get paginated list of project voters with their vote statistics and totals

get

Time Scope Options (scope parameter):

• scope=global: All-time data from first vote to present

• scope=global-dates: Custom date range (requires startDate & endDate)

• scope=current-period: Current voting period (default - backend determines automatically)

• scope=period: Specific voting period (requires year & period)

Parameter Requirements by Scope:

• global: No additional parameters needed

• global-dates: Requires startDate and endDate (ISO date strings)

• current-period: No additional parameters needed (default)

• period: Requires year (number) and period (number)

Examples:

• All-time: GET /projects/123/voters?scope=global

• Date range: GET /projects/123/voters?scope=global-dates&startDate=2024-01-01&endDate=2024-12-31

• Current period: GET /projects/123/voters (default) or GET /projects/123/voters?scope=current-period

• Specific period: GET /projects/123/voters?scope=period&year=2024&period=3

Notes:

• End dates extending into the future are automatically capped to the current time

• Global scope uses all historical data for the project

Path parameters

projectIdinteger · max: 2147483647Required

Query parameters

orderBystring · enumOptionalDefault: scorePossible values:

orderDirectionstring · enumOptionalDefault: descPossible values:

sentimentstring · enumOptionalPossible values:

scopestring · enumOptionalDefault: current-periodPossible values:

startDatestringOptional

endDatestringOptional

yearintegerOptional

periodintegerOptional

limitinteger · max: 100OptionalDefault: 50

offsetnumberOptionalDefault: 0

Responses

200

Successful response

application/json

totalnumberRequired

limitnumberRequired

offsetnumberRequired

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get

/projects/{projectId}/voters

HTTPcURLJavaScriptPython

GET /api/v2/projects/{projectId}/voters HTTP/1.1
Host: api.ethos.network
Accept: */*

{
  "values": [
    {
      "user": {
        "id": 1,
        "profileId": 1,
        "displayName": "text",
        "username": "text",
        "avatarUrl": "https://example.com",
        "description": "text",
        "score": 1,
        "status": "ACTIVE",
        "userkeys": [
          "text"
        ],
        "xpTotal": 1,
        "xpStreakDays": 1,
        "xpRemovedDueToAbuse": true,
        "influenceFactor": 1,
        "influenceFactorPercentile": 1,
        "humanVerificationStatus": "REQUESTED",
        "validatorNftCount": 1,
        "links": {
          "profile": "https://example.com",
          "scoreBreakdown": "https://example.com"
        },
        "stats": {
          "review": {
            "received": {
              "negative": 1,
              "neutral": 1,
              "positive": 1
            }
          },
          "vouch": {
            "given": {
              "amountWeiTotal": 1,
              "count": 1
            },
            "received": {
              "amountWeiTotal": 1,
              "count": 1
            }
          }
        }
      },
      "bullishCount": 1,
      "bearishCount": 1,
      "totalVotes": 1,
      "firstVoteAt": "text",
      "lastVoteAt": "text",
      "bullishReasons": [
        {
          "voteReason": "text",
          "totalVotes": 1
        }
      ],
      "bearishReasons": [
        {
          "voteReason": "text",
          "totalVotes": 1
        }
      ]
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 1,
  "totals": {
    "totalVoters": 1,
    "totalBullishVoters": 1,
    "totalBearishVoters": 1,
    "totalBullishVotes": 1,
    "totalBearishVotes": 1
  }
}

Reallocate votes for all users (Admin only)

post

Operation Types:

• reset (default): Resets the voting period by advancing to the next period and allocating fresh votes

• reallocate: Allocates additional votes for the current period without advancing the period

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

operationTypestring · enumOptionalDefault: new_period_resetPossible values:

Responses

200

Successful response

application/json

allocationsCreatedintegerRequired

totalVotesAllocatedintegerRequired

usersAffectedintegerRequired

messagestring · min: 1Required

400

Invalid input data

application/json

401

Authorization not provided

application/json

403

Insufficient access

application/json

500

Internal server error

application/json

post

/projects/votes/reallocate

HTTPcURLJavaScriptPython

POST /api/v2/projects/votes/reallocate HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 36

{
  "operationType": "new_period_reset"
}

{
  "allocationsCreated": 1,
  "totalVotesAllocated": 1,
  "usersAffected": 1,
  "message": "text"
}

Get bulk user project vote totals with flexible time range support

get

Time Scope Options (scope parameter):

• scope=global: All-time data from first vote to present

• scope=global-dates: Custom date range (requires startDate & endDate)

• scope=current-period: Current voting period (default - backend determines automatically)

• scope=period: Specific voting period (requires year & period)

Parameter Requirements by Scope:

• global: No additional parameters needed

• global-dates: Requires startDate and endDate (ISO date strings)

• current-period: No additional parameters needed (default)

• period: Requires year (number) and period (number)

Examples:

• All-time: GET /projects/PROJECT_ID/bulk-totals?scope=global

• Date range: GET /projects/PROJECT_ID/bulk-totals?scope=global-dates&startDate=2024-01-01&endDate=2024-12-31

• Current period: GET /projects/PROJECT_ID/bulk-totals (default) or GET /projects/PROJECT_ID/bulk-totals?scope=current-period

• Specific period: GET /projects/PROJECT_ID/bulk-totals?scope=period&year=2024&period=3

Notes:

• End dates extending into the future are automatically capped to the current time

• Global scope uses all historical data for the project

Query parameters

projectIdinteger · max: 2147483647Required

profileIdsinteger[] · min: 1 · max: 100Required

scopestring · enumOptionalDefault: current-periodPossible values:

startDatestringOptional

endDatestringOptional

yearintegerOptional

periodintegerOptional

Responses

200

Successful response

application/json

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get

/projects/votes/bulk-totals

HTTPcURLJavaScriptPython

GET /api/v2/projects/votes/bulk-totals?projectId=1&profileIds=1 HTTP/1.1
Host: api.ethos.network
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": {
    "totalBullishVotes": 1,
    "totalBearishVotes": 1,
    "bullishReasons": [
      {
        "voteReason": "text",
        "totalVotes": 1
      }
    ],
    "bearishReasons": [
      {
        "voteReason": "text",
        "totalVotes": 1
      }
    ]
  }
}

Get project vote chart data with flexible time range and aggregation options

get

Time Scope Options (scope parameter):

• scope=global: All-time data from first vote to present

• scope=global-dates: Custom date range (requires startDate & endDate)

• scope=current-period: Current voting period (default - backend determines automatically)

• scope=period: Specific voting period (requires year & period)

Parameter Requirements by Scope:

• global: No additional parameters needed

• global-dates: Requires startDate and endDate (ISO date strings)

• current-period: No additional parameters needed (default)

• period: Requires year (number) and period (number)

Time Aggregation (bucket parameter):

• Available buckets: '1 minute', '5 minutes', '15 minutes', '30 minutes', '1 hour', '2 hours', '6 hours', '12 hours', '1 day', '1 week', '1 month'

• If bucket is omitted, the API auto-selects an optimal bucket size based on the time range to prevent excessive data points

• For large time spans with small buckets, an error will be returned with a suggested larger bucket

• Maximum data points: 2000 (for performance)

Examples:

• All-time: GET /projects/123/chart?scope=global

• Date range: GET /projects/123/chart?scope=global-dates&startDate=2024-01-01&endDate=2024-12-31

• Current period: GET /projects/123/chart (default) or GET /projects/123/chart?scope=current-period

• Specific period: GET /projects/123/chart?scope=period&year=2024&period=3

Notes:

• End dates extending into the future are automatically capped to the current time

• Global scope uses all historical data for the project

Path parameters

projectIdinteger · max: 2147483647Required

Query parameters

bucketstring · enumOptionalPossible values:

scopestring · enumOptionalDefault: current-periodPossible values:

startDatestringOptional

endDatestringOptional

yearintegerOptional

periodintegerOptional

Responses

200

Successful response

application/json

timeBucketstringRequired

totalBullishVotesinteger · int64Optional

totalBearishVotesinteger · int64Optional

bullishVotesinteger · int64Optional

bearishVotesinteger · int64Optional

uniqueVotersinteger · int64Optional

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get

/projects/{projectId}/chart

HTTPcURLJavaScriptPython

GET /api/v2/projects/{projectId}/chart HTTP/1.1
Host: api.ethos.network
Accept: */*

[
  {
    "timeBucket": "text",
    "totalBullishVotes": 1,
    "totalBearishVotes": 1,
    "bullishVotes": 1,
    "bearishVotes": 1,
    "uniqueVoters": 1
  }
]