✨Browser SDK
Verify includes a Javascript SDK which handles showing a wallet connection UI, making API requests and returning results. This is the recommended way of interacting with Verify, but we also have a REST API if you want to build your own UI.
Installation
Install the SDK via NPM or by importing with a <script>
tag.
Install the SDK from NPM
npm install --save @diamondhh/verify
Import the combined bundle for all supported chains
import VerifySdk from '@diamondhh/verify'
Or import a chain specific bundle (supports tree shaking)
import VerifySdk from '@diamondhh/verify/solana' // OR
import VerifySdk from '@diamondhh/verify/ethereum' // Also supports Polygon
The SDK will automatically inject the required stylesheet, no CSS import required.Import the default CSS in your <head>
Usage
Initialise the SDK
Before you can use Verify you need to set your API key. You can get an API key for free by registering on Diamond Hands Hotel.
When using the Browser SDK or calling the API from the client side you must use your public key. You must never share your secret key (used for verifying results on the backend) as it could also be used to forge a successful verification.
const verify = new VerifySdk("pk_YOUR_PUBLIC_KEY")
Make a request
Now the SDK is set up you're ready to start making requests. The quickest way to get started is to read the example below and review the comments for detailed information. This example uses all available options, but only chain
and contract
are required.
const res = await verify.nft({
// Chain symbol: SOL, ETH or MATIC (Polygon)
chain: "SOL",
// Network: options are chain specific, see table below
// Defaults to mainnet if not provided
// network: "testnet",
// Contract address or Candy Machine ID (Solana)
contract: "6p9xpokmE8PcK4VBwBk6nf6PYoBwWUDsYxjMy7erRjpw",
// Provide marketplace information and Verify will automatically fetch
// your avatar and banner images, social links & add a puchase button.
marketplace: {
// Marketplace name: OPENSEA, LOOKS_RARE, MAGIC_EDEN, SOLANART
// Valid marketplace options will depend on your chain
name: "MAGIC_EDEN",
// Slug is only required for Solana NFTs as the collection can't
// be found automatically. The slug is found at the end of your listing
// URL, for example magiceden.io/marketplace/[your slug]
slug: "space_sneks_society"
},
// You can override the collection metadata or provide manually if
// your collection isn't listed yet. Images must be absolute URLs, and
// will be resized automatically. All fields are optional and will be
// merged with marketplace data.
metadata: {
name: "My Awesome NFT",
avatarImage: "https://mynft.com/assets/avatar.png",
bannerImage: "https://mynft.com/assets/banner.png",
socials: [{
type: "TWITTER",
url: "https://twitter.com/MyAwesomeNFT"
}, {
type: "DISCORD",
url: "https://discord.gg/MyAwesomeNFT"
}, {
type: "WEB",
url: "https://myawesomenft.com"
}
},
// Add unlockable content, which only users who pass verification can
// access. Configure unlockables through the web dashboard or via
// the API. Only unlockables for the correct chain/contract will be
// returned (invalid unlockables are silently ignored).
//
// This also works with Webhook unlockables, allowing you to return
// dynamic content based on the results of the user verification.
// Unlike other unlockable types, webhook unlockables are executed
// even if the verification fails allowing you to update a users
// account to revoke access if they previously had it.
//
// You can provide as an array of unlockable names to return or just
// pass 'true' to fetch all available unlockables.
// unlockables: true,
unlockables: ["my-video"],
// Link the request to some data in your system by passing an arbirary
// data string up to 512 bytes. We highly recommend you also provide a HMAC
// signature = SHA256("sk_YOUR_SECRET_KEY" + value) which will
// ensure the data isn't tampered with before the verification request.
// You can also include an object by converting it to a string first.
//
// If a HMAC isn't provided the request will still succeed but
// `result.data.verified` will be false. DO NOT CALCULATE THE HMAC CLIENT
// SIDE. Your secret key must never be transmitted to end users.
//
// This is entirely optional, and has no effect on operation other than
// including the provided data in the verification results. Usually used
// alongside webhook unlockables to perform a side effect based on the
// verification results. Possible uses cases include:
// * passing an email address to subcribe to a holders mailing list
// * passing a user ID and upgrading them to a premium membership
// * passing a user ID and linking to their wallet address for
// wallet-based login
data: {
value: "{\"email\":\"[email protected]\"}",
hmac: "b12f8da26ff8f64f6ae22db5e78d49b8504a4bc446203a4247d5e8990d1fe3e7"
},
})
chain
SOL
ETH
MATIC
Chain to find the contract on
contract
String
Ethereum & Polygon Contract address Solana
Candy Machine program address
network
Solana
mainnet
testnet
devnet
Ethereum
mainnet
goerli
rinkeby
Polygon
mainnet
mumbai
Network to use, defaults to mainnet
marketplace.name
OPENSEA
LOOKS_RARE
MAGIC_EDEN
SOLANART
Marketplace to fetch collection metadata from
marketplace.slug
String
Required if a marketplace name is provided and the chain is SOL
metadata.name
String
Collection name
metadata.avatarImage
URL
Avatar image (must be an absolute URL)
metadata.bannerImage
URL
Banner image (must be an absolute URL)
metadata.socials
Object[]
Social links to display. Valid options for type
are WEB
, TWITTER
and DISCORD
data.value
String
Arbitrary data that will be included in the signed result
data.hmac
String
Recommended with data.value
SHA256 HMAC of the data, where the key is your secret key. If a HMAC is provided but invalid an error will be thrown.
Get results
res
will resolve to an object with the results of the verification request once the user has completed the verification (either passing or failing). If aborted without completing, the call will throw an error.
// console.log(res)
{
"result": {
"at": "1643732888",
"ownership": true,
"wallet": {
"address": "sneksprLoHxxRAyLS9W4oZibXRJX9Q69m1Bnv2hRCAE",
"verified": true
},
"data": {
"value": "{\"email\":\"[email protected]\"}",
"verified": true
}
},
"asset": {
"chain": "SOL",
"network": "mainnet",
"contract": "6p9xpokmE8PcK4VBwBk6nf6PYoBwWUDsYxjMy7erRjpw",
"symbol": "SNEK"
},
"tokens": [{
"id": "FuSrkrUnGf2KRHeMvEFh2jpJ55NHwfh3syifebVoPBDS",
"uri": "https://arweave.net/eOGTCQTp1J95o2pzxTt_yinrtuPVVGlgfP4UyE5P2p0",
"metadata": {
"name": "Space Sneks #279",
"description": "An ultra exclusive society of 1,024 highly evolved Sneks, that travelled the cosmos to open the Diamond Hands Hotel.",
"image": "https://www.arweave.net/6YBdvGHAyNc4wLp4hQDDvT-2ytMHaknVTR59cwpw8dI?ext=png",
"collection": {
"name": "Space Sneks",
"family": "Diamond Hands Hotel"
},
"attributes": [
{
"trait_type": "Other",
"value": "Blue Laser"
}
]
}
}],
"unlockables": [
{
"name": "secret-video",
"type": "video",
"content": "https://dmnd.network/verify/v1/get-unlockable?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjcwZTgzMzk5LWVkYTAtNGExNi1hZDhlLWQ5MjVlMDRiNzQzNyIsImlhdCI6MTUxNjIzOTAyMn0.zHXeuqwpyXBwK-27wrGkV_uvrmK_t60uk1ihiGig82w&appId=2da62f65-543b-4338-a68a-9104f6c31b56",
"createdAt": "2022-02-18T14:37:00.387Z",
"updatedAt": null,
}
],
"signed": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2ZXJpZmllZCI6eyJvd25lcnNoaXAiOnRydWUsIndhbGxldCI6dHJ1ZSwiYWRkcmVzcyI6InNuZWtzcHJMb0h4eFJBeUxTOVc0b1ppYlhSSlg5UTY5bTFCbnYyaFJDQUUiLCJhdCI6IjE2NDM3MzI4ODgifSwiYXNzZXQiOnsiY2hhaW4iOiJTT0wiLCJjb250cmFjdCI6IjZwOXhwb2ttRThQY0s0VkJ3Qms2bmY2UFlvQndXVURzWXhqTXk3ZXJSanB3Iiwic3ltYm9sIjoiU05FSyJ9LCJvd25lZCI6W3siaWQiOm51bGwsImFkZHJlc3MiOiJGdVNya3JVbkdmMktSSGVNdkVGaDJqcEo1NU5Id2ZoM3N5aWZlYlZvUEJEUyIsIm1ldGFkYXRhIjp7Im5hbWUiOiJTcGFjZSBTbmVrcyAjMjc5IiwiZGVzY3JpcHRpb24iOiJBbiB1bHRyYSBleGNsdXNpdmUgc29jaWV0eSBvZiAxLDAyNCBoaWdobHkgZXZvbHZlZCBTbmVrcywgdGhhdCB0cmF2ZWxsZWQgdGhlIGNvc21vcyB0byBvcGVuIHRoZSBEaWFtb25kIEhhbmRzIEhvdGVsLiIsImltYWdlIjoiaHR0cHM6Ly93d3cuYXJ3ZWF2ZS5uZXQvNllCZHZHSEF5TmM0d0xwNGhRRER2VC0yeXRNSGFrblZUUjU5Y3dwdzhkST9leHQ9cG5nIiwiY29sbGVjdGlvbiI6eyJuYW1lIjoiU3BhY2UgU25la3MiLCJmYW1pbHkiOiJEaWFtb25kIEhhbmRzIEhvdGVsIn0sImF0dHJpYnV0ZXMiOlt7InRyYWl0X3R5cGUiOiJPdGhlciIsInZhbHVlIjoiQmx1ZSBMYXNlciJ9XX19XX0.JnxguNAeT37upXgx9R_8-vGS4WiVQ487F3RttDubJr0"
}
Result
result
holds a summary of the verification result.
If using Webhook unlockables you MUST check the value of ownership
and data.verified
as webhooks will be executed regardless of verification success.
ownership
Boolean
Whether the wallet owns at least one NFT from the provided contract
wallet.address
String
The wallet address that was checked
wallet.verified
Boolean
Whether wallet ownership was also verified.
false
if you provided wallet.address
to the verification request without passing a HMAC.
data.value
String
Arbitrary data that was passed to the verification request
data.verified
Boolean
true
if a valid data HMAC was provided.
false
if a HMAC was not provided.
Request will throw an error if an invalid HMAC was provided.
at
String
Unix millis timestamp of the verification
Asset
asset
has some basic information about the contract verified.
chain
SOL
ETH
MATIC
Contract chain
network
Solana
mainnet
testnet
devnet
Ethereum
mainnet
goerli
rinkeby
Polygon
mainnet
mumbai
Contract network
contract
String
Contract address
symbol
String
Symbol declared in the metadata
Tokens
tokens
is an array of NFTs from the provided contract that the wallet owns. If the user owns no NFTs from the contract then this array will be empty. NFTs from other contracts are not returned (you should make another request to fetch results from multiple collections).
id
String
Ethereum & Polygon Token ID Solana Address of the token
uri
URL
Source URL of off-chain metadata
metadata
Object
EIP-1155 compatible token metadata. Available properties will vary depending on the NFT and chain.
Unlockables
unlockables
is an array of valid unlockables which were requested. Any unlockables which aren't found or don't match the chain/contract settings will be silently ignored.
name
String
Name of the unlockable
type
image
video
file
json
text
webhook
Type of unlockable
content
Object
String
URL
Image, video and file unlockables will return a pre-signed URL that can be used to access the file.
JSON unlockables will return an Object.
Text unlockables will return a String.
Webhook unlockables will return an Object if the Content-Type
header is application/json
, otherwise will return a String.
createdAt
Date
Creation date
updatedAt
Date
Last modification date
error
Object
Webhook unlockables which throw an error will return an object with code
and message
properties (see Errors)
Verifying results
Included in the results object is a signed
property. This is a JSON Web Token signed with your secret key, where the payload is the full results object excluding unlockables
.
You can pass this string to your backend and verify it using any JWT library. Below is an example using the jsonwebtoken
library.
import jwt from 'jsonwebtoken'
try {
// Pass the `signed` property to your backend
const signed = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2ZXJpZmllZCI6eyJvd25lcnNoaXAiOnRydWUsIndhbGxldCI6dHJ1ZSwiYWRkcmVzcyI6InNuZWtzcHJMb0h4eFJBeUxTOVc0b1ppYlhSSlg5UTY5bTFCbnYyaFJDQUUiLCJhdCI6IjE2NDM3MzI4ODgifSwiYXNzZXQiOnsiY2hhaW4iOiJTT0wiLCJjb250cmFjdCI6IjZwOXhwb2ttRThQY0s0VkJ3Qms2bmY2UFlvQndXVURzWXhqTXk3ZXJSanB3Iiwic3ltYm9sIjoiU05FSyJ9LCJvd25lZCI6W3siaWQiOm51bGwsImFkZHJlc3MiOiJGdVNya3JVbkdmMktSSGVNdkVGaDJqcEo1NU5Id2ZoM3N5aWZlYlZvUEJEUyIsIm1ldGFkYXRhIjp7Im5hbWUiOiJTcGFjZSBTbmVrcyAjMjc5IiwiZGVzY3JpcHRpb24iOiJBbiB1bHRyYSBleGNsdXNpdmUgc29jaWV0eSBvZiAxLDAyNCBoaWdobHkgZXZvbHZlZCBTbmVrcywgdGhhdCB0cmF2ZWxsZWQgdGhlIGNvc21vcyB0byBvcGVuIHRoZSBEaWFtb25kIEhhbmRzIEhvdGVsLiIsImltYWdlIjoiaHR0cHM6Ly93d3cuYXJ3ZWF2ZS5uZXQvNllCZHZHSEF5TmM0d0xwNGhRRER2VC0yeXRNSGFrblZUUjU5Y3dwdzhkST9leHQ9cG5nIiwiY29sbGVjdGlvbiI6eyJuYW1lIjoiU3BhY2UgU25la3MiLCJmYW1pbHkiOiJEaWFtb25kIEhhbmRzIEhvdGVsIn0sImF0dHJpYnV0ZXMiOlt7InRyYWl0X3R5cGUiOiJPdGhlciIsInZhbHVlIjoiQmx1ZSBMYXNlciJ9XX19XX0.JnxguNAeT37upXgx9R_8-vGS4WiVQ487F3RttDubJr0"
const result = jwt.verify(signed, "sk_YOUR_SECRET_KEY")
} catch (err) {
// Signature has been tampered with
}
Events
You can listen for events from Verify to update the state of your application.
verify.on('opened', () => {
// The verify modal was opened
})
verify.on('closed', () => {
// The verify modal was closed
})
verify.on('contract_metadata', (data) => {
// Metadata for the contract has been loaded
})
verify.on('wallet_connected', data => {
// When the users wallet has been connected successfully
})
verify.on('wallet_verified', data => {
// The user has signed the nonce and it was valid
})
verify.on('results', data => {
// IMPORTANT: this event does not confirm the user owns the
// requested NFT. You should check the event data which
// follows the same format as the results object
})
verify.on('error', data => {
// There was an error during verification. These errors are not
// nessecarily fatal as the user can retry within the request.
// The main verify.nft() promise will reject in the event of a
// fatal error.
})
Last updated
Was this helpful?