Building with Passport
Passport API v2
API reference

Passport API v2 -- API Reference

Please note:
Passport API v2 simplifies and adds key functionality that wasn't previously available with Passport API v1. Because of this, it is recommended for you to use Passport API v2 moving forward.

We have not announced any deprecation or retirement timelines for v1 yet, and plan to provide more details before the end of 2024.

You can learn more about the differences between v1 and v2 via our migration guide.

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.

In the examples below, replace the following placeholder values with your actual data:

  • {scorer_id} - Your Scorer ID from the developer portal
  • {address} - The Ethereum address you want to score
  • {API_key} - Your API key from the developer portal

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.passport.xyz/v2/stamps/{scorer_id}/score/{address}' \
    --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.

Access starts with Tier 1. If you need an elevation, please request higher rate limits (opens in a new tab).

TierRate limit
Tier 1125 requests per 15 minutes
Tier 2350 requests per 15 minutes
Tier 32000 requests per 15 minutes
Tier 42000+ requests per 15 minutes

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: For definitions of the data types used in Passport API v2, see the Data dictionary page.

Available endpoints

Passport API v2 base URL: https://api.passport.xyz (opens in a new tab)

Endpoint actionEndpoint
Retrieve latest score for a single addressGET /v2/stamps/{scorer_id}/score/{address}
Retrieve historical score for a single addressGET /v2/stamps/{scorer_id}/score/{address}/history
Retrieve Stamps verified by a single addressGET /v2/stamps/{address}
Retrieve all Stamps available in PassportGET /v2/stamps/metadata

Retrieve latest score for a single address

This is the primary endpoint that integrators should use.

This endpoint will return the latest score and Stamp data for a single address.

GET /v2/stamps/{scorer_id}/score/{address}

Sample request
curl --request GET \
  --url https://api.passport.xyz/v2/stamps/{scorer_id}/score/{address} \
  --header 'X-API-KEY: {API KEY}'
Sample response
{
  "address": "{address}",
  "score": "{overall_score}",
  "passing_score": true/false,
  "last_score_timestamp": "{last_score_time ISO 8601}",
  "expiration_timestamp": "{expiration_time ISO 8601}",
  "threshold": "20",
  "error": null,
  "stamps": {
    "Ens": {
      "score": "{credential_score}",
      "dedup": true/false,
      "expiration_date": "{expiration_time ISO 8601}"
    },
    "ETHDaysActive#50": {
      "score": "{credential_score}",
      "dedup": true/false,
      "expiration_date": "{expiration_time ISO 8601}"
    },
    "ETHGasSpent#0.25": {
      "score": "{credential_score}",
      "dedup": true/false,
      "expiration_date": "{expiration_time ISO 8601}"
    },
    { ... }
  }
}

Learn more about the data dictionary.

Retrieve historical score for a single address

Note:
To access this endpoint, you must submit your use case and be approved by the Passport team. To do so, please fill out the following form, making sure to provide a detailed description of your use case. The Passport team typically reviews and responds to form responses within 48 hours.

Request access (opens in a new tab)

This endpoint will return the last requested historical score and Stamp data for a single address before a specified time.

For example, if you requested a score on 2024-12-01 using the GET /v2/stamps/{scorer_id}/score/{address} endpoint, then use this historical score endpoint to request the score for the same address on 2024-12-05, you will receive the score and Stamp data for 2024-12-01 for that address. If you have not requested a score for a specified address using the GET /v2/stamps/{scorer_id}/score/{address} endpoint, you will not be able to receive a historical score for that address.

GET /v2/stamps/{scorer_id}/score/{address}/history

Query parameters

NameRequiredDescription
created_atyesSpecified time that you want to retrieve the most recently submitted score for.

ISO 8601 (YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.sssZ)
Sample request
curl --request GET \
    --url https://api.passport.xyz/v2/stamps/{scorer_id}/score/{address}/history?created_at={created_at} \
    --header 'X-API-KEY: {API KEY}'
Sample response
{
  "items": [
    {
      "address": "{address}",
      "score": "{score}",
      "passing_score": true/false,
      "last_score_timestamp": "{last_score_time ISO 8601}",
      "expiration_timestamp": "{expiration_time ISO 8601}",
      "threshold": "20",
      "error": null,
      "stamps": {
        "Ens": {
          "score": "{credential_score}",
          "dedup": true/false,
          "expiration_date": "{expiration_time ISO 8601}"
        },
        "ETHDaysActive#50": {
          "score": "{credential_score}",
          "dedup": true/false,
          "expiration_date": "{expiration_time ISO 8601}"
        },
        "ETHGasSpent#0.25": {
          "score": "{credential_score}",
          "dedup": true/false,
          "expiration_date": "{expiration_time ISO 8601}"
        },
        { ... }
      }
    }
  ]
}        

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 /v2/stamps/{address}

Query parameters

NameRequiredDescription
include_metadataNoReturns optional metadata object with additional details about connected Stamps.

Format: true/false
Default: false
limitNoPaginates response, providing the given number of Stamps per page (For example, use limit=3 to request three Stamps) Learn more about API pagination.
tokenNoPass the next or prev value from the previous response to get the next or previous page of results.
Sample request
curl --request GET \
    --url 'https://api.passport.xyz/v2/stamps/{address}?include_metadata=true' \
    --header 'X-API-KEY: {API KEY}'
Sample response
{
  "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 /v2/stamps/metadata

Sample request
curl --request GET \
    --url https://api.passport.xyz/v2/stamps/metadata \
    --header 'X-API-KEY: {API KEY}'
Sample request
[
  {
    "id": "string",
    "icon": "string",
    "name": "string",
    "description": "string",
    "connectMessage": "string",
    "groups": [
      {
        "name": "string",
        "stamps": [
          {
            "name": "string",
            "description": "string",
            "hash": "string"
          }
        ]
      }
    ]
  }
]

If you have questions about the API, please reach out to us in our developer support channel (opens in a new tab).