百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
J

js

> 编程语言
开源

用于与 Metaplex 程序交互的 JavaScript SDK

377 stars0 点赞1 次浏览
访问官网GitHub

工具介绍

用于与 Metaplex 程序交互的 JavaScript SDK

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

bash
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.

typescript
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.

typescript
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.

typescript
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.

typescript
// 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.

typescript
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).

typescript
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.

typescript
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.

typescript
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.

typescript
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.

typescript
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.

typescript
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 exactly the metadata will be uploaded depends on the selected StorageDriver.

typescript
const { uri } = await metaplex.nfts().uploadMetadata({
    name: "My NFT",
    description: "My description",
    image: "https://arweave.net/123",
});

console.log(uri) // https://arweave.net/789

Some properties inside that metadata object will also require you to upload some assets to provide their URI — such as the image property on the example above.

To make this process easier, the uploadMetadata method will recognise any instances of MetaplexFile within the provided object and upload them in bulk to the current storage driver. It will then create a new version of the provided metadata where all instances of MetaplexFile are replaced with their URI. Finally, it will upload that replaced metadata to the storage driver and return it.

…

Note that MetaplexFiles can be created in various different ways based on where the file is coming from. You can read more about MetaplexFile objects and how to use them here.

create

The create method accepts a variety of parameters that define the on-chain data of the NFT. The only parameters required are its name, its sellerFeeBasisPoints — i.e. royalties — and the uri pointing to its JSON metadata — remember that you can use uploadMetadata to get that URI. All other parameters are optional as the SDK will do its best to provide sensible default values.

Here's how you can create a new NFT with minimum configuration.

typescript
const { nft } = await metaplex.nfts().create({
    uri: "https://arweave.net/123",
    name: "My NFT",
    sellerFeeBasisPoints: 500, // Represents 5.00%.
});

This will take care of creating the mint account, the associated token account, the metadata PDA and the original edition PDA (a.k.a. the master edition) for you.

Additionally, since no other optional parameters were provided, it will d

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

TypeScriptblockchainjsmetaplexnft

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言