Quick Start

This page will get you up and running with the Passport API. You will come away with the following:

How to prepare a Passport for scoring on the Passport XYZ server
How to retrieve Passport scores

Please make sure to follow the instructions on our Getting access page before working through this guide.

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.

API basics

The base URL for the API methods we'll be using is https://api.scorer.gitcoin.co/. There are several API endpoints that can be accessed by extending this base URL.

You can browse the API details in the API reference.

You will also need to include some header information. Both GET and POST requests require your API key. POST requests also require the payload type to be defined. It is always application/json.

How to retrieve a score

There is one basic step to retrieving a Passport score. All you have to do is submit a Passport to your Scorer instance. This triggers the Scorer instance to calculate a score for the specified address, and delivers their most recent score data.

Submitting and retrieving a Passport score

The following endpoint is used to submit and retrieve a Passport.

https://api.scorer.gitcoin.co/registry/submit-passport

This endpoint receives HTTP POST requests with the address to be scored and the scorer_id in the payload. An example POST request that submits address 0x2C1E111d7C3adc823B5fA3af3f07EB62831C3c5 to Scorer 100 looks as follows:

Sample request

curl -X POST 'https://api.scorer.gitcoin.co/registry/submit-passport' \
--data '{"address":"0x2C1E111d7C3adc823B5fA3af3f07EB62831C3c5","scorer_id":"100"}' \ 
-H "Content-Type: application/json" \ 
-H 'X-API-KEY: {your-api-key}'

The response from this endpoint should look as follows:

Sample response

{
    "address": "0x2C1E111d7C3adc823B5fA3af3f07EB62831C3c5",
    "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"
    }
}

This response indicates that the address was successfully submitted and delivers the calculated score in the score field of the returned object.

Typically, the score is compared to a threshold that determines whether a user is given access to some resource. We strongly recommend using a score threshold of 20.

Next Steps

Now you have seen how to retrieve a Passport score from the Passport XYZ server, you can start building this into your apps.

Check out our tutorials or API reference pages to learn how to build with Passport.

You can also ask questions in our developer support channel on Telegram (opens in a new tab).

Getting access Tutorials