Metaplex JavaScript SDK

🚨 Deprecated library

Please note that this library is no longer actively maintained. To integrate Metaplex's products with your JavaScript applications please use our various Umi libraries instead:

• 🌊 Umi Framework. GitHub / NPM
• 📦 Token Metadata. Documentation / GitHub / NPM
• 📦 Candy Machine. Documentation / GitHub / NPM
• 📦 Bubblegum. Documentation / GitHub / NPM
• 📦 Token Auth Rules. Documentation / GitHub / NPM
• 📦 Toolbox. Documentation / GitHub / NPM

---

This SDK helps developers get started with the on-chain tools provided by Metaplex. It focuses its API on common use-cases to provide a smooth developer experience whilst allowing third parties to extend its features via plugins.

Please note that this SDK has been re-implemented from scratch and is still in active development. This means some of the core API and interfaces might change from one version to another. However, feel free to use it and provide some early feedback if you wish to contribute to the direction of this project.

Installation

npm install @metaplex-foundation/js @solana/web3.js

🔥 Pro Tip: Check out our examples and starter kits on the "JS Examples" repository.

Setup

The entry point to the JavaScript SDK is a Metaplex instance that will give you access to its API.

It accepts a Connection instance from @solana/web3.js that will be used to communicate with the cluster.

import { Metaplex } from "@metaplex-foundation/js";
import { Connection, clusterApiUrl } from "@solana/web3.js";

const connection = new Connection(clusterApiUrl("mainnet-beta"));
const metaplex = new Metaplex(connection);

On top of that, you can customise who the SDK should interact on behalf of and which storage provider to use when uploading assets. We refer to these as "Identity Drivers" and "Storage Drivers" respectively. You may change these drivers by calling the use method on the Metaplex instance like so. We'll see all available drivers in more detail below.

import { Metaplex, keypairIdentity, bundlrStorage } from "@metaplex-foundation/js";
import { Connection, clusterApiUrl, Keypair } from "@solana/web3.js";

const connection = new Connection(clusterApiUrl("mainnet-beta"));
const wallet = Keypair.generate();

const metaplex = Metaplex.make(connection)
    .use(keypairIdentity(wallet))
    .use(bundlrStorage());

Notice how you can create a Metaplex instance using Metaplex.make(...) instead of new Metaplex(...) in order to make the fluent API more readable.

Usage

Once properly configured, that Metaplex instance can be used to access modules providing different sets of features. Currently, there is only one documented NFT module that can be accessed via the nfts() method. From that module, you will be able to find, create and update NFTs with more features to come.

For instance, here is how you can fetch an NFT by its mint address.

const nft = await metaplex.nfts().findByMint({ mintAddress });

We call findByMint an Operation on the NFT Module. Each operation accepts an input object as its first argument that is defined by the operation itself. Additionally, each operation accepts a second optional argument that is shared by all operations and used for more generic options. For instance, you may pass an AbortSignal to this second argument to cancel the operation before it finishes — similarly to how you would cancel an HTTP request.

// Create an AbortController that aborts in 100ms.
const abortController = new AbortController();
setTimeout(() => abortController.abort(), 100);

// Pass the AbortController's signal to the operation.
const nft = await metaplex.nfts().findByMint({ mintAddress }, {
    signal: abortController.signal
});

Now, let’s look into the NFT module in a bit more detail before moving on to the identity and storage drivers.

NFTs

The NFT module can be accessed via metaplex.nfts() and provides the following methods.

• findByMint
• findAllByMintList
• load
• findAllByOwner
• findAllByCreator
• uploadMetadata
• create
• update
• printNewEdition
• use

And the following model, either returned or used by the above methods.

• The Nft model

You may also be interested in browsing the API References of that module.

findByMint

The findByMint method accepts a mintAddress public key and returns an Nft object.

const mintAddress = new PublicKey("ATe3DymKZadrUoqAMn7HSpraxE4gB88uo1L9zLGmzJeL");

const nft = await metaplex.nfts().findByMint({ mintAddress });

The returned Nft object will have its JSON metadata already loaded so you can, for instance, access its image URL like so (provided it is present in the downloaded metadata).

const imageUrl = nft.json.image;

Similarly, the Edition information of the NFT — original or printed — is also available on the object via the edition property. Its type depends on whether the NFT is the original or a printed edition.

const editionAddress = nft.edition.address;

if (nft.edition.isOriginal) {
    const totalPrintedNfts = nft.edition.supply;
    const maxNftsThatCanBePrinted = nft.edition.maxSupply;
} else {
    const mintAddressOfOriginalNft = nft.edition.parent;
    const editionNumber = nft.edition.number;
}

You can read more about the NFT model below.

findAllByMintList

The findAllByMintList operation accepts an array of mint addresses and returns an array of NFTs. However, null values will be returned for each provided mint address that is not associated with an NFT.

Note that this is much more efficient than calling findByMint for each mint in the list as the SDK can optimise the query and fetch multiple NFTs in much fewer requests.

const [nftA, nftB] = await metaplex.nfts().findAllByMintList({
    mints: [mintA, mintB]
});

NFTs retrieved via findAllByMintList may be of type Metadata rather than Nft.

What this means is they won't have their JSON metadata loaded because this would require one request per NFT and could be inefficient if you provide a long list of mint addresses. Additionally, you might want to fetch these on-demand, as the NFTs are being displayed on your web app for instance. The same goes for the edition property which requires an extra account to fetch and might be irrelevant until the user clicks on the NFT.

Note that, since plugins can swap operation handlers with their own implementations, it is possible that a plugin relying on indexers return an array of Nfts directly instead of Metadatas. The default implementation though, will return Metadatas.

Thus, if you want to load the json and/or edition properties of an NFT, you need to load that Metadata into an Nft. Which you can do with the next operation.

load

For performance reasons, when fetching NFTs in bulk, you may receive Metadatas which exclude the JSON Metadata and the Edition information of the NFT. In order to transform a Metadata into an Nft, you may use the load operation like so.

const nft = await metaplex.nfts().load({ metadata });

This will give you access to the json and edition properties of the NFT as explained in the NFT model documentation.

findAllByOwner

The findAllByOwner method accepts a public key and returns all NFTs owned by that public key.

const myNfts = await metaplex.nfts().findAllByOwner({
    owner: metaplex.identity().publicKey
});

Similarly to findAllByMintList, the returned NFTs may be Metadatas.

findAllByCreator

The findAllByCreator method accepts a public key and returns all NFTs that have that public key registered as their first creator. Additionally, you may provide an optional position parameter to match the public key at a specific position in the creator list.

const nfts = await metaplex.nfts().findAllByCreator({ creator });
const nfts = await metaplex.nfts().findAllByCreator({ creator, position: 1 }); // Equivalent to the previous line.
const nfts = await metaplex.nfts().findAllByCreator({ creator, position: 2 }); // Now matching the second creator field.

Similarly to findAllByMintList, the returned NFTs may be Metadatas.

uploadMetadata

When creating or updating an NFT, you will need a URI pointing to some JSON Metadata describing the NFT. Depending on your requirement, you may do this on-chain or off-chain.

If your JSON metadata is not already uploaded, you may do this using the SDK via the uploadMetadata method. It accepts a metadata object and returns the URI of the uploaded metadata. Where exac