- /image
- /metadata
- Authentication Code
- Hotlink Protection & CORS Restrictions
- HTTP Status Codes
- References
nftcdn.io aims at making displaying Cardano NFTs as easy, efficient and secure as possible without requiring knowledge of the underlying standards and storage used.
The first version /image endpoint focuses on speed and security over fidelity by providing an optimized still image from CIP25 (v1+v2), CIP68 (222/333/444) and CNFT v0.01 standards image property, as well as the Mainnet Token Registry and Testnet Token Registry.
Later versions will focus on providing a more complete viewing experience.
The /image endpoint returns a token image usable in an HTML <img> tag.
Preview network
https://asset1xxx.preview.nftcdn.io/image[?size=PIXELS]
Preprod network
https://asset1xxx.preprod.nftcdn.io/image?tk=HMAC[&size=PIXELS]
Mainnet network
https://asset1xxx.YOUR_SUBDOMAIN.nftcdn.io/image?tk=HMAC[&size=PIXELS]
asset1xxx is the CIP 14 fingerprint of a token.
preview endpoint is public and does not require URLs to be authenticated.
preprod and mainnet ones are secured and require URLs to be authenticated.
The tk authentication code is described here.
Without size parameter, the original image from the NFT image property is returned in its original format.
With a size parameter in pixels, the image is rescaled if needed to have its largest side equal to size, and returned in WebP format. If the image is already smaller than the requested size, it is just converted to WebP. For animated images like GIFs, the first frame is used.
Example:
https://asset1cf4y9alel09d4xzheqcjn29mrla8f3k8pnzrdf.preview.nftcdn.io/image?size=256
<img src="https://asset1cf4y9alel09d4xzheqcjn29mrla8f3k8pnzrdf.preview.nftcdn.io/image?size=256">
The /metadata endpoint returns a token metadata in JSON format including a normalized display name.
Preview network
https://asset1xxx.preview.nftcdn.io/metadata
Preprod network
https://asset1xxx.preprod.nftcdn.io/metadata?tk=HMAC
Mainnet network
https://asset1xxx.YOUR_SUBDOMAIN.nftcdn.io/metadata?tk=HMAC
asset1xxx is the CIP 14 fingerprint of a token.
preview endpoint is public and does not require URLs to be authenticated.
preprod and mainnet ones are secured and require URLs to be authenticated.
The tk authentication code is described here.
id: Token ID (so-called "asset name" on Cardano)name: Token display name (to be displayed to users)policy: Policy IDfingerprint: CIP-14 Fingerprintdecimals: Optional number of decimals (0 by default)metadata: Token original metadata
{
"id": "537061636542756430",
"name": "SpaceBud #0",
"policy": "d5e6bf0500378d4f0da4e8dde6becec7621cd8cbf5cbb9b87013d4cc",
"fingerprint": "asset1rhmwfllvhgczltxm0y7rdump6g5p5ax4c25csq",
"metadata": {
"arweaveId": "4zXmWOWjzVZUCoEzhIzy7iCg2xs_EkdCvT0I6TYOoGg",
"image": "ipfs://QmNyHUZxfRxGpwg9QSbe3cMDkaT8so17TRvzXpNio5gbGf",
"name": "SpaceBud #0",
"traits": [
"Star Suit",
"Chestplate",
"Belt",
"Covered Helmet"
],
"type": "Frog"
}
}
Notes:
- For CIP-68 tokens, the
idandfingerprintare the reference token ones.
On mainnet, to protect our users bandwidth and prevent URL forgery, URLs must be authenticated using a SHA256 HMAC authentication code.
On preprod, the authentication code is also required for test purpose so the key is public:
7FoxfBgV2k+RSz6UUts3/fG1edG7oIGXxdtIVCdalaI=
- Build the URL including
tkparameter with an empty value - Generate the URL SHA256 HMAC using your secret key (provided in base64)
- Include the HMAC value encoded in base64url as the
tkparameter value
const crypto = require('crypto');
const { URLSearchParams } = require('url');
function nftcdnUrl(domain, key, asset, uri = "/image", params = {}) {
// 1. Set an empty value to tk and build the URL
params.tk = "";
let url = buildUrl(domain, asset, uri, params);
// 2. Generate the URL SHA256 HMAC encoded in base64url
params.tk = crypto.createHmac("sha256", key).update(url).digest("base64url");
// 3. Return the final URL including HMAC set as tk value
return buildUrl(domain, asset, uri, params);
}
function buildUrl(domain, asset, uri, params) {
const searchParams = new URLSearchParams(params);
return `https://${asset}.${domain}.nftcdn.io${uri}?${searchParams.toString()}`;
}
// Your nftcdn.io subdomain and secret key
let [domain, key] = ["preprod", Buffer.from("7FoxfBgV2k+RSz6UUts3/fG1edG7oIGXxdtIVCdalaI=", "base64")];
// Test
console.log(nftcdnUrl(domain, key, "asset1cpfcfxay6s73xez8srvhf0pydtd9yqs8hyfawv", "/image", { size: 256 }));
Working examples for preprod in JavaScript, Python, Ruby and PHP are included in the repository.
Asset fingerprints can be computed using Open Source libraries, for example https://github.com/Emurgo/cip14-js in JavaScript.
<img src="https://asset1cpfcfxay6s73xez8srvhf0pydtd9yqs8hyfawv.preprod.nftcdn.io/image?tk=ZZ388CZwJhhLzm2djfRwaaPb8I_w7luNh5hOHJ2Ev4I&size=128">
Note: The order of query parameters is not important but the same order must be used when generating the HMAC and when using the URL because it is not possible to guess the initial order when checking the URL authenticity. It is therefore possible to transmit only HMAC values to your frontend instead of full URLs as long as you keep the query parameters in the same order.
To further protect users' bandwidth, requests are restricted to a single domain and limited optional related subdomains.
Hotlink Protection check that requests Referer header match your domain. null referer is permitted as it is used by some privacy browser features or extensions and some proxies, but it is set by clients so a website cannot enforce it globally.
CORS access-control-allow-origin response header also allows only your domain.
Note:
preprod and preview endpoints do not have such restrictions.
Custom URL query parameters are allowed as long as they are included when generating an URL HMAC.
This can be useful to add internal details helping for later investigation as we plan to provide access to logs in the customer interface.
200or304is returned on success depending on request headers.400is returned on invalid requests (incorrect URL format or missing query parameters).403is returned on invalid HMAC or Referer.404is returned when the token, image or metadata is not found.