Metaplex

Features

Fetching Assets

Now that we know how to create and mint the various onchain accounts of our assets, let's learn how to fetch them.

Digital Assets

As mentioned in the previous page, an asset — fungible or not — requires multiple onchain accounts to be created. Depending on the Token Standard of the asset, some accounts may not be required. Here's a quick overview of these accounts:

  • Mint account (from the SPL Token program): It defines the core properties of the underlying SPL token. This is the entry point to any asset as all other accounts derive from it.
  • Metadata account: It provides additional data and features to the underlying SPL token.
  • Master Edition or Edition account (only for Non-Fungibles): It enables printing multiple copies of an original NFT. Even when an NFT does not allow printing editions, the Master Edition account is still created as it is used as the Mint authority and Freeze authority of the Mint account to ensure its non-fungibility.

In order to make fetching assets easier, our SDKs offer a set of helper methods that allow us to fetch all the relevant accounts of an asset in one go. We call the data type that stores all these accounts a Digital Asset. In the next sub-sections, we will go through the various ways to fetch Digital Assets.

Digital Asset definition

import { PublicKey } from '@metaplex-foundation/umi'

import { Mint } from '@metaplex-foundation/mpl-toolbox'

import {

  Metadata,

  MasterEdition,

  Edition,

} from '@metaplex-foundation/mpl-token-metadata'



export type DigitalAsset = {

  publicKey: PublicKey

  mint: Mint

  metadata: Metadata

  edition?:

    | ({ isOriginal: true } & MasterEdition)

    | ({ isOriginal: false } & Edition)

}

Fetch By Mint

This helper fetches a single Digital Asset from the public key of its Mint account.

1import { publicKey } from '@metaplex-foundation/umi';

2import { fetchDigitalAsset } from '@metaplex-foundation/mpl-token-metadata';

3

4// Assuming umi is set up with mplTokenMetadata plugin

5// See getting-started for full setup

6

7const mintAddress = publicKey('Ay1U9DWphDgc7hq58Yj1yHabt91zTzvV2YJbAWkPNbaK');

8

9// Fetch a digital asset by its mint address

10const asset = await fetchDigitalAsset(umi, mintAddress);

11

12console.log('Asset:', asset.publicKey);

13console.log('Metadata:', asset.metadata.publicKey);

14console.log('Name:', asset.metadata.name);

15console.log('URI:', asset.metadata.uri);

16console.log('Seller Fee:', asset.metadata.sellerFeeBasisPoints);

Fetch By Metadata

This helper fetches a single Digital Asset from the public key of its Metadata account. This is slightly less efficient than the previous helper as we first need to fetch the content of the Metadata account to find the Mint address but if you only have access to the Metadata public key, this can be helpful.

1import { publicKey } from '@metaplex-foundation/umi';

2import { fetchDigitalAssetByMetadata } from '@metaplex-foundation/mpl-token-metadata';

3

4// Assuming umi is set up with mplTokenMetadata plugin

5// See getting-started for full setup

6

7const metadataAddress = publicKey('Gz3vYbpsB2agTsAwedtvtTkQ1CG9Cpo6eTq59rrEGCKF');

8

9// Fetch a digital asset by its metadata address

10const asset = await fetchDigitalAssetByMetadata(umi, metadataAddress);

11

12console.log('Asset:', asset.publicKey);

13console.log('Metadata:', asset.metadata.publicKey);

14console.log('Name:', asset.metadata.name);

15console.log('URI:', asset.metadata.uri);

Fetch All By Mint List

This helper fetches as many Digital Assets as there are Mint public keys in the provided list.

1import { publicKey } from '@metaplex-foundation/umi';

2import { fetchAllDigitalAsset } from '@metaplex-foundation/mpl-token-metadata';

3

4// Assuming umi is set up with mplTokenMetadata plugin

5// See getting-started for full setup

6

7const mints = [

8  publicKey('Ay1U9DWphDgc7hq58Yj1yHabt91zTzvV2YJbAWkPNbaK'),

9  publicKey('8TQdiAzdZZEaKtHGjvnLMXhVGjfNsqMgPGBQPPsWYgo8'),

10];

11

12// Fetch multiple digital assets by their mint addresses

13const assets = await fetchAllDigitalAsset(umi, mints);

14

15assets.forEach((asset) => {

16  console.log('Asset:', asset.publicKey);

17  console.log('Name:', asset.metadata.name);

18});

Fetch All By Creator

This helper fetches all Digital Assets by creator. Since creators can be located in five different positions in the Metadata account, we must also provide the creator position we are interested in. For instance, if we know that for a set of NFTs, the first creator is creator A and the second creator B, we will want to search for creator A in position 1 and creator B in position 2.

