👨‍💻REST API

Authentication

Please review the Authentication section for details on using your API keys.

🛡️Authentication

NFT Verification

Before starting verification, we typically want to show some kind of modal or introduction window, which requires metadata about the contract. We provide an endpoint to fetch the collection name, social links and images for this purpose.

Get contract metadata

POST https://dmnd.network/verify/v1/contract/info

This endpoint returns metadata like collection name, social links and images. It's used by the Browser SDK to load data required to show the initial connection modal, and can be used to build your own connection UI.

Headers

Name	Type	Description
X-API-KEY*	String	Your public API key if used on the frontend, or secret key for backend use

Request Body

Name	Type	Description
chain*	Enum	ETH, MATIC or SOL
network*	Enum	Ethereum: mainnet, testnet-ropsten, testnet-rinkeby Polygon: mainnet, testnet-mumbai Solana: mainnet, testnet, devnet
contract*	String	Contract address or Candy Machine ID
marketplace.name	Enum	OPENSEA, LOOKS_RARE, MAGIC_EDEN or SOLANART
marketplace.slug	String	Marketplace slug, required for Solana
externalImages.avatarImage	String	Absolute URL to avatar image to override marketplace metadata. Automatically resized to 1:1 at 160px square
externalImages.bannerImage	String	Absolute URL to banner image to override marketplace metadata. Automatically resized to 3:1 at 256px height

200: OK Successful response

{
    // Response
}

400: Bad Request Request format is invalid

{
    // Response
}

403: Forbidden Invalid API key or request origin

{
    // Response
}

401: Unauthorized Invalid API key

{
    // Response
}

Before starting verification, the user must connect their wallet. This is handled by client-side code, usually with the API or SDK for the users wallet (e.g Metamask or Phantom).

In order to make sure that users own the address their wallet claims, it needs to be verified. This is done by generating a single-use message (a 'nonce'), which must be signed. Once the users wallet is connected, fetch their address and make a request to the below endpoint to get a new nonce.

Get a new nonce

POST https://dmnd.network/verify/v1/address/nonce

Generates a new nonce message which the user must sign and return to verify ownership.

Headers

Name	Type	Description
X-API-KEY*	String	Your public API key

Pass the returned nonce to the the users wallet for signing. Once the nonce has been successfully signed, we send the signature to the API for verification, along with the original nonce.

Verify the signature

POST https://dmnd.network/verify/v1/address/verify

This endpoint returns an SHA256 HMAC in the format expiration:SHA256("sk_YOUR_SECRET_KEY" + expiration + ":" + address), where expiration is a UNIX timestamp in seconds.

We use an expiring HMAC by default, however if you're generating a HMAC on your backend you can also generate an eternal version by omitting the expiration and colon, though this is not recommended.

This HMAC can be saved by your client implementation for future use, allowing users to skip the wallet connection and signature on subsequent visits, until the HMAC has expired.

Once you have a HMAC, either from this request or a previous request, you can continue to the actual verification request.

This step is technically optional as the API won't throw an error if a HMAC is not provided. However, result.wallet.verified will be false in verification results, and we do not recommend it unless using on the backend with previously verified addresses.

Unlockables require address verification by default (though this can also be disabled), so requests without a HMAC won't be able to access them.

Verify NFT ownership

POST https://dmnd.network/verify/v1/asset/nft

Yay, you've completed verification!

The response from this endpoint will include the verification result summary (whether they own at least one token, their address etc), along with the full list of tokens from the provided collection with any off-chain metadata.

Managing unlockables

You can use the API to create and manage unlockables.

List unlockables

GET https://dmnd.network/verify/v1/unlockables

Create a new unlockable

POST https://dmnd.network/verify/v1/unlockables

Get an unlockable by ID

GET https://dmnd.network/verify/v1/unlockables/:id

Path Parameters

Name	Type	Description
*	String	Unlockable ID

Update an unlockable

PUT https://dmnd.network/verify/v1/unlockables/:id

Path Parameters

Name	Type	Description
*	String	Unlockable ID

Delete an unlockable

DELETE https://dmnd.network/verify/v1/unlockables/:id

Fetch unlockable content

You may wish to manually create a signed URL to access unlockable content. You can construct this URL on your backend, by creating a JWT as below, and signing it with your app secret key. The below example uses the jsonwebtoken package, however can be adapted to any JWT library:

import jwt from "jsonwebtoken"

const appId = "YOUR_APP_ID"
const secretKey = "sk_YOUR_SECRET_KEY"
const unlockableId = "d85c8682-6179-4e20-9e00-25507e07b7c6"
 
const token = jwt.sign(
  {
    id: unlockableId,
    // Optionally you can also include an `attemptId` to tie this download
    // to a verification attempt. This should be the ID returned by /verify/nft.
    // attemptId: "85bcc566-56e1-41f9-af8f-f77c060e7b97"
  },
  secretKey,
  { algorithm: "HS256", expiresIn: "24h" }
)

const url = `https://dmnd.network/verify/v1/unlockables/download?token=${token}&appId=${appId}`

This endpoint does not support Webhook unlockables

Get unlockable content

GET https://dmnd.network/verify/v1/unlockables/download

Query Parameters

Name	Type	Description
token*	String	JWT for unlockable
appId*	String	ID of your app