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).
Tier | Rate limit |
---|---|
Tier 1 | 125 requests per 15 minutes |
Tier 2 | 350 requests per 15 minutes |
Tier 3 | 2000 requests per 15 minutes |
Tier 4 | 2000+ 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 action | Endpoint |
---|---|
Retrieve latest score for a single address | GET /v2/stamps/{scorer_id}/score/{address} |
Retrieve historical score for a single address | GET /v2/stamps/{scorer_id}/score/{address}/history |
Retrieve Stamps verified by a single address | GET /v2/stamps/{address} |
Retrieve all Stamps available in Passport | GET /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}
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
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
Name | Required | Description |
---|---|---|
created_at | yes | Specified time that you want to retrieve the most recently submitted score for. ISO 8601 ( YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.sssZ ) |
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
Name | Required | Description |
---|---|---|
include_metadata | No | Returns optional metadata object with additional details about connected Stamps.Format: true /false Default: false |
limit | No | Paginates response, providing the given number of Stamps per page (For example, use limit=3 to request three Stamps) Learn more about API pagination. |
token | No | Pass the next or prev value from the previous response to get the next or previous page of results. |
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).