API Reference

The Passport API enables developers to retrieve Passport scores and Stamp metadata for users who have created a Gitcoin Passport.

You can also experiment with the Passport API using our API playground tool (opens in a new tab) and adding your API keys via the 'Authorize' button.

Authentication

To access the Gitcoin Passport API, you will need a Scorer ID and an API key.

To make a successful request, you will need to include your API key in the "Authorization" header of each API request. The header should have the following format:

"X-API-KEY: {API_key}"

Replace {API_key} with your API key. For example, if you were using cURL, your request might look something like this:

curl --request GET 'https://api.scorer.gitcoin.co/registry/signing-message' \
    --header 'X-API-KEY: VwUi___.0yQU1HIAE4hLEMkVs___'

Rate limits

Your API key will allow you to make up to a certain number of requests to any of the endpoints included on this page during a certain period of time.

You will start off with Tier 1, and will need to request higher rate limits (opens in a new tab) if necessary.

Timeouts

The load balancer for all Passport API endpoints has a timeout of 60 seconds. This means that if a request to one of these endpoints does not receive a response within 60 seconds, the request will be aborted.

If your request times out, you should set up retry logic by calling the API again after a short delay, typically increasing the delay for each subsequent retry.

However, it is important to mention that you should not implement retry logic when making requests to the Submit for scoring endpoint. Even if your request times out, the scoring process should still be in progress.

Pagination

Some requests are likely to return a large amount of data. You can paginate it by adding ?limit=<x>, where x is the number of elements of the dataset you wish to return in each response, to the end of the request. This instructs the server to only send x "pages" of the response.

For the Stamps endpoint, x refers to the number of Stamp objects to return in each response. The full request to the Stamp endpoint, including the pagination instruction and headers, could look as follows:

curl --request GET 'https://api.scorer.gitcoin.co/registry/stamps/{address}?limit=3' \
  --header 'X-API-KEY: {API-KEY}'

In this example, the API will return three Stamps in each response.

To help you navigate, the returned data includes values in the prev and next fields. These are endpoint URLs with pre-filled query parameters you can use to retrieve the previous or next chunk of data. Note that if you request a limit of 3, your next value is also going to have a limit of 3. For example, if the response contains Stamps 4, 5 and 6, the URL in prev will return Stamps 1, 2, and 3. The URL in next will return Stamps 7, 8, and 9.

This is what a response looks like with the next and prev fields. Notice these fields values are endpoint URLs.

{
  "next": "https://api.scorer.gitcoin.co/registry/stamps/{address}?token=bmVw%4dFNQ9fM3TcxMTcD%3D&limit=3",
  "prev": "https://api.scorer.gitcoin.co/registry/stamps/{address}?token=c9fMTcHJlTcwdlxMNQ%3D%3D&limit=3",
  "items": [
    {
      "version": "1.0.0",
      "credential": {...}
    }
  ]
}

To retrieve the next page of results you can use the URL provided in the next field, in this case:

curl --request GET 'https://api.scorer.gitcoin.co/registry/stamps/{address}?token=bmVw%4dFNQ9fM3TcxMTcD%3D&limit=3' \
  --header 'X-API-KEY: {API-key}'

You can also use the offset parameter to retrieve data from a given location in a paginated API response. The offset value given identifies the first element in the response you want to retrieve. For example, passing offset=5 means the response will skip the first 5 elements and start at element 6 of the returned data. You can combine this with limit to get specific chunks of data, for example to retrieve objects 6 - 10, you could pass offset=5&limit=5.

Here's what that would look like in practice, retrieving the 6th to 10th Stamps for a given address:

curl --request GET 'https://api.scorer.gitcoin.co/registry/stamps/{address}?offset=5&limit=5' \
  --header 'X-API-KEY: {API-key}' 

Data dictionary

We have put together a data dictionary that you can use to better understand each field that delivers with the response payloads from the Passport API endpoints.

Available endpoints

To get a Passport score from an ETH address, follow these steps:

1. Optional: Retrieve a signing message from the Scorer
   GET /registry/signing-message
2. Submit the Ethereum address to the Scorer
   POST /registry/submit-passport
