API Reference (0.1.0)
Download OpenAPI specification:Download
ethpass is an API service for creating Apple Wallet and Google Wallet passes from your NFTs and other assets.
The service uses API keys to authenticate requests. Log into the developer dashboard to generate yours, or see our Generate API Key guide.
To supply an API key for a request, you must include it in the request header.
const response = await fetch("https://api.ethpass.xyz/api/v0/passes", {
method: "POST",
body: JSON.stringify(payload),
headers: new Headers({
"content-type": "application/json",
"X-API-KEY": "YOUR_SECRET_API_KEY"
}),
});
Create a new pass
POST /v0/passes
Generate a pass from a wallet signature, chain information, and (optional) NFT information.
Authorizations:
Request Body schema: application/json
required | object Blockchain Details |
signature required | string Signed message |
signatureMessage required | string Message displayed when requesting signature |
platform required | string (Platform) Enum: "apple" "google" |
object (EVMNFT) | |
object (BarcodeInput) | |
image | string You can display a custom image on your pass. The file size of the image should not exceed 2MB, and it should be in one of the following formats. (.png, .jpg, .webp, .svg, .gif, .tiff) |
templateId | string Custom template |
externalId | string Use this parameter to grant custom identifiers to passes. |
PublicApplePass (object) or PublicGooglePass (object) Customize passes based on platform specifications | |
object (Delegation) Wallet Delegation |
Responses
Request samples
- Payload
{- "chain": {
- "name": "evm",
- "network": 1
}, - "signature": "0x71147d2b97a397061e6dbd82351867a7057bdb4d9566a8ac2d618e1a3e62d43c722245fb4e6a8e9ee814348bdd5c433224c8c10f9fadf7fd154b44c17056109f1c",
- "signatureMessage": "Sign this message to generate a test pass with ethpass.xyz",
- "platform": "apple",
- "nft": {
- "contractAddress": "0x79c1d53f15e34895d608ff47ee56ad1f0f3f45d3",
- "tokenId": "315",
- "contractInterface": "0x80ac58cd"
}, - "barcode": {
- "message": "Encoded code or message here",
}, - "templateId": "01791169-5edc-4fbc-a87a-106fb9400bdc",
- "externalId": "external-id-123",
- "pass": {
- "description": "My Event Name",
- "logoText": "MY EVENTS",
- "labelColor": "rgb(255,0,0)",
- "backgroundColor": "rgb(0,0,0)",
- "foregroundColor": "rgb(255,255,255)",
- "expirationDate": "string",
- "locations": [
- {
- "relevantText": "string",
- "altitude": 0,
- "latitude": 0,
- "longitude": 0
}
], - "auxiliaryFields": [
- {
- "label": "CLAIM CODE",
- "textAlignment": "PKTextAlignmentNatural",
- "key": "field1",
- "value": "string"
}
], - "backFields": [
- {
- "label": "CLAIM CODE",
- "textAlignment": "PKTextAlignmentNatural",
- "key": "field1",
- "value": "string"
}
], - "headerFields": [
- {
- "label": "CLAIM CODE",
- "textAlignment": "PKTextAlignmentNatural",
- "key": "field1",
- "value": "string"
}
], - "primaryFields": [
- {
- "label": "CLAIM CODE",
- "textAlignment": "PKTextAlignmentNatural",
- "key": "field1",
- "value": "string"
}
], - "secondaryFields": [
- {
- "label": "CLAIM CODE",
- "textAlignment": "PKTextAlignmentNatural",
- "key": "field1",
- "value": "string"
}
], - "appLaunchURL": "string",
- "associatedStoreIdentifiers": [
- 0
]
}, - "delegation": {
- "registry": "delegate.cash",
- "vaultAddress": "0x79c1d53f15e34895d608ff47ee56ad1f0f3f45d3"
}
}
Response samples
- 200
- 400
{- "id": "f664196b-035a-454d-90c4-ab0adc107981",
- "buffer": { }
}
Get all passes
GET /v0/passes
Retrieves all passes created in ethpass tied to your developer account / project API key.
It is recommended to filter by relevant information.
Authorizations:
query Parameters
lastScannedStartTime | number Filter passes scanned on or after specified time (Unix timestamp in seconds) |
lastScannedEndTime | number Filter passes scanned up to or before specified time (Unix timestamp in seconds) |
createdStartTime | number Filter passes created on or after specified time (Unix timestamp in seconds) |
createdEndTime | number Filter passes created up to or before specified time (Unix timestamp in seconds) |
expired | number
|
platform | any Enum: "apple" "google" Filter passes by platform |
chain | string (Chains) Value: "evm" Filter passes by blockchain |
network | number (Network) Enum: 1 5 11155111 137 80001 10 420 42161 421613 56 97 100 84531 Filter passes by network |
ownerAddress | string Filter passes by owners wallet address |
contractAddress | string Filter passes by contract address |
tokenId | string Filter passes by token ID |
orderBy | string Enum: "id" "ownerAddress" "createdAt" "lastScannedAt" "expiredAt" "platform" Sort the results based on a field |
asc | number Enum: "0" "1" The "asc" query parameter sorts database query results in ascending order when set to 1, and descending order when set to 0, and is typically used in conjunction with the "orderBy" parameter. |
limit | number Restrict the number of results returned. |
offset | number Skip a certain number of results and return the remaining results. |
Responses
Response samples
- 200
- 400
{- "count": 0,
- "passes": [
- {
- "id": "e9adf464-c17b-4494-854c-25604c5fa948",
- "chain": {
- "name": "evm",
- "network": 1
}, - "ownerAddress": "0xD0136A89A15CV85f3f7e76e77E2450538a70B02h",
- "createdAt": "2019-08-24",
- "lastScannedAt": "2019-08-24",
- "expiredAt": "2019-08-24",
- "expireAction": "NFT transferred to another wallet",
- "platform": "apple",
- "nfts": {
- "contractAddress": "0x79c1d53f15e34895d608ff47ee56ad1f0f3f45d3",
- "tokenId": "315",
- "contractInterface": "0x80ac58cd",
- "valid": true
}, - "barcodeSignature": "0xc1fe64e0fcb287ec5b4eab53541fac723abc7a5d06554f79ef7263dd5ae4708b03695f55e6e6acf86b92274c626859750ceaae2dbaa67688f472bc924f3bca921c",
- "templateId": "f664196b-035a-454d-90c4-ab0adc107981",
- "registrations": [
- { }
], - "delegation": {
- "registry": "delegate.cash",
- "vaultAddress": "0x79c1d53f15e34895d608ff47ee56ad1f0f3f45d3"
}
}
]
}
Get a single pass
GET /v0/passes/{id}
Retrieve a pass by its ID.
IDs can be obtained either from creation or by querying GET /v0/passes.
Authorizations:
path Parameters
id required | string Pass ID or user provided |
query Parameters
scanHistoryStartTime | number Include previous barcode scans starting from specified time (Unix timestamp in seconds) |
scanHistoryEndTime | number Include previous barcode scans ending at specified time (Unix timestamp in seconds) |
Responses
Response samples
- 200
- 400
{- "id": "e9adf464-c17b-4494-854c-25604c5fa948",
- "chain": {
- "name": "evm",
- "network": 1
}, - "ownerAddress": "0xD0136A89A15CV85f3f7e76e77E2450538a70B02h",
- "createdAt": "2019-08-24",
- "lastScannedAt": "2019-08-24",
- "expiredAt": "2019-08-24",
- "expireAction": "NFT transferred to another wallet",
- "platform": "apple",
- "nfts": {
- "contractAddress": "0x79c1d53f15e34895d608ff47ee56ad1f0f3f45d3",
- "tokenId": "315",
- "contractInterface": "0x80ac58cd",
- "valid": true
}, - "barcodeSignature": "0xc1fe64e0fcb287ec5b4eab53541fac723abc7a5d06554f79ef7263dd5ae4708b03695f55e6e6acf86b92274c626859750ceaae2dbaa67688f472bc924f3bca921c",
- "templateId": "f664196b-035a-454d-90c4-ab0adc107981",
- "registrations": [
- { }
], - "delegation": {
- "registry": "delegate.cash",
- "vaultAddress": "0x79c1d53f15e34895d608ff47ee56ad1f0f3f45d3"
}
}
Update a pass
PATCH /v0/passes/{id}
Update any fields of the Apple Wallet or Google Wallet pass, as well as the encoded message in the barcode and other pass details.
For more information on updating passes, see here.
Authorizations:
path Parameters
id required | string Pass ID or user provided |
Request Body schema: application/json
object (BarcodeInput) | |
image | string You can display a custom image on your pass. The file size of the image should not exceed 2MB, and it should be in one of the following formats. (.png, .jpg, .webp, .svg, .gif, .tiff) |
PublicApplePass (object) or PublicGooglePass (object) |
Responses
Request samples
- Payload
{- "barcode": {
- "message": "Encoded code or message here",
}, - "pass": {
- "description": "My Event Name",
- "logoText": "MY EVENTS",
- "labelColor": "rgb(255,0,0)",
- "backgroundColor": "rgb(0,0,0)",
- "foregroundColor": "rgb(255,255,255)",
- "expirationDate": "string",
- "locations": [
- {
- "relevantText": "string",
- "altitude": 0,
- "latitude": 0,
- "longitude": 0
}
], - "auxiliaryFields": [
- {
- "label": "CLAIM CODE",
- "textAlignment": "PKTextAlignmentNatural",
- "key": "field1",
- "value": "string"
}
], - "backFields": [
- {
- "label": "CLAIM CODE",
- "textAlignment": "PKTextAlignmentNatural",
- "key": "field1",
- "value": "string"
}
], - "headerFields": [
- {
- "label": "CLAIM CODE",
- "textAlignment": "PKTextAlignmentNatural",
- "key": "field1",
- "value": "string"
}
], - "primaryFields": [
- {
- "label": "CLAIM CODE",
- "textAlignment": "PKTextAlignmentNatural",
- "key": "field1",
- "value": "string"
}
], - "secondaryFields": [
- {
- "label": "CLAIM CODE",
- "textAlignment": "PKTextAlignmentNatural",
- "key": "field1",
- "value": "string"
}
], - "appLaunchURL": "string",
- "associatedStoreIdentifiers": [
- 0
]
}
}
Response samples
- 400
{- "message": "string"
}
Invalidate a pass
DELETE /v0/passes/{id}
Retrieve the Apple Wallet / Google Wallet URL which lets the user download their pass.
Authorizations:
path Parameters
id required | string Pass ID or user provided |
Responses
Response samples
- 200
- 400
{- "id": "e9adf464-c17b-4494-854c-25604c5fa948",
- "chain": {
- "name": "evm",
- "network": 1
}, - "ownerAddress": "0xD0136A89A15CV85f3f7e76e77E2450538a70B02h",
- "createdAt": "2019-08-24",
- "lastScannedAt": "2019-08-24",
- "expiredAt": "2019-08-24",
- "expireAction": "NFT transferred to another wallet",
- "platform": "apple",
- "nfts": {
- "contractAddress": "0x79c1d53f15e34895d608ff47ee56ad1f0f3f45d3",
- "tokenId": "315",
- "contractInterface": "0x80ac58cd",
- "valid": true
}, - "barcodeSignature": "0xc1fe64e0fcb287ec5b4eab53541fac723abc7a5d06554f79ef7263dd5ae4708b03695f55e6e6acf86b92274c626859750ceaae2dbaa67688f472bc924f3bca921c",
- "templateId": "f664196b-035a-454d-90c4-ab0adc107981",
- "registrations": [
- { }
], - "delegation": {
- "registry": "delegate.cash",
- "vaultAddress": "0x79c1d53f15e34895d608ff47ee56ad1f0f3f45d3"
}
}
Redistribute a pass
GET /v0/passes/{id}/distribute
Retrieve the Apple Wallet / Google Wallet URL which lets the user download their pass.
Authorizations:
path Parameters
id required | string Pass ID or user provided |
Responses
Response samples
- 200
- 400
{- "fileURL": "string",
- "buffer": { }
}
Scan a pass
GET /v0/scan
Verify ownership of a token by scanning the barcode on a pass. ethpass will once again read the on-chain owner of the token linked to the pass, and return a successful response if the ownership is accurate.
Authorizations:
query Parameters
data required | string Barcode value extracted from scan |
dryRun | boolean Default: false With this parameter set to true, the API will scan a pass and return the extracted information, but it will not be recorded as a valid scan in the database. |
Responses
Response samples
- 200
- 400
{- "message": "string",
- "id": "e9adf464-c17b-4494-854c-25604c5fa948",
- "chain": {
- "name": "evm",
- "network": 1
}, - "ownerAddress": "0xD0136A89A15CV85f3f7e76e77E2450538a70B02h",
- "createdAt": "2019-08-24",
- "lastScannedAt": "2019-08-24",
- "expiredAt": "2019-08-24",
- "expireAction": "NFT transferred to another wallet",
- "platform": "apple",
- "nfts": {
- "contractAddress": "0x79c1d53f15e34895d608ff47ee56ad1f0f3f45d3",
- "tokenId": "315",
- "contractInterface": "0x80ac58cd",
- "valid": true
}, - "barcodeSignature": "0xc1fe64e0fcb287ec5b4eab53541fac723abc7a5d06554f79ef7263dd5ae4708b03695f55e6e6acf86b92274c626859750ceaae2dbaa67688f472bc924f3bca921c",
- "templateId": "f664196b-035a-454d-90c4-ab0adc107981",
- "registrations": [
- { }
], - "delegation": {
- "registry": "delegate.cash",
- "vaultAddress": "0x79c1d53f15e34895d608ff47ee56ad1f0f3f45d3"
}
}
required | object Blockchain Details |
signature required | string Signed message |
signatureMessage required | string Message displayed when requesting signature |
platform required | string (Platform) Enum: "apple" "google" |
object (EVMNFT) | |
object (BarcodeInput) | |
image | string You can display a custom image on your pass. The file size of the image should not exceed 2MB, and it should be in one of the following formats. (.png, .jpg, .webp, .svg, .gif, .tiff) |
templateId | string Custom template |
externalId | string Use this parameter to grant custom identifiers to passes. |
PublicApplePass (object) or PublicGooglePass (object) Customize passes based on platform specifications | |
object (Delegation) Wallet Delegation |
{- "chain": {
- "name": "evm",
- "network": 1
}, - "signature": "0x71147d2b97a397061e6dbd82351867a7057bdb4d9566a8ac2d618e1a3e62d43c722245fb4e6a8e9ee814348bdd5c433224c8c10f9fadf7fd154b44c17056109f1c",
- "signatureMessage": "Sign this message to generate a test pass with ethpass.xyz",
- "platform": "apple",
- "nft": {
- "contractAddress": "0x79c1d53f15e34895d608ff47ee56ad1f0f3f45d3",
- "tokenId": "315",
- "contractInterface": "0x80ac58cd"
}, - "barcode": {
- "message": "Encoded code or message here",
}, - "templateId": "01791169-5edc-4fbc-a87a-106fb9400bdc",
- "externalId": "external-id-123",
- "pass": {
- "description": "My Event Name",
- "logoText": "MY EVENTS",
- "labelColor": "rgb(255,0,0)",
- "backgroundColor": "rgb(0,0,0)",
- "foregroundColor": "rgb(255,255,255)",
- "expirationDate": "string",
- "locations": [
- {
- "relevantText": "string",
- "altitude": 0,
- "latitude": 0,
- "longitude": 0
}
], - "auxiliaryFields": [
- {
- "label": "CLAIM CODE",
- "textAlignment": "PKTextAlignmentNatural",
- "key": "field1",
- "value": "string"
}
], - "backFields": [
- {
- "label": "CLAIM CODE",
- "textAlignment": "PKTextAlignmentNatural",
- "key": "field1",
- "value": "string"
}
], - "headerFields": [
- {
- "label": "CLAIM CODE",
- "textAlignment": "PKTextAlignmentNatural",
- "key": "field1",
- "value": "string"
}
], - "primaryFields": [
- {
- "label": "CLAIM CODE",
- "textAlignment": "PKTextAlignmentNatural",
- "key": "field1",
- "value": "string"
}
], - "secondaryFields": [
- {
- "label": "CLAIM CODE",
- "textAlignment": "PKTextAlignmentNatural",
- "key": "field1",
- "value": "string"
}
], - "appLaunchURL": "string",
- "associatedStoreIdentifiers": [
- 0
]
}, - "delegation": {
- "registry": "delegate.cash",
- "vaultAddress": "0x79c1d53f15e34895d608ff47ee56ad1f0f3f45d3"
}
}
description | string |
logoText | string |
labelColor | string |
backgroundColor | string |
foregroundColor | string |
expirationDate | string |
Array of objects (Location) | |
Array of objects (Field) | |
Array of objects (Field) | |
Array of objects (Field) | |
Array of objects (Field) | |
Array of objects (Field) | |
appLaunchURL | string |
associatedStoreIdentifiers | Array of numbers |
{- "description": "My Event Name",
- "logoText": "MY EVENTS",
- "labelColor": "rgb(255,0,0)",
- "backgroundColor": "rgb(0,0,0)",
- "foregroundColor": "rgb(255,255,255)",
- "expirationDate": "string",
- "locations": [
- {
- "relevantText": "string",
- "altitude": 0,
- "latitude": 0,
- "longitude": 0
}
], - "auxiliaryFields": [
- {
- "label": "CLAIM CODE",
- "textAlignment": "PKTextAlignmentNatural",
- "key": "field1",
- "value": "string"
}
], - "backFields": [
- {
- "label": "CLAIM CODE",
- "textAlignment": "PKTextAlignmentNatural",
- "key": "field1",
- "value": "string"
}
], - "headerFields": [
- {
- "label": "CLAIM CODE",
- "textAlignment": "PKTextAlignmentNatural",
- "key": "field1",
- "value": "string"
}
], - "primaryFields": [
- {
- "label": "CLAIM CODE",
- "textAlignment": "PKTextAlignmentNatural",
- "key": "field1",
- "value": "string"
}
], - "secondaryFields": [
- {
- "label": "CLAIM CODE",
- "textAlignment": "PKTextAlignmentNatural",
- "key": "field1",
- "value": "string"
}
], - "appLaunchURL": "string",
- "associatedStoreIdentifiers": [
- 0
]
}
Array of objects (walletobjects_v1_Message) | |
object (walletobjects_v1_TextModuleData) Data for Text module. All fields are optional. Header will be displayed if available, different types of bodies will be concatenated if they are defined. | |
object (walletobjects_v1_LinksModuleData) | |
object (walletobjects_v1_LatLongPoint) |
{- "messages": [
- {
- "body": "string",
- "displayInterval": {
- "end": {
- "date": "string"
}, - "kind": "string",
- "start": {
- "date": "string"
}
}, - "header": "string",
- "id": "string",
- "kind": "string",
- "localizedBody": {
- "defaultValue": {
- "kind": "string",
- "language": "string",
- "value": "string"
}, - "kind": "string",
- "translatedValues": [
- {
- "kind": "string",
- "language": "string",
- "value": "string"
}
]
}, - "localizedHeader": {
- "defaultValue": {
- "kind": "string",
- "language": "string",
- "value": "string"
}, - "kind": "string",
- "translatedValues": [
- {
- "kind": "string",
- "language": "string",
- "value": "string"
}
]
}, - "messageType": "string"
}
], - "textModulesData": {
- "body": "string",
- "header": "string",
- "id": "string",
- "localizedBody": {
- "defaultValue": {
- "kind": "string",
- "language": "string",
- "value": "string"
}, - "kind": "string",
- "translatedValues": [
- {
- "kind": "string",
- "language": "string",
- "value": "string"
}
]
}, - "localizedHeader": {
- "defaultValue": {
- "kind": "string",
- "language": "string",
- "value": "string"
}, - "kind": "string",
- "translatedValues": [
- {
- "kind": "string",
- "language": "string",
- "value": "string"
}
]
}
}, - "linksModuleData": {
- "uris": [
- {
- "description": "string",
- "id": "string",
- "kind": "string",
- "localizedDescription": {
- "defaultValue": {
- "kind": "string",
- "language": "string",
- "value": "string"
}, - "kind": "string",
- "translatedValues": [
- {
- "kind": "string",
- "language": "string",
- "value": "string"
}
]
}, - "uri": "string"
}
]
}, - "locations": {
- "kind": "string",
- "latitude": 0,
- "longitude": 0
}
}