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.

Authentication

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.

ApiKeyAuth

Security Scheme Type: API Key

Header parameter name: X-API-KEY

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"
  }),
});

passes

Create a new pass

POST /v0/passes

Generate a pass from a wallet signature, chain information, and (optional) NFT information.

Authorizations:

ApiKeyAuth

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 Apple Documentation Google Documentation
	object (Delegation) Wallet Delegation

Responses

Request samples

Payload

Content type

application/json

{"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",
"redirect": {"url": "https://my-app.io/scan"
}
},
"image": "https://ipfs.io/ipfs/QmYyXcVMgny4BJYiaUyTU46HX7seFNgnvte2eoL2fN2PXf",
"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

Content type

application/json

{"id": "f664196b-035a-454d-90c4-ab0adc107981",
"fileURL": "https://api.ethpass.xyz/api/public/download/GeneratedPass-0.63592689673288.pkpass",
"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:

ApiKeyAuth

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 `0` Filter active passes `1` Filter expired passes
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 Default: `createdAt`
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. Default: 50
offset	number Skip a certain number of results and return the remaining results.

Responses

Response samples

Content type

application/json

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

ApiKeyAuth

path Parameters

required

string

Pass ID or user provided externalId

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

Content type

application/json

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

ApiKeyAuth

path Parameters

required

string

Pass ID or user provided externalId

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

Content type

application/json

{"barcode": {"message": "Encoded code or message here",
"redirect": {"url": "https://my-app.io/scan"
}
},
"image": "https://ipfs.io/ipfs/QmYyXcVMgny4BJYiaUyTU46HX7seFNgnvte2eoL2fN2PXf",
"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

Content type

application/json

{"message": "string"
}

Invalidate a pass

DELETE /v0/passes/{id}

Retrieve the Apple Wallet / Google Wallet URL which lets the user download their pass.

Authorizations:

ApiKeyAuth

path Parameters

required

string

Pass ID or user provided externalId

Responses

Response samples

Content type

application/json

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

ApiKeyAuth

path Parameters

required

string

Pass ID or user provided externalId

Responses

Response samples

Content type

application/json

{"fileURL": "string",
"buffer": { }
}

scan

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.

See our tips on scanning QR codes.

Authorizations:

ApiKeyAuth

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

Content type

application/json

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

Create Pass Model

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 Apple Documentation Google Documentation
	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",
"redirect": {"url": "https://my-app.io/scan"
}
},
"image": "https://ipfs.io/ipfs/QmYyXcVMgny4BJYiaUyTU46HX7seFNgnvte2eoL2fN2PXf",
"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"
}
}

Apple Pass Model

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

Google Pass Model

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