Building with Passport
Passport API
Data dictionary

Data dictionary

On this page you will find definitions and explanations for the data types used in the Gitcoin Passport stack. The Scorer, Stamp , Credential and Stamp-metadata objects require the most explanation so they are handled separately here. Other types found across the Passport stack are defined in "Other data".

The Scorer object

ValueTypeDescriptionHow to use
addressstringThe string of 20 bytes that uniquely identify an Ethereum accountIdentifies a specific account to be scored
scorestringThe registry/score endpoint returns a string that should be parsed as a float. It represents the result of adding the weights of all a user's Stamps.Returned from registry/score. Can be used to gate access to content.
statusstringShows whether a server request is PROCESSING or DONE.Included in responses from registry/score
last_score_timestampdatetime stringThe date and time of the previous request made to the Scorer instance. For example, "2023-04-28T09:35:49.159Z"Returned by the registry/score and registry/submit-passport endpoint
expiration_datedatetime stringThe date and time that the next upcoming Stamp will expire, which will subsequently reduce the score. To see when each specific Stamp expires, please use the GET /stamps endpoint.You might want to display this score expiration to the user to remind them to return to the Passport app to refresh their score before it expires
evidencestructWhen the binary Scorer is selected, this field is used to explain why the return value was 0 or 1. Specifically, the returned data shows the threshold score required to return 1, and the actual score the Passport received. The current score threshold for a passing score is 20.You can use this to check the reasoning behind a binary Passport score, and understand why a Passport was decided to be Sybil (0) or non-Sybil (1).
errorstringDescribes any error returned by the server. Refer to the API status and error codes page for more information.Used to understand why a request failed.
stamp_scoresstructContains key:value pairs with stamp names as keys and their weights for the scoring algoithm as values.

The Stamp object

ValueTypeDescriptionHow to use
credentialstructMessage displayed in the Passport Scorer app alongside a button to trigger verification of a specific Stamp See Credentials table below for more details.This is what a Stamp actually comprises. It is associated with an Ethereum address.
itemsarray<stamp>An array containing data for each individual Stamp.Each object in this array represents a specific Stamp.
metadatastructMetadata is a struct containing id, icon, name, description, and connectMessage fields for each provider and then more granular data for each of the provider's StampsReturned from the registry/stamps endpoint if the qualifier include-metadata=true is also passed. Returned from registry/stamp-metadata for all Stamps
nextstringA pointer to the next page of returned data, if the returned data has been paginated.You can use this is a request to access a page and the subsequent page of results for a paginated response. If the value is null you are already seeing all the available information.
prevstringA pointer to the preceding page of returned data, if the returned data has been paginated.You can use this is a request to access a page and the previous page of results for a paginated response. If the value is null you are already seeing all the available information.
versionstringA version identifier for a StampReturned for each Stamp from registry/stamps

Credentials

A credential is a struct returned in the Stamp object. It has its own sub-fields as follows:

ValueTypeDescriptionHow to use
typestringA descriptor that shows what type of credential is presentCan be used to check that the returned data is of the expected structure for a given credential type. This is usually going to have the value VerifiableCredential.
proofstructA struct containing several fields comprising the proof that a certain action was taken, for example a signed auth token proving that an account was unlocked.Used to verify ownership of a specific Stamp
issuerhashEach Stamp issuer has a specific identifying hash provided in this field.Used to identify a Stamp issuer
@contexturlLink to the credential definition documentationCan be used to access reference documentation for the credential type
issuanceDatedatetime stringThe date and time that the Stamp was minted. For example, "2023-04-28T09:35:49.159Z"Can be used to check the age of a Stamp
expirationDatedatetime stringThe date and time the Stamp should expire. For example, "2023-04-28T09:35:49.159Z"Can be used to automatically expire a Stamp
credentialSubjectstructContains anonymized information about the user that the Stamp is issued to. This includes a unique ID, a hash, link to the data schema and the Stamp provider name in plaintext.Can be used to connect Stamps to a user in a privacy preserving way

Stamp metadata

ValueTypeDescriptionHow to use
connectMessagestringMessage displayed in the Passport scorer app alongside a button to trigger verification of a specific StampMainly used in the Passport app, but could be used to provide appropriate message for verification in other contexts
descriptionstringShort description of what a specific Stamp demonstrates. For example, ownership of >0.5 ETHReturned in Stamp metadata, can be used to understand a specific Stamp
groupsstringIdentifier for top-level groupings of Stamps for a given providerEach provider may issue many Stamps which can be grouped together by theme, for example the Gitcoin Provider groups Stamps by Self GTC-staking and Community GTC-staking
hashstringA unique hash representing a specific instance of a credentialUsed to prevent the same Stamp being used multiple times in a specific Scorer instance
iconstringA URL for an image to represent each Stamp providerReturned in Stamp metadata, can be used to load an icon for a Stamp provider
idstringAn identifier for a StampReturned in Stamp metadata, can be used to scrape data for a specific Stamp
namestringName of the provider issuing a given StampReturned as part of the Stamp metadata, can be used to scrape information for specific providers
stampsarrayArray containing Stamp structs for each individual Stamp. Each Stamp has name, description and hash fieldsIncluded in Stamp metadata. Used to identify specific instances of individual Stamps

GTC staking

ValueTypeDescription
usersarrayContains the specified address's staking data, including a stakes object that contains data on how much and when a user staked GTC on themselves, and the xstakeAggregate, which contains data on how much a user has staked on other community members and when.
stakesarrayContains one or multiple stake objects, which includes data on how much GTC the specified user has staked on themselves. This array will include a different object for each round the user had staked any GTC on themselves.
stakestringRepresents the number of GTC the user has staked on themselves in a specified round.
roundobjectContains the ID of the round in which the associated stake amount was staked.
idnumberRepresents the round in which the associated stake amount was staked.
xstakeAggregatesarrayContains one or multiple stake objects, which includes data on how much GTC the specified user has staked on themselves. This array will include a different object for each round the user had staked any GTC on themselves.
totalstringRepresents the total number of GTC the user staked on community members in a specified round.

Other data

ValueTypeDescriptionHow to use
API-KeystringAn authorization token generated by the Scorer app giving you access to a Scorer instance on the Gitcoin server.Include this API key as part of your request headers.
nonceintA transaction counter for an address that is used in signing to prevent certain types of attackThis is an optional field that can be provided to submit-passport for additional verification. Today access to Scorers is controlled using API keys only by default.
scorer_idstringScorers are instantiated with unique IDs known as scorer_ids.Create a Scorer in the Scorer app to receive a scorer_id. Then this value links your API requests to a specific Scorer instance matching your API key
signaturestringSome workflows require a Scorer owner to demonstrate their ownership by signing a message with the Scorer owner's private key.This is an optional field that can be provided to submit-passport for additional verification. Today access to Scorers is controlled using API keys only by default.