This helper requires RPC calls to filter accounts and is available in the Umi SDK. For the Kit SDK, consider using a DAS (Digital Asset Standard) API provider for efficient queries.

1import { publicKey } from '@metaplex-foundation/umi';

2import { fetchAllDigitalAssetByCreator } from '@metaplex-foundation/mpl-token-metadata';

3

4// Assuming umi is set up with mplTokenMetadata plugin

5// See getting-started for full setup

6

7const creator = publicKey('creatorAddress...');

8

9// Assets where the creator is first in the Creator array

10const assetsA = await fetchAllDigitalAssetByCreator(umi, creator);

11

12// Assets where the creator is second in the Creator array

13const assetsB = await fetchAllDigitalAssetByCreator(umi, creator, {

14  position: 2,

15});

16

17console.log('Assets with creator at position 1:', assetsA.length);

18assetsA.forEach((asset) => {

19  console.log('Name:', asset.metadata.name);

20});

Fetch All By Owner

This helper fetches all Digital Assets by owner.

This helper requires RPC calls to filter accounts and is available in the Umi SDK. For the Kit SDK, consider using a DAS (Digital Asset Standard) API provider for efficient queries.

1import { publicKey } from '@metaplex-foundation/umi';

2import { fetchAllDigitalAssetByOwner } from '@metaplex-foundation/mpl-token-metadata';

3

4// Assuming umi is set up with mplTokenMetadata plugin

5// See getting-started for full setup

6

7const owner = publicKey('ownerAddress...');

8

9// Fetch all digital assets owned by a wallet

10const assets = await fetchAllDigitalAssetByOwner(umi, owner);

11

12assets.forEach((asset) => {

13  console.log('Name:', asset.metadata.name);

14  console.log('URI:', asset.metadata.uri);

15});

Fetch All By Update Authority

This helper fetches all Digital Assets from the public key of their update authority.

This helper requires RPC calls to filter accounts and is available in the Umi SDK. For the Kit SDK, consider using a DAS (Digital Asset Standard) API provider for efficient queries.

1import { publicKey } from '@metaplex-foundation/umi';

2import { fetchAllDigitalAssetByUpdateAuthority } from '@metaplex-foundation/mpl-token-metadata';

3

4// Assuming umi is set up with mplTokenMetadata plugin

5// See getting-started for full setup

6

7const updateAuthority = publicKey('updateAuthorityAddress...');

8

9// Fetch all digital assets by update authority

10const assets = await fetchAllDigitalAssetByUpdateAuthority(umi, updateAuthority);

11

12console.log('Found', assets.length, 'assets');

13assets.forEach((asset) => {

14  console.log('Name:', asset.metadata.name);

15  console.log('Mint:', asset.publicKey);

16});

Digital Assets With Token

Note that the Digital Asset data structure mentioned above does not provide any information about the owner of the asset. This first definition only focuses on the onchain accounts that are required regardless of their owners. However, in order to provide a more complete picture of an asset, we may also need to know who owns it. This is where the Digital Asset With Token data structure comes in. It is an extension of the Digital Asset data structure that also includes the following accounts:

  • Token account (from the SPL Token program): It defines the relationship between a Mint account and its owner. It stores important data such as the amount of tokens owned by the owner. In the case of NFTs, the amount is always 1.
  • Token Record account (for PNFTs only): It defines additional token-related information for Programmable Non-Fungibles such as its current Token Delegate and its role.

Note that, for fungible assets, the same Digital Asset will likely be associated with multiple owners via multiple Token accounts. Therefore, there can be multiple Digital Asset With Token for the same Digital Asset.

Here as well, we offer a set of helpers to fetch Digital Assets With Token.

Digital Asset With Token definition

import { Token } from '@metaplex-foundation/mpl-toolbox'

import {

  DigitalAsset,

  TokenRecord,

} from '@metaplex-foundation/mpl-token-metadata'



export type DigitalAssetWithToken = DigitalAsset & {

  token: Token

  tokenRecord?: TokenRecord

}

Fetch By Mint

This helper fetches a single Digital Asset With Token from the public key of its Mint account. This is mostly relevant for Non-Fungible assets since it will only return one Digital Asset With Token, regardless of how many exist for a Fungible asset.

The Kit SDK requires knowing either the token address or the owner. Use the "Fetch By Mint and Owner" helper below if you know the owner.

1import { publicKey } from '@metaplex-foundation/umi';

2import { fetchDigitalAssetWithTokenByMint } from '@metaplex-foundation/mpl-token-metadata';

3

4// Assuming umi is set up with mplTokenMetadata plugin

