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"
}),
});
Get project information
GET /v0/project
This endpoint fetches details for a specific project tied to your account. The data retrieved includes the unique identifier (id) of the project, which follows the universally unique identifier (UUID) format. It also provides the name of the project, which can be used to easily identify the project across various platforms or interfaces.
In addition, the project's associated timezone is returned. This can be essential for understanding and scheduling time-sensitive operations related to the project.
Lastly, the keyCreated
boolean value indicates whether a key has been created for the project. This piece of information can be vital for determining the project's readiness for certain operations and integrations that may require a project key.
Authorizations:
Responses
Response samples
- 200
- 400
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "timezone": "string",
- "keyCreated": true
}
Get project stats
GET /v0/project
This endpoint retrieves a comprehensive set of statistical data tied to a specific project. The statistics include the total number of passes and scan counts, as well as a detailed breakdown of platform-specific metrics for Apple and Google. These platform metrics include the total number, registered, and expired counts.
Furthermore, this endpoint also provides an array of recent activities, encapsulating key information such as the platform, chain, owner address, network, timestamps of creation, expiry and last scan, as well as data on scans and registrations. It also provides action details and timestamps.
Authorizations:
Responses
Response samples
- 200
- 400
{- "stats": {
- "totalPasses": 0,
- "totalScanCount": 0,
- "apple": {
- "total": 0,
- "registered": 0,
- "expired": 0
}, - "google": {
- "total": 0,
- "registered": 0,
- "expired": 0
}
}, - "recentActivity": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "platform": "string",
- "chain": "string",
- "ownerAddress": "string",
- "network": "string",
- "expiredAt": "2019-08-24T14:15:22Z",
- "createdAt": "2019-08-24T14:15:22Z",
- "lastScannedAt": "2019-08-24T14:15:22Z",
- "registrations": [
- null
], - "scans": {
- "total": 0,
- "property1": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "createdAt": "2019-08-24T14:15:22Z",
- "pass": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
}, - "property2": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "createdAt": "2019-08-24T14:15:22Z",
- "pass": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
}
}, - "action": "string",
- "timestamp": 0
}
]
}
Create a new pass
POST /v0/passes
This endpoint allows you to generate an Apple or Google pass based on specific wallet signatures.
Using this feature, you can create a digital representation of ownership or affiliation, similar to a digital card or pass, which can be added to a user's Apple Wallet or Google Pay. This pass can be created to represent various forms of ownership or involvement, such as the ownership of a wallet, possession of a particular NFT, or even attachment to one or multiple existing policies.
Authorizations:
Request Body schema: application/json
object Blockchain Details | |
signature | string Signed message |
signatureMessage | string Message displayed when requesting signature |
platform required | string (Platform) Enum: "apple" "google" |
object (EVMNFT) | |
policies | Array of strings Policy IDs |
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"
}, - "policies": [
- "string"
], - "barcode": {
- "message": "Encoded code or message here",
- "format": "QR",
- "encoded": true,
}, - "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": "e9adf464-c17b-4494-854c-25604c5fa948",
- "buffer": { },
- "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",
- "policies": [
- {
- "name": "string",
- "chain": {
- "name": "evm",
- "network": 1
}, - "ruleEvaluation": "ALL",
- "minRules": 0,
- "rules": [
- {
- "type": "COLLECTION",
- "satisfiesRule": 0,
- "data": {
- "contractAddress": "string",
- "tokenIds": [
- 0
], - "balance": 0,
- "holdingTime": {
- "unit": "minutes",
- "value": 0
}, - "attributes": [
- {
- "name": "string",
- "values": [
- "string"
]
}
]
}, - "metadata": { }
}
]
}
], - "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 all passes
GET /v0/passes
This endpoint fetches a list of all passes associated with your project. Each pass represents an Apple or Google pass that has been generated for a specific wallet, NFT, or policy.
To tailor the response to your specific needs, you have the flexibility to filter the passes based on multiple parameters including scanning times, creation times, expiration status, platform type (Apple or Google), chain type, network, owner`s wallet address, contract address, and token ID.
The endpoint also allows for sorting the results based on a specific field such as id
, ownerAddress
, createdAt
, lastScannedAt
, expiredAt
, or platform
. The order of the results can be set to ascending or descending using the asc
query parameter.
You can also manage the number of results returned with the limit
parameter and skip certain results using the offset
parameter. By default, the response will include a maximum of 50 passes.
Each retrieved pass will contain comprehensive details including the ID, platform, blockchain network, owner address, token ID, contract address, creation time, last scanned time, and expiration status.
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 295 296 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",
- "policies": [
- {
- "name": "string",
- "chain": {
- "name": "evm",
- "network": 1
}, - "ruleEvaluation": "ALL",
- "minRules": 0,
- "rules": [
- {
- "type": "COLLECTION",
- "satisfiesRule": 0,
- "data": {
- "contractAddress": "string",
- "tokenIds": [
- 0
], - "balance": 0,
- "holdingTime": {
- "unit": "minutes",
- "value": 0
}, - "attributes": [
- {
- "name": null,
- "values": [ ]
}
]
}, - "metadata": { }
}
]
}
], - "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}
This endpoint enables you to fetch the details of a specific pass by its unique identifier (ID). The pass ID could either be obtained from the creation of the pass or by querying the endpoint GET /v0/passes.
The pass details returned will encompass all pertinent data regarding the pass, including the platform it pertains to (Apple or Google), associated blockchain network, owner's wallet address, token ID, contract address, creation time, last scanned time, and expiration status.
To delve into the pass's scan history, you have the option to include parameters scanHistoryStartTime
and `scanHistoryEndTime``. These parameters help filter out barcode scans in the pass's history that occurred within the specified time range. The time is provided as a Unix timestamp in seconds.
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",
- "policies": [
- {
- "name": "string",
- "chain": {
- "name": "evm",
- "network": 1
}, - "ruleEvaluation": "ALL",
- "minRules": 0,
- "rules": [
- {
- "type": "COLLECTION",
- "satisfiesRule": 0,
- "data": {
- "contractAddress": "string",
- "tokenIds": [
- 0
], - "balance": 0,
- "holdingTime": {
- "unit": "minutes",
- "value": 0
}, - "attributes": [
- {
- "name": "string",
- "values": [
- "string"
]
}
]
}, - "metadata": { }
}
]
}
], - "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}
This endpoint enables you to update specific fields of an existing pass for either Apple Wallet or Google Wallet. The pass ID, which is a mandatory parameter, helps identify the specific pass to be updated.
You can modify various pass details such as the encoded message in the barcode, custom images on your pass, or other aspects of the pass linked to Apple or Google platforms.
Moreover, if you want to change the barcode information, you can provide the updated details in the request body following the BarcodeInput schema.
Changes in pass details related to Apple Wallet or Google Wallet can also be made, guided by their respective schemas, i.e., PublicApplePass or PublicGooglePass.
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",
- "format": "QR",
- "encoded": true,
}, - "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}
This endpoint invalidates a pass associated with the provided ID. Upon executing this operation, the pass will be removed from the user's Apple Wallet or Google Wallet, thereby preventing any further use. Please note that once a pass is invalidated, it cannot be reinstated; a new pass must be generated if required.
Note: A new API endpoint will be released soon, which will provide the functionality to reinstate an existing pass if required.
It's crucial to understand that invalidating a pass does not result in the deletion of its record from the database. Rather, it simply modifies the status of the pass to inactive, indicating that the pass is no longer in use.
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",
- "policies": [
- {
- "name": "string",
- "chain": {
- "name": "evm",
- "network": 1
}, - "ruleEvaluation": "ALL",
- "minRules": 0,
- "rules": [
- {
- "type": "COLLECTION",
- "satisfiesRule": 0,
- "data": {
- "contractAddress": "string",
- "tokenIds": [
- 0
], - "balance": 0,
- "holdingTime": {
- "unit": "minutes",
- "value": 0
}, - "attributes": [
- {
- "name": "string",
- "values": [
- "string"
]
}
]
}, - "metadata": { }
}
]
}
], - "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
This endpoint facilitates the redistribution of a pass, meaning it allows for the retrieval of a specific Apple Wallet or Google Wallet pass URL. Users can access this URL to download their respective passes.
The mandatory parameter is the pass ID or the user-provided externalId
. It uniquely identifies the specific pass you want to redistribute.
Upon success, the response will include the file URL from where the user can download their pass. For Apple passes, an additional file buffer will be returned.
Redistributing a pass is particularly useful in cases where a pass needs to be reissued, if there is an update in the pass details, or if the user misplaced the initial pass. This helps maintain access to the services associated with the pass without any disruptions.
Note: Distribution links are designed to expire automatically 48 hours after they are first accessed as a security measure. Additionally, any pre-existing distribution links will automatically expire upon the creation of a new link for the same 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
{- "scanResult": {
- "valid": true,
- "nft": {
- "contractAddress": "0x79c1d53f15e34895d608ff47ee56ad1f0f3f45d3",
- "tokenId": "315",
- "contractInterface": "0x80ac58cd",
- "valid": true
}
}, - "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",
- "policies": [
- {
- "name": "string",
- "chain": {
- "name": "evm",
- "network": 1
}, - "ruleEvaluation": "ALL",
- "minRules": 0,
- "rules": [
- {
- "type": "COLLECTION",
- "satisfiesRule": 0,
- "data": {
- "contractAddress": "string",
- "tokenIds": [
- 0
], - "balance": 0,
- "holdingTime": {
- "unit": "minutes",
- "value": 0
}, - "attributes": [
- {
- "name": "string",
- "values": [
- "string"
]
}
]
}, - "metadata": { }
}
]
}
], - "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 a new policy
POST /v0/policies
This endpoint allows you to create a new policy within your project.
A policy includes attributes such as the policy name, the chain on which it operates, the rule evaluation method, the minimum number of rules required, and the specific array of rules applicable to that policy.
Authorizations:
Request Body schema: application/json
name | string |
object (ChainInput) | |
ruleEvaluation | string (PolicyRuleEvaluation) Enum: "ALL" "ANY" "SOME" |
minRules | number Minimum number of rules that must be satisfied if |
Array of objects (PolicyRule) |
Responses
Request samples
- Payload
{- "name": "string",
- "chain": {
- "name": "evm",
- "network": 1
}, - "ruleEvaluation": "ALL",
- "minRules": 0,
- "rules": [
- {
- "type": "COLLECTION",
- "satisfiesRule": 0,
- "data": {
- "contractAddress": "string",
- "tokenIds": [
- 0
], - "balance": 0,
- "holdingTime": {
- "unit": "minutes",
- "value": 0
}, - "attributes": [
- {
- "name": "string",
- "values": [
- "string"
]
}
]
}, - "metadata": { }
}
]
}
Response samples
- 200
- 400
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "chain": {
- "name": "evm",
- "network": 1
}, - "ruleEvaluation": "ALL",
- "minRules": 0,
- "rules": [
- {
- "type": "COLLECTION",
- "satisfiesRule": 0,
- "data": {
- "contractAddress": "string",
- "tokenIds": [
- 0
], - "balance": 0,
- "holdingTime": {
- "unit": "minutes",
- "value": 0
}, - "attributes": [
- {
- "name": "string",
- "values": [
- "string"
]
}
]
}, - "metadata": { }
}
]
}
Get all policies
GET /v0/policies
This endpoint provides a comprehensive list of all policies that have been created in your project.
Each policy retrieved will include detailed attributes such as the policy name, the type of chain it operates on, the rule evaluation criteria, the minimum number of rules required, and an array of associated rules.
Authorizations:
Responses
Response samples
- 200
- 400
{- "count": 0,
- "policies": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "chain": {
- "name": "evm",
- "network": 1
}, - "ruleEvaluation": "ALL",
- "minRules": 0,
- "rules": [
- {
- "type": "COLLECTION",
- "satisfiesRule": 0,
- "data": {
- "contractAddress": "string",
- "tokenIds": [
- 0
], - "balance": 0,
- "holdingTime": {
- "unit": "minutes",
- "value": 0
}, - "attributes": [
- {
- "name": "string",
- "values": [
- "string"
]
}
]
}, - "metadata": { }
}
]
}
]
}
Get a single policy
GET /v0/policies/{id}
This endpoint retrieves detailed information for a specific policy that has been created within your project.
The retrieved policy includes an array of comprehensive attributes, such as the policy name, the type of chain it operates on, the rule evaluation method, the minimum number of rules required, and an extensive list of associated rules.
Authorizations:
path Parameters
id required | string Policy ID |
Responses
Response samples
- 200
- 400
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "chain": {
- "name": "evm",
- "network": 1
}, - "ruleEvaluation": "ALL",
- "minRules": 0,
- "rules": [
- {
- "type": "COLLECTION",
- "satisfiesRule": 0,
- "data": {
- "contractAddress": "string",
- "tokenIds": [
- 0
], - "balance": 0,
- "holdingTime": {
- "unit": "minutes",
- "value": 0
}, - "attributes": [
- {
- "name": "string",
- "values": [
- "string"
]
}
]
}, - "metadata": { }
}
]
}
Update a policy
PATCH /v0/policies/{id}
This endpoint allows you to update the details of an existing policy within your project.
Updating a policy entails modifying the existing attributes such as the policy name, the type of chain it operates on, the rule evaluation method, the minimum number of rules required, and the specific set of associated rules.
Authorizations:
path Parameters
id required | string Policy ID |
Request Body schema: application/json
name | string |
object (ChainInput) | |
ruleEvaluation | string (PolicyRuleEvaluation) Enum: "ALL" "ANY" "SOME" |
minRules | number Minimum number of rules that must be satisfied if |
Array of objects (PolicyRule) |
Responses
Request samples
- Payload
{- "name": "string",
- "chain": {
- "name": "evm",
- "network": 1
}, - "ruleEvaluation": "ALL",
- "minRules": 0,
- "rules": [
- {
- "type": "COLLECTION",
- "satisfiesRule": 0,
- "data": {
- "contractAddress": "string",
- "tokenIds": [
- 0
], - "balance": 0,
- "holdingTime": {
- "unit": "minutes",
- "value": 0
}, - "attributes": [
- {
- "name": "string",
- "values": [
- "string"
]
}
]
}, - "metadata": { }
}
]
}
Response samples
- 200
- 400
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "chain": {
- "name": "evm",
- "network": 1
}, - "ruleEvaluation": "ALL",
- "minRules": 0,
- "rules": [
- {
- "type": "COLLECTION",
- "satisfiesRule": 0,
- "data": {
- "contractAddress": "string",
- "tokenIds": [
- 0
], - "balance": 0,
- "holdingTime": {
- "unit": "minutes",
- "value": 0
}, - "attributes": [
- {
- "name": "string",
- "values": [
- "string"
]
}
]
}, - "metadata": { }
}
]
}
Delete a policy
DELETE /v0/policies/{id}
This endpoint enables you to delete a specific policy associated with your project.
Deleting a policy involves the removal of the existing set of rules and parameters. This action is generally taken when a policy is no longer necessary or relevant to your project's current requirements or operational strategy.
Authorizations:
path Parameters
id required | string Policy ID |
Responses
Response samples
- 200
- 400
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "chain": {
- "name": "evm",
- "network": 1
}, - "ruleEvaluation": "ALL",
- "minRules": 0,
- "rules": [
- {
- "type": "COLLECTION",
- "satisfiesRule": 0,
- "data": {
- "contractAddress": "string",
- "tokenIds": [
- 0
], - "balance": 0,
- "holdingTime": {
- "unit": "minutes",
- "value": 0
}, - "attributes": [
- {
- "name": "string",
- "values": [
- "string"
]
}
]
}, - "metadata": { }
}
]
}
Verify Policies
This endpoint verifies provided policies against the provided wallet addresses. Each policy object includes its identifier, validation status, and an array of rules. These rules contain their respective identifier, type, satisfaction status, and associated data.
The endpoint processes each address and policy pair, checking if the conditions of each policy rule are met. If a policy is invalid (for instance, if a rule within the policy is not satisfied), it returns a detailed error message indicating the policy ID and the reason for its failure. In the case of any other error during the execution, an appropriate error message is returned.
The successful response includes the same array of wallet addresses and policies, but each policy now also includes a satisfiesAllPolicies
boolean indicating if all its rules were satisfied. Additionally, each rule in a policy includes a 'valid' boolean showing if the rule was satisfied, and a 'results' object containing the outcomes of the rule validation.
Authorizations:
query Parameters
policyIds required | string Comma separated string of policy IDs to be verified. |
walletAddresses required | string Comma separated string of wallet addresses to be verified against the policies. |
Responses
Response samples
- 200
- 400
[- {
- "address": "acc2de7d-9959-4ca0-9dda-9b7ef1cd4c6c",
- "satisfiesAllPolicies": true,
- "policies": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "valid": true,
- "verifiedBlockNumber": 0,
- "name": "string",
- "chain": {
- "name": "evm",
- "network": 1
}, - "ruleEvaluation": "ALL",
- "minRules": 0,
- "rules": [
- {
- "type": "COLLECTION",
- "satisfiesRule": 0,
- "data": {
- "contractAddress": "string",
- "tokenIds": [
- 0
], - "balance": 0,
- "holdingTime": {
- "unit": "minutes",
- "value": 0
}, - "attributes": [
- {
- "name": "string",
- "values": [
- null
]
}
]
}, - "metadata": { },
- "valid": true,
- "results": {
- "ruleViolation": "ALLOW_LIST_CONDITION_NOT_MET",
- "currentBalance": 0,
- "tokenChecks": [
- {
- "tokenId": "string",
- "balance": 0
}
]
}
}
]
}
]
}
]
object Blockchain Details | |
signature | string Signed message |
signatureMessage | string Message displayed when requesting signature |
platform required | string (Platform) Enum: "apple" "google" |
object (EVMNFT) | |
policies | Array of strings Policy IDs |
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"
}, - "policies": [
- "string"
], - "barcode": {
- "message": "Encoded code or message here",
- "format": "QR",
- "encoded": true,
}, - "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
}
}
name | string |
object (ChainInput) | |
ruleEvaluation | string (PolicyRuleEvaluation) Enum: "ALL" "ANY" "SOME" |
minRules | number Minimum number of rules that must be satisfied if |
Array of objects (PolicyRule) |
{- "name": "string",
- "chain": {
- "name": "evm",
- "network": 1
}, - "ruleEvaluation": "ALL",
- "minRules": 0,
- "rules": [
- {
- "type": "COLLECTION",
- "satisfiesRule": 0,
- "data": {
- "contractAddress": "string",
- "tokenIds": [
- 0
], - "balance": 0,
- "holdingTime": {
- "unit": "minutes",
- "value": 0
}, - "attributes": [
- {
- "name": "string",
- "values": [
- "string"
]
}
]
}, - "metadata": { }
}
]
}
type | string (PolicyRuleType) Enum: "COLLECTION" "ERC20" "NATIVE_TOKEN" "ALLOW_LIST" "POAP" |
satisfiesRule | number A number that represents whether the rule is satisfied or not. A value of |
COLLECTION (object) or NATIVE_TOKEN (object) or ERC20 (object) or ALLOW_LIST (object) or POAP (object) | |
metadata | object |
{- "type": "COLLECTION",
- "satisfiesRule": 0,
- "data": {
- "contractAddress": "string",
- "tokenIds": [
- 0
], - "balance": 0,
- "holdingTime": {
- "unit": "minutes",
- "value": 0
}, - "attributes": [
- {
- "name": "string",
- "values": [
- "string"
]
}
]
}, - "metadata": { }
}