Passport API v2 -- 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.

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

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)

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}

curl --request GET \
  --url https://api.passport.xyz/v2/stamps/{scorer_id}/score/{address} \
  --header 'X-API-KEY: {API KEY}'

{
  "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

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

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

{
  "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

curl --request GET \
    --url 'https://api.passport.xyz/v2/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 /v2/stamps/metadata

curl --request GET \
    --url https://api.passport.xyz/v2/stamps/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"
          }
        ]
      }
    ]
  }
]

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