Attach exclusive content to your NFTs, only accessible by holders
Unlockables are secret files or data which can only be access by holders of your NFT. You can use unlockables to include HD versions of artwork, source files, 3D models or any other digital download with the purchase of your NFT.
You can even include dynamic data with Webhook unlockables, which send a copy of the results to your API for custom processing, before returning the response in the verification results. This can be used to return different files depending on the number of tokens a user has or token traits, or to perform an additional action like subscribing the user to a holders-only mailing list.
You don't need to make any changes to your smart contract, and unlockables can be added to existing contracts which have already been deployed.
There are three main types of unlockables:
- Files (images, videos or digital downloads)
- JSON or Plain Text
- Webhooks (dynamic content)
You can create as many unlockables as you like, and request specific (or all) be returned in verification results. For more information on using unlockables with the Browser SDK, check out the SDK usage.
Before creating your unlockable, you need to upload the file to some publicly accessible location. All requests are proxied through the Verify API, so this location won't be revealed to end users.
You can upload these files anywhere, but we recommend using S3 or similar object storage, with a randomized filename or hash to prevent the URL being easily guessed. You should not link to this location from your website or any publicly accessible content, as it would reveal the origin URL which could be accessed without authentication.
We also support IPFS URLs (using the
ipfs://protocol) which will be automatically proxied without revealing the CID to end users
For maximum security you can set firewall rules to disable access except from the Diamond Network servers by whitelisting the following IP addresses:
To return arbitrary JSON or plain text, create an unlockable as described below and provide a static JSON object or text to return. This is useful for revealing store discount codes, secret URLs and other data which doesn't need to change depending on the verification results.
Webhook unlockables are the most flexible, but require you to implement an API endpoint to process the request and generate a response.
Webhook unlockables are executed for every request, regardless of whether it was successful. This allows you to revoke access if a previously verified user no longer has your NFT, but you cannot assume all attempts are verified as holders.
You should always validate the signed JWT in webhook requests to ensure the request hasn't been forged
On a verification request, your endpoint will receive a
POSTrequest with a JSON body in the same format as the results object from the Browser SDK. Your application can perform additional processing and filtering before returning a response which will then be returned to the user.
- Must return a
- Must return a
- Must return a response within 10 seconds or the request will timeout
If you'd like to return dynamic files from a webhook unlockable, we recommend uploading your files to a private S3 bucket (or similar object storage) and return signed URLs to grant temporary access (this is similar to how native file unlockables work).
You can include arbitrary data in verification requests, which will be passed to Webhook unlockables. This is useful for linking requests to a user ID in your system, or passing additional data like an email address to the webhook handler.
Data must be encoded as a string, with a maximum length of 512 characters.
This data will be included in the verification results under
Hold up: did you spot the issue? The data value is provided on the frontend, so the user could tamper with it (for example, change it to a friends email to get them subscribed)
There is an additional parameter you can pass:
hmac. The HMAC is a hash of your secret API key and the data
value. When a HMAC is provided, we automatically verify it and reject the request if it's invalid. You don't need to provide one, but we highly recommend it if you need to securely connect verification requests to existing user identities.
You should use a HMAC whenever your webhook needs to be sure the data passed hasn't been tampered with
Here is an example for generating a HMAC on Node.js:
const crypto = require("crypto")
const data = "[email protected]"
const key = "sk_XXXXXXXX"
We then pass this HMAC to the request along with the the data:
Or if you're using PHP (including Wordpress) you can generate the HMAC in one short line:
The Verify API will check the provided HMAC, and reject the request if the data has been changed in any way since the HMAC was generated.
In the results the data will be provided, but now
verified = trueand can be trusted.
Create a new app by clicking "Create App", or select an existing app.
Click the "Create" button next to the "Unlockables" header, and enter the settings for your unlockable.
For details on creating unlockables through the API, please refer to the API documentation:
Users are granted access to unlockables by completing a verification request, either via the Browser SDK or a custom UI. You can control the unlockables returned by providing an array of unlockable names under the
You can also grant access to unlockables manually by creating a pre-signed URL on your server. Check out the "Fetch unlockable content" docs on the REST API for details: