Quick Start

This page will help you make your first API request using the Passport API v2.

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

Please make sure you have an API key and Scorer ID before working through this guide.

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

You can browse more specific API details in the API reference.

How to retrieve a score

There is one basic step to retrieve a user's Passport score and Stamp data. All you have to do is make a request to the following GET endpoint:

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

This endpoint requires a scorer_id and an address to be passed as path parameters. You can see an example of this in the following cURL request, using a scorer ID, 100; an address, 0x2C1E111d7C3adc823B5fA3af3f07EB62831C3c5; and a placeholder ({your-api-key}) that you need to replace with your API key:

Sample request

curl --request GET \
  --url https://api.passport.xyz/v2/stamps/100/score/0x2C1E111d7C3adc823B5fA3af3f07EB62831C3c5 \
  --header 'X-API-KEY: {your-api-key}'

An example response might look as follows:

Sample response

{
    "address": "0x2C1E111d7C3adc823B5fA3af3f07EB62831C3c5",
    "score": "33.538",
    "passing_score": true,
    "last_score_timestamp": "2024-11-17T14:46:22.900951+00:00",
    "expiration_timestamp": "2025-02-06T14:28:06.879000+00:00",
    "threshold": "20",
    "error": null,
    "stamp_scores": {
      "Discord": "0.516",
      "Google": "0.525",
      "NFT": "1.032",
      "SnapshotProposalsProvider": "0.839",
      "zkSyncScore#5": "1.67",
      "zkSyncScore#20": "1.67",
      "zkSyncScore#50": "1.67",
      "ZkSyncEra": "0.606",
      "Lens": "0.93",
      "ETHGasSpent#0.25": "1.003",
      "GuildPassportMember": "0.54",
      "CivicUniquenessPass": "6.005",
      "TrustaLabs": "0.511",
      "BinanceBABT": "16.021"
    }
}

This response indicates that the address was successfully able to prove their humanity with Passport since their score is above the recommended threshold of 20.

It's worthwhile to note that you can manually set your own score threshold within your code base based on your ecosystem's unique needs, but a score threshold of 20 is recommended for optimal results.

Next Steps

Getting access API reference