Passport API v1 -- API Reference

The Passport API enables developers to retrieve Passport XYZ scores and Stamp metadata for users who have created a 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 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.

Requests made to the Passport API v1 and v2 count towards the same rate limit.

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

Key concepts

There are several key concepts you should be aware of when using the Passport API:

• Timeouts: The Passport API endpoints have 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.
• Pagination: Some requests return a large amount of data. To effectively retrieve this data, you will need to paginate the response. For more information, see API pagination.
• 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
   GET /registry/signing-message
2. Submit and retrieve latest score for a single address
   POST /registry/submit-passport
3. Retrieve previously submitted score for a single address
   GET /registry/score/{scorer_id}/{address}
4. Retrieve previously submitted scores of all submitted addresses
   GET /registry/score/{scorer_id}

Use the following endpoints to receive Stamps data:

• Retrieve Stamps verified by a single address
  GET /registry/stamps/{address}
• Retrieve all Stamps available in Passport GET /registry/stamp-metadata

Use the following endpoint to receive staking information

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

Retrieve a signing message

This optional 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 Passport XYZ from Ceramic.\n\nNonce: {Nonce}\n",
    "nonce": "{Nonce}"
}

Submit and retrieve latest score for a single address

This is the primary endpoint that integrators should use.

This endpoint will submit the Passport to the scorer, and return the latest score and Stamp data for a single address. It will always return the most updated score and Stamp data, so resubmitting a user's address will refresh their score.

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": "{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"
      ...
    }
}

Retrieve previously submitted score for a single address

You must submit a Passport to be scored via the Submit for scoring endpoint before successfully receiving that score via this endpoints.

Use this endpoint to retrieve the last submitted score for one Ethereum address.

You can use the multiple address endpoint if you'd like to retrieve the latest submitted scores for all addresses that have been submitted to the scorer using the POST endpoint.

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 resubmit/refresh the address's score.

Retrieve previously submitted scores of all submitted addresses

You must submit a Passport to be scored via the Submit for scoring endpoint first.

Use this endpoint to retrieve the last submitted score for all Ethereum addresses that have been submitted (POST endpoint) to your scorer.

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 last submitted scores for a given address based on the timeperiod that you submitted their address to the scorer.

The two possible query parameters are last_score_timestamp_gt and last_score_timestamp_gte.

• last_score_timestamp_gt (standing for 'greater than'): This parameter returns the address' last submitted scores that were submitted to your scorer instance after the specified time.
• last_score_timestamp_gt (standing for 'greater than or equal'): This parameter returns the address' last submitted scores that were submitted to your scorer instance after or at the same time as the specified time.

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}'

Retrieve Stamps verified by a single address

Use this endpoint to request all Stamps that have been verified by the specified 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": {}
    }
  ]
}

Retrieve all Stamps available in Passport

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"
          }
        ]
      }
    ]
  }
]

Retrieve GTC staking amounts

This endpoint has been deprecated, as it was built around the legacy GTC staking application.

We are planning on releasing a new version of the GTC staking endpoint. Please fill out the following form to help us prioritize this new endpoint in our roadmap:

https://forms.gle/VbDBNTvb99emaSUV9 (opens in a new tab)

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).