Scores

Overview

The Scores API allows you to query and analyze credibility scores in the Ethos network. Scores represent a user's trustworthiness and reputation based on their activity, reviews, vouches, and other factors. The API provides endpoints for retrieving individual scores, score history, comparing scores, and even simulating changes to a score.

Endpoints

Get Score

GET /api/v1/score/:userkey

Description: Retrieves the credibility score for a specific user.

Authentication Required: No

Parameters

Path Parameters

Name	Type	Required	Description
userkey	string	Yes	The userkey for the user. Can be in the format of "profileId:123", "address:0x1234...", or "service:x.com:username:vitalii"

Query Parameters

Name	Type	Required	Description
txHash	string	No	Transaction hash to retrieve a historical score associated with a specific transaction

Responses

Success Response

Code: 200 OK

{
  "ok": true,
  "data": {
    "score": 1711,
    "elements": {
      "Ethereum Address Age": {
        "element": {
          "name": "Ethereum Address Age",
          "type": "LookupInterval",
          "ranges": [
            {"end": 90, "score": 0},
            {"start": 90, "end": 365, "score": 1},
            {"start": 365, "end": 1461, "score": 3},
            {"start": 1461, "end": 2922, "score": 5},
            {"start": 2922, "score": 5}
          ],
          "outOfRangeScore": 0
        },
        "raw": 0,
        "weighted": 0,
        "error": false
      },
      "Twitter Account Age": {
        "element": {
          "name": "Twitter Account Age",
          "type": "LookupInterval",
          "ranges": [
            {"start": 0, "end": 90, "score": -250},
            {"start": 90, "end": 365, "score": -50},
            {"start": 365, "end": 730, "score": 0},
            {"start": 1461, "score": 5}
          ],
          "outOfRangeScore": 0
        },
        "raw": 1178,
        "weighted": 0,
        "error": false
      },
      "Number of Vouchers Impact": {
        "element": {
          "name": "Number of Vouchers Impact",
          "type": "LookupNumber",
          "range": {"min": 0, "max": 270}
        },
        "raw": 94,
        "weighted": 94,
        "error": false
      },
      "Vouched Ethereum Impact": {
        "element": {
          "name": "Vouched Ethereum Impact",
          "type": "LookupNumber",
          "range": {"min": 0, "max": 270}
        },
        "raw": 223,
        "weighted": 223,
        "error": false
      },
      "Review Impact": {
        "element": {
          "name": "Review Impact",
          "type": "LookupNumber",
          "range": {"min": -800, "max": 270}
        },
        "raw": 193,
        "weighted": 193,
        "error": false
      }
    },
    "metadata": {},
    "errors": []
  }
}

Property	Type	Description
ok	boolean	Success status
data	object	Score data
data.score	number	Overall credibility score (ranging from 0-2800)
data.elements	object	Detailed information about each score component
data.elements[elementName]	object	Information about a specific score element
data.elements[elementName].element	object	Definition of the score element
data.elements[elementName].element.name	string	Element name
data.elements[elementName].element.type	string	Element type (LookupInterval or LookupNumber)
data.elements[elementName].element.ranges	array	For LookupInterval: ranges with start, end and score values
data.elements[elementName].element.range	object	For LookupNumber: min and max range values
data.elements[elementName].raw	number	Raw score value for this element
data.elements[elementName].weighted	number	Weighted contribution to the final score
data.elements[elementName].error	boolean	Whether there was an error calculating this element
data.metadata	object	Additional metadata about the score calculation
data.errors	array	Names of elements that had errors during calculation

Error Responses

Code: 404 Not Found

{
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Score not found"
  }
}

{
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Attestation account not found"
  }
}

{
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Score for transaction not found"
  }
}

Example

Request

http GET https://api.ethos.network/api/v1/score/profileId:1

Response

{
  "ok": true,
  "data": {
    "score": 1711,
    "elements": {
      "Ethereum Address Age": {
        "element": {
          "name": "Ethereum Address Age",
          "type": "LookupInterval",
          "ranges": [
            {"end": 90, "score": 0},
            {"start": 90, "end": 365, "score": 1},
            {"start": 365, "end": 1461, "score": 3},
            {"start": 1461, "end": 2922, "score": 5},
            {"start": 2922, "score": 5}
          ],
          "outOfRangeScore": 0
        },
        "raw": 0,
        "weighted": 0,
        "error": false
      },
      "Number of Vouchers Impact": {
        "element": {
          "name": "Number of Vouchers Impact",
          "type": "LookupNumber",
          "range": {"min": 0, "max": 270}
        },
        "raw": 94,
        "weighted": 94,
        "error": false
      }
    },
    "metadata": {},
    "errors": []
  }
}

Notes

• Ethos credibility scores range from 0-2800 and are categorized into levels:

  • Untrusted: 0-799

  • Questionable: 800-1199

  • Neutral: 1200-1599

  • Reputable: 1600-1999

  • Exemplary: 2000-2800

• The response includes detailed information about each component that contributes to the final score.

• The elements object contains various factors like account age, review impact, voucher count, etc.

• Each element includes its raw score, weighted contribution, and metadata about how it was calculated.

• If a user has no historical data for a particular element, it may show a raw score of 0.

---

Simulate Score Changes

POST /api/v1/score/simulate

Description: Simulates how various actions would affect a user's credibility score.

Authentication Required: No

Parameters

Request Body

{
  "subjectKey": "profileId:1",
  "vouchAmount": 1.5,
  "numberOfVouchers": 2
}

Property	Type	Required	Description
subjectKey	string	Yes	Userkey of the subject to simulate the score for
twitterUserId	string	No	Twitter user ID to simulate account age impact
reviews	array of objects	No	Array of reviews to simulate
reviews[].author	string	Yes	Address of the review author
reviews[].score	string	Yes	Review score: "positive", "neutral", or "negative"
vouchAmount	number	No	Amount of ETH to simulate being vouched
vouchedDays	number	No	Number of days to simulate the vouch for (default: maximum allowed)
numberOfVouchers	number	No	Number of vouchers to simulate
votes	object	No	Votes to simulate
votes.review	object	No	Votes on reviews
votes.review.upvotes	number	Yes	Number of upvotes on reviews
votes.review.downvotes	number	Yes	Number of downvotes on reviews
votes.vouch	object	No	Votes on vouches
votes.vouch.upvotes	number	Yes	Number of upvotes on vouches
votes.vouch.downvotes	number	Yes	Number of downvotes on vouches
slashes	array of objects	No	Slashes to simulate
slashes[].type	string	Yes	Type of slash: "SOCIAL" or "FINANCIAL"
slashes[].amount	number	Yes	Amount of the slash

Responses

Success Response

Code: 200 OK

{
  "ok": true,
  "data": {
    "simulation": {
      "value": 38.70023504412825,
      "relativeValue": 38.70023504412825,
      "impact": "POSITIVE",
      "adjustedRecipientScore": 1749.7002350441282
    },
    "calculationResults": {
      "score": 1749.7002350441282,
      "elements": {
        "Ethereum Address Age": {
          "element": {
            "name": "Ethereum Address Age",
            "type": "LookupInterval",
            "ranges": [
              {"end": 90, "score": 0},
              {"start": 90, "end": 365, "score": 1},
              {"start": 365, "end": 1461, "score": 3},
              {"start": 1461, "end": 2922, "score": 5},
              {"start": 2922, "score": 5}
            ],
            "outOfRangeScore": 0
          },
          "raw": 0,
          "weighted": 0,
          "error": false
        },
        "Twitter Account Age": {
          "element": {
            "name": "Twitter Account Age",
            "type": "LookupInterval",
            "ranges": [
              {"start": 0, "end": 90, "score": -250},
              {"start": 90, "end": 365, "score": -50},
              {"start": 365, "end": 730, "score": 0},
              {"start": 1461, "score": 5}
            ],
            "outOfRangeScore": 0
          },
          "raw": 463,
          "weighted": 0,
          "error": false
        },
        "Vouched Ethereum Impact": {
          "element": {
            "name": "Vouched Ethereum Impact",
            "type": "LookupNumber",
            "range": {"min": 0, "max": 270}
          },
          "raw": 253.3720080769059,
          "weighted": 253.3720080769059,
          "error": false
        },
        "Number of Vouchers Impact": {
          "element": {
            "name": "Number of Vouchers Impact",
            "type": "LookupNumber",
            "range": {"min": 0, "max": 270}
          },
          "raw": 102.85714285714285,
          "weighted": 102.85714285714285,
          "error": false
        }
      },
      "metadata": {},
      "errors": []
    },
    "errors": []
  }
}

Property	Type	Description
ok	boolean	Success status
data	object	Simulation results
data.simulation	object	Score change information
data.simulation.value	number	Absolute point change in score
data.simulation.relativeValue	number	Relative point change in score
data.simulation.impact	string	Impact type (e.g., "POSITIVE")
data.simulation.adjustedRecipientScore	number	New simulated score
data.calculationResults	object	Detailed calculation results
data.calculationResults.score	number	Total simulated score
data.calculationResults.elements	object	Detailed breakdown of score elements
data.errors	array	Names of elements that had errors during calculation

Error Responses

Code: 404 Not Found

{
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Failed to calculate subject score"
  }
}

{
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Twitter Profile not found"
  }
}

Example

Request

http POST https://api.ethos.network/api/v1/score/simulate \
  subjectKey="profileId:1" \
  vouchAmount:=1.5 \
  numberOfVouchers:=2

Response

{
  "ok": true,
  "data": {
    "simulation": {
      "value": 38.70023504412825,
      "relativeValue": 38.70023504412825,
      "impact": "POSITIVE",
      "adjustedRecipientScore": 1749.7002350441282
    },
    "calculationResults": {
      "score": 1749.7002350441282,
      "elements": {
        "Ethereum Address Age": {
          "element": {
            "name": "Ethereum Address Age",
            "type": "LookupInterval",
            "ranges": [
              {"end": 90, "score": 0},
              {"start": 90, "end": 365, "score": 1},
              {"start": 365, "end": 1461, "score": 3},
              {"start": 1461, "end": 2922, "score": 5},
              {"start": 2922, "score": 5}
            ],
            "outOfRangeScore": 0
          },
          "raw": 0,
          "weighted": 0,
          "error": false
        },
        "Number of Vouchers Impact": {
          "element": {
            "name": "Number of Vouchers Impact",
            "type": "LookupNumber",
            "range": {"min": 0, "max": 270}
          },
          "raw": 102.85714285714285,
          "weighted": 102.85714285714285,
          "error": false
        }
      },
      "metadata": {},
      "errors": []
    },
    "errors": []
  }
}

Notes

• You can simulate changes to a user's score by providing different parameters.

• The response includes both the projected score and a detailed breakdown of how each element contributed.

• The impact field indicates whether the changes would have a positive, negative, or neutral effect.

• Only include the parameters you want to simulate; omit others to keep them at their current values.

• The simulation doesn't affect the actual user's score - it's only a preview of potential changes.