5// See getting-started for full setup

6

7const mint = publicKey('Ay1U9DWphDgc7hq58Yj1yHabt91zTzvV2YJbAWkPNbaK');

8

9// Fetch a digital asset with its token account by mint address

10const asset = await fetchDigitalAssetWithTokenByMint(umi, mint);

11

12console.log('Asset:', asset.publicKey);

13console.log('Name:', asset.metadata.name);

14console.log('Token Owner:', asset.token.owner);

15console.log('Token Amount:', asset.token.amount);

Fetch By Mint and Owner

This helper is more performant than the previous helper but requires that we know the owner of the asset.

1import { publicKey } from '@metaplex-foundation/umi';

2import { fetchDigitalAssetWithAssociatedToken } from '@metaplex-foundation/mpl-token-metadata';

3

4// Assuming umi is set up with mplTokenMetadata plugin

5// See getting-started for full setup

6

7const mint = publicKey('Ay1U9DWphDgc7hq58Yj1yHabt91zTzvV2YJbAWkPNbaK');

8const owner = publicKey('ownerAddress...');

9

10// Fetch a digital asset with its associated token account

11const asset = await fetchDigitalAssetWithAssociatedToken(umi, mint, owner);

12

13console.log('Asset:', asset.publicKey);

14console.log('Name:', asset.metadata.name);

15console.log('Token Owner:', asset.token.owner);

16console.log('Token Amount:', asset.token.amount);

Fetch All By Owner

This helper fetches all Digital Assets With Token from a given owner.

This helper requires RPC calls to filter accounts and is available in the Umi SDK. For the Kit SDK, consider using a DAS (Digital Asset Standard) API provider for efficient queries.

1import { publicKey } from '@metaplex-foundation/umi';

2import { fetchAllDigitalAssetWithTokenByOwner } from '@metaplex-foundation/mpl-token-metadata';

3

4// Assuming umi is set up with mplTokenMetadata plugin

5// See getting-started for full setup

6

7const owner = publicKey('ownerAddress...');

8

9// Fetch all digital assets with their token accounts by owner

10const assets = await fetchAllDigitalAssetWithTokenByOwner(umi, owner);

11

12console.log('Found', assets.length, 'assets');

13assets.forEach((asset) => {

14  console.log('Name:', asset.metadata.name);

15  console.log('Token Amount:', asset.token.amount);

16});

Fetch All By Mint

This helper fetches all Digital Assets With Token from the public key of a Mint account. This is particularly relevant for Fungible assets since it fetches all Token accounts.

This helper requires RPC calls to filter accounts and is available in the Umi SDK. For the Kit SDK, consider using a DAS (Digital Asset Standard) API provider for efficient queries.

1import { publicKey } from '@metaplex-foundation/umi';

2import { fetchAllDigitalAssetWithTokenByMint } from '@metaplex-foundation/mpl-token-metadata';

3

4// Assuming umi is set up with mplTokenMetadata plugin

5// See getting-started for full setup

6

7const mint = publicKey('Ay1U9DWphDgc7hq58Yj1yHabt91zTzvV2YJbAWkPNbaK');

8

9// Fetch all token accounts for a given mint

10const assets = await fetchAllDigitalAssetWithTokenByMint(umi, mint);

11

12console.log('Found', assets.length, 'token accounts');

13assets.forEach((asset) => {

14  console.log('Owner:', asset.token.owner);

15  console.log('Amount:', asset.token.amount);

16});

Fetch All By Owner and Mint

This helper fetches all Digital Assets With Token from both an owner and a Mint account. This can be useful for Fungible assets that have more than one Token account for a given owner.

This helper requires RPC calls to filter accounts and is available in the Umi SDK. For the Kit SDK, consider using a DAS (Digital Asset Standard) API provider for efficient queries.

1import { publicKey } from '@metaplex-foundation/umi';

2import { fetchAllDigitalAssetWithTokenByOwnerAndMint } from '@metaplex-foundation/mpl-token-metadata';

3

4// Assuming umi is set up with mplTokenMetadata plugin

5// See getting-started for full setup

6

7const owner = publicKey('ownerAddress...');

8const mint = publicKey('Ay1U9DWphDgc7hq58Yj1yHabt91zTzvV2YJbAWkPNbaK');

9

10// Fetch all token accounts for a given owner and mint

11const assets = await fetchAllDigitalAssetWithTokenByOwnerAndMint(umi, owner, mint);

12

13console.log('Found', assets.length, 'token accounts');

14assets.forEach((asset) => {

15  console.log('Token Address:', asset.token.publicKey);

16  console.log('Amount:', asset.token.amount);

17});
Next
Updating Assets