Endpoint Definition
To use the Gitcoin Scorer API to score an Ethereum address, you need to have a Scorer app configured, an associated Scorer ID, and your API keys.
To get a Passport score from an ETH address, follow these steps:
- 1.
- 2.
- 3.Retrieve the Passport score for one or multiple addresses
GET /registry/score/{scorer_id}/{address} GET /registry/score/{scorer_id}
You can also receive the specific Stamps data:
This endpoint returns a message verifying the agreement to submit a wallet address for scoring, and a
nonce that can be used to verify the authenticity of the signed message. You don't need to get a signature from this endpoint, but you do need a signature from the wallet you are scoring that proves that the user owns the wallet.
GET /registry/signing-message
Sample request
curl --location \
--request GET 'https://api.scorer.gitcoin.co/registry/signing-message' \
--header 'X-API-KEY: {API KEY}'
Sample response
1
{
2
"message": "I hereby agree to submit my address in order to score my associated Gitcoin Passport from Ceramic.\n\nNonce: {Nonce}\n",
3
"nonce": "{Nonce}"
4
}
Before receiving a Passport score, developers need to submit an Ethereum address to their Scorer.
To do so, developers need to POST the relevant Ethereum address and their Scorer ID to this endpoint.
POST /registry/submit-passport
Name | Type | Required | Description |
|---|---|---|---|
address | Text | Yes | The wallet address |
scorer_id | Text | Yes | The Scorer ID |
signature | Text | No | Signature received from the wallet |
nonce | Text | No | Nonce generated in the signing message. This is needed for requiring a signature before scoring. |
Sample Response
1
{
2
"address": "{address}",
3
"score": null,
4
"status": "PROCESSING",
5
"last_score_timestamp": "2023-02-03T12:08:21.735838+00:00",
6
"evidence": null,
7
"error": null
8
}
You must submit any Passports you'd like to request a score for via the Submit for scoring endpoint before successfully receiving their scores via these endpoints.
Use these endpoints to retrieve the score for one Ethereum address, or all Ethereum addresses that have been submitted to a Scorer.
To request the score of a specified address:
GET /registry/score/{scorer_id}/{address}
Sample request
curl --request GET 'https://api.scorer.gitcoin.co/registry/score/{scorer_id}/{address}' \
--header 'X-API-KEY: {API KEY}'
To request the scores for all addresses that have been submitted to a Scorer:
GET /registry/score/{scorer_id}
Sample request
curl --location --request GET 'https://api.scorer.gitcoin.co/registry/score/{scorer_id}' \
--header 'X-API-KEY: {API KEY}'
Sample response
1
{
2
"items": [
3
{
4
"address": "{wallet}",
5
"score": "{score}",
6
"status": "DONE",
7
"last_score_timestamp": "{timestamp}",
8
"evidence": null,
9
"error": null
10
},
11
{
12
"address": "{wallet}",
13
"score": "{score}",
14
"status": "DONE",
15
"last_score_timestamp": "{timestamp}",
16
"evidence": null,
17
"error": null
18
}
19
],
20
"count": 2
21
}
Use this endpoint to request all Stamps that have been connected to an Ethereum address.
If you would like to retrieve the metadata for all available Stamps, please use the Get Stamps metadata endpoint.
GET /registry/stamps/{address}
Name | Required | Text |
|---|---|---|
include_metadata | No | [Beta] Returns optional metadata object with additional details about connected Stamps. |
Sample request
curl --request GET 'https://api.scorer.gitcoin.co/registry/stamps/{address}?include_metadata=true' \
--header 'X-API-KEY: {API KEY}'
Sample response
{
"next": "string",
"prev": "string",
"items": [
{
"version": "string",
"credential": {},
"metadata": {}
}
]
}
Use this endpoint to request all Stamps available on Passport.
If you would like to retrieve just the Stamps that are connected to a specified Ethereum address, please use the Get Stamps endpoint.
GET /registry/stamp-metadata
Sample request
curl --request GET 'https://api.scorer.gitcoin.co/registry/stamp-metadata' \
--header 'X-API-KEY: {API KEY}'
Sample response
[
{
"id": "string",
"icon": "string",
"name": "string",
"description": "string",
"connectMessage": "string",
"groups": [
{
"name": "string",
"stamps": [
{
"name": "string",
"description": "string",
"hash": "string"
}
]
}
]
}
]
Last modified 1h ago