3. Retrieve the Passport score for a single address
   GET /registry/score/{scorer_id}/{address}
4. Retrieve the Passport scores of all submitted addresses
   GET /registry/score/{scorer_id}

Use the following endpoints to receive Stamps data:

• Receive Stamps connected to one or multiple submitted Passports
  GET /registry/stamps/{address}
• Receive all Stamps available in Passport [Beta]
  GET /registry/stamp-metadata

Use the following endpoint to receive staking information

• Receive GTC staking amounts GET /registry/gtc-stake/{address}

Retrieve a signing message

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

curl --request GET \
    --url https://api.scorer.gitcoin.co/registry/signing-message \
    --header 'X-API-KEY: {API KEY}'

{
    "message": "I hereby agree to submit my address in order to score my associated Gitcoin Passport from Ceramic.\n\nNonce: {Nonce}\n",
    "nonce": "{Nonce}"
}

Submit for scoring

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.

There are two different values that deliver with the status field:

• PROCESSING - Continue to poll for the results using the GET scores endpoint until the DONE status is returned. score field will return as null.
• DONE - The Scorer has completed scoring the specified Passport. score field will return with Passport score.

Refreshing scores

The score displayed in the Passport app is refreshed automatically, whenever the user makes any change to their Passport. However, API users may find the scores returned by the API sometimes differs from the score displayed in the app. If this happens, refresh the Passport score by making a POST request to submit-passport.

POST /registry/submit-passport

JSON body parameters

curl --request POST \
  --url https://api.scorer.gitcoin.co/registry/submit-passport \
  --header 'X-API-KEY: {API KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "address": "{ADDRESS}",
    "scorer_id": "{SCORER ID}",
    "signature": "{SIGNATURE - OPTIONAL)",
    "nonce": "{NONCE - OPTIONAL}"
  }'

Sample responses

The name in the parenthesis represents what type of Scorer you are using.

{
    "address": "{address}",
    "score": null,
    "status": "PROCESSING",
    "last_score_timestamp": "{timestamp}",
    "expiration_date": "{expiration_time}",
    "evidence": null,
    "error": null,
    "stamp_scores": {
      "Ens": "2.2",
      "NFT": "0.69",
      "Google": "2.25"
      ...
    }
}

{
    "address": "{address}",
    "score": "{score}",
    "status": "DONE",
    "last_score_timestamp": "{last_score_time}",
    "expiration_date": "{expiration_time}",
    "evidence": null,
    "error": null,
    "stamp_scores": {
      "Ens": "2.2",
      "NFT": "0.69",
      "Google": "2.25"
      ...
    }
}

{
    "address": "{address}",
    "score": "{score}",
    "status": "DONE",
    "last_score_timestamp": "{timestamp}",
    "expiration_date": "{expiration_time}",
    "evidence": {
        "type": "ThresholdScoreCheck",
        "success": true,
        "rawScore": "{score}",
        "threshold": "15.00000"
    },
    "error": null,
    "stamp_scores": {
      "Ens": "2.2",
      "NFT": "0.69",
      "Google": "2.25"
      ...
    }
}

Get score of a single address

You must submit any Passports you'd like to request a score for via the Submit for scoring endpoint before successfully receiving a score via this endpoints.

Use this endpoint to retrieve the score for one Ethereum address. You can use the multiple address endpoint if you have more than one address submitted to a Scorer.

GET /registry/score/{scorer_id}/{address}

curl --request GET \
    --url https://api.scorer.gitcoin.co/registry/score/{scorer_id}/{address} \
    --header 'X-API-KEY: {API KEY}'

{
  "items": [
      {
          "address": "{wallet}",
          "score": "{score}",
          "status": "DONE",
          "last_score_timestamp": "{timestamp}",
          "expiration_date": "{expiration_time}",
          "evidence": null,
          "error": null,
          "stamp_scores": {
            "Ens": "2.2",
            "NFT": "0.69",
            "Google": "2.25"
            ...
          }
      }
  ]
}        

API users may find the scores returned by registry/score sometimes differs from the score displayed in the app. If this happens, simply refresh the Passport score by making a POST request to submit-passport.

Get scores of all submitted addresses

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 this endpoints.

Use this endpoint to retrieve the score for one Ethereum address. You can use the single address endpoint if you'd like to request a score for one address.

GET /registry/score/{scorer_id}

Query parameters

curl --request GET \
    --url https://api.scorer.gitcoin.co/registry/score/{scorer_id} \
    --header 'X-API-KEY: {API KEY}'

{
    "items": [
        {
            "address": "{wallet}",
            "score": "{score}",
            "status": "DONE",
            "last_score_timestamp": "{timestamp}",
            "expiration_date": "{expiration_time}",
            "evidence": null,
            "error": null,
            "stamp_scores": {
              "Ens": "2.2",
              "NFT": "0.69",
              "Google": "2.25"
              ...
            }
        },
        {
            "address": "{wallet}",
            "score": "{score}",
            "status": "DONE",
            "last_score_timestamp": "{timestamp}",
            "expiration_date": "{expiration_time}",
            "evidence": null,
            "error": null,
            "stamp_scores": {
              "Ens": "2.2",
              "NFT": "0.69",
              "Google": "2.25"
              ...
            }
        }
    ],
    "count": 2
}

You can also add a query to return all the scores for a given address for a certain time period. This can be useful if you want to filter your responses so that it only returns scores that have been updated since your last request.

The two possible query parameters are last_score_timestamp_gt and last_score_timestamp_gte. The difference between the two is that _gt (standing for 'greater than') returns updated scores that were created by your scorer instance strictly after the given time, whereas _gte (standing for 'greater than or equal') returns updated scores after or at the same time as the given time.

The argument should be provided in ISO 8601 (opens in a new tab) format.

For example:

curl --request GET \
    --url https://api.scorer.gitcoin.co/registry/score/{scorer_id}?address={address}?last_score_timestamp_get=2023-07-20T19%3A54%3A44.463335%2B00%3A00 \
    --header 'X-API-KEY: {API KEY}'

Also note that because Stamp deduplication is achieved using a 'last in, first out' model, it is possible for Passports with identical Stamps to return different scores from different Scorers. The reason is that if the identical passports A and B are submitted to Scorer 1 in the order A,B, the returned score could be different to the same Passports submitted to Scorer 2 in the order B,A, because different instances of duplicate Stamps would be removed.

Get Stamps

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}

Query parameters

curl --request GET \
    --url 'https://api.scorer.gitcoin.co/registry/stamps/{address}?include_metadata=true' \
    --header 'X-API-KEY: {API KEY}'

{
  "next": "string",
  "prev": "string",
  "items": [
    {
      "version": "string",
      "credential": {},
      "metadata": {}
    }
  ]
}

Get Stamps metadata [Beta]

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

curl --request GET \
    --url https://api.scorer.gitcoin.co/registry/stamp-metadata \
    --header 'X-API-KEY: {API KEY}'

[
  {
    "id": "string",
    "icon": "string",
    "name": "string",
    "description": "string",
    "connectMessage": "string",
    "groups": [
      {
        "name": "string",
        "stamps": [
          {
            "name": "string",
            "description": "string",
            "hash": "string"
          }
        ]
      }
    ]
  }
]

Receive GTC staking amounts

This endpoint returns both self (stakes) and community (xstakeAggregates) staking amounts for a specified address and round. It also breaks down staking amounts based on round ID.

Our round IDs correspond to the different Gitcoin Grants rounds, and can be found at the following link: Round IDs (opens in a new tab)

GET /registry/gtc-stake/{address}/{round_id}

curl --request GET \
    --url https://api.scorer.gitcoin.co/registry/gtc-stake/{address}/{round_id} \
    --header 'X-API-KEY: {API KEY}'

{
  "users": [
    {
      "stakes": [
        {
          "stake": "string",
          "round": {
            "id": "string"
          }
        },
        {
          "stake": "string",
          "round": {
            "id": "string"
          }
        }
      ],
      "xstakeAggregates": [
        {
          "total": "string",
          "round": {
            "id": "string"
          }
        }
      ]
    }
  ]
}

If you have questions about the API you can ask them in our developer support channel (opens in a new tab).