Skip to main content

Instructions

Create a Metadata account

Description

This instruction creates and initializes a new Metadata account for a given Mint account. It is required that the Mint account has been created and initialized by the Token Program before executing this instruction.

  • Name: CreateMetadataAccountV3
  • Discriminator: 33 (u8)

Accounts

NameTypeDescription
Metadata
Metadata key (pda of ['metadata', program id, mint id])
Mint
Mint of token asset
Mint Authority
Mint authority
Payer
payer
Update Authority
update authority info
System Program
System program
Rent
Rent info

Arguments

ArgumentOffsetSizeDescription
Create Metadata Account Args V 3
0~An object containing all the arguments for the CreateMetadataAccountV3 instruction.
Data
0~A data object containing the following attributes.
Name
036The on-chain name of the token, limited to 32 bytes. For instance "Degen Ape #1 ".
Symbol
3614The on-chain symbol of the token, limited to 10 bytes. For instance "DAPE".
Uri
50204The URI of the token, limited to 200 bytes. This URI points to an off-chain JSON file that contains additional data following a certain standard. You can learn more about this JSON standard here. The JSON file can either be stored in a traditional server (e.g. using AWS) or using a permanent storage solution such as using Arweave.
Seller Fee Basis Points
2542(Indicative) The royalties shared by the creators in basis points — i.e. 550 means 5.5%. Whilst this field is used by virtually all NFT marketplaces, it is not enforced by the Token Metadata program itself.
Creators
256~(Optional) An array of creators and their share of the royalties. This array is limited to 5 creators. Note that, because the Creators field is an array of variable length, we cannot guarantee the byte position of any field that follows (Notice the tilde ~ in the fields below). Each creator contains the following fields.
Address
~32The public key of the creator
Verified
~1A boolean indicating if the creator signed the NFT. It is important to check this field to ensure the authenticity of the creator.
Share
~1(Indicative) The creator's shares of the royalties in percentage (1 byte) — i.e. 55 means 55%. Similarly to the Seller Fee Basis Points field, this is used by marketplaces but not enforced by the Token Metadata program.
Collection
~34(Optional) This field optionally links to the Mint address of another NFT that acts as a Collection NFT. It contains the following sub-fields.
Verified
~1A boolean indicating if the owner of the Collection NFT signed this NFT. It is important to check this field to ensure the authenticity of the collection.
Key
~32The public key of the Collection NFT's Mint Account
Uses
~18(Optional) This field can make NFTs usable. Meaning you can load it with a certain amount of "uses" and use it until it has run out. You can learn more about using NFTs here.
Use Method
~1An enum defining the use behaviour for the NFT. It can be one of the following: Burn, Multiple or Single.
Remaining
~8The remaining amount of uses.
Total
~8The total amount of uses allowed in the first place.
Is Mutable
~1A boolean indicating if the Metadata Account can be updated. Once flipped to False, it cannot ever be True again.
Collection Details
~8(Optional) This optional enum allows us to differentiate Collection NFTs from Regular NFTs whilst adding additional context such as the amount of NFTs that are linked to the Collection NFT. You can learn more about the sized collections here

Update a Metadata account

Description

This instruction enables us to update parts of the Metadata account. Note that some fields have constraints limiting how they can be updated. For instance, once the Is Mutable field is set to False, it cannot be changed back to True.

  • Name: UpdateMetadataAccountV2
  • Discriminator: 15 (u8)

Accounts

NameTypeDescription
Metadata
Metadata account
Update Authority
Update authority key

Arguments

ArgumentOffsetSizeDescription
Update Metadata Account Args V 2
0~An object containing all the arguments for the UpdateMetadataAccountV2 instruction.
Data
0~(Optional) A data object containing the following attributes.
Name
036The on-chain name of the token, limited to 32 bytes. For instance "Degen Ape #1 ".
Symbol
3614The on-chain symbol of the token, limited to 10 bytes. For instance "DAPE".
Uri
50204The URI of the token, limited to 200 bytes. This URI points to an off-chain JSON file that contains additional data following a certain standard. You can learn more about this JSON standard here. The JSON file can either be stored in a traditional server (e.g. using AWS) or using a permanent storage solution such as using Arweave.
Seller Fee Basis Points
2542(Indicative) The royalties shared by the creators in basis points — i.e. 550 means 5.5%. Whilst this field is used by virtually all NFT marketplaces, it is not enforced by the Token Metadata program itself.
Creators
256~(Optional) An array of creators and their share of the royalties. This array is limited to 5 creators. Note that, because the Creators field is an array of variable length, we cannot guarantee the byte position of any field that follows (Notice the tilde ~ in the fields below). Each creator contains the following fields.
Address
~32The public key of the creator
Verified
~1A boolean indicating if the creator signed the NFT. It is important to check this field to ensure the authenticity of the creator.
Share
~1(Indicative) The creator's shares of the royalties in percentage (1 byte) — i.e. 55 means 55%. Similarly to the Seller Fee Basis Points field, this is used by marketplaces but not enforced by the Token Metadata program.
Collection
~34(Optional) This field optionally links to the Mint address of another NFT that acts as a Collection NFT. It contains the following sub-fields.
Verified
~1A boolean indicating if the owner of the Collection NFT signed this NFT. It is important to check this field to ensure the authenticity of the collection.
Key
~32The public key of the Collection NFT's Mint Account
Uses
~18(Optional) This field can make NFTs usable. Meaning you can load it with a certain amount of "uses" and use it until it has run out. You can learn more about using NFTs here.
Use Method
~1An enum defining the use behaviour for the NFT. It can be one of the following: Burn, Multiple or Single.
Remaining
~8The remaining amount of uses.
Total
~8The total amount of uses allowed in the first place.
Update Authority
~32(Optional) The public key that is allowed to update this account.
Primary Sale Happened
~1(Optional, Indicative) A boolean indicating if the token has already been sold at least once. Once flipped to True, it cannot ever be False again. This field can affect the way royalties are distributed.
Is Mutable
~1(Optional) A boolean indicating if the Metadata Account can be updated. Once flipped to False, it cannot ever be True again.

Burn a NFT

Description

This instruction enables the owner of the NFT to completely burn it:

  • burning the SPL token and closing the token account
  • closing the metadata and edition accounts
  • giving the owner the reclaimed funds from closing these accounts

This handler checks if the NFT is a member of a verified collection, and if it is, requires the collection metadata account be passed in so the size can be decremented.

This handler will not close metadata and edition accounts where the token has already been burned and the mint has a supply of 0. At that point there is no official "owner" of the NFT.

  • Name: BurnNft
  • Discriminator: 29 (u8)

Accounts

NameTypeDescription
Metadata
Metadata (pda of ['metadata', program id, mint id])
Owner
NFT owner
Mint
Mint of the NFT
Token Account
Token account to close
Master Edition Account
MasterEdition2 of the NFT
Spl Token Program
SPL Token Program
Collection Metadata
Metadata of the Collection

Burn an Edition NFT

Description

This instruction enables the owner of a Print Edition NFT to completely burn it:

  • burning the SPL token and closing the token account
  • closing the metadata and edition accounts
  • giving the owner the reclaimed funds from closing these accounts

This handler checks if the NFT is a Print Edition and not a Master edition, and decrements the Master Edition supply fields after burning the NFT.

The Master Edition supply is decremented every time a Print Edition is burned. If the owner of the Master Edition is not the same as the owner of the Print Edition, the max_supply is also decremented.

Print Editions burned by the owner ("the creator") of the Master Edition can be reminted, but print editions burned by other owners ("users") cannot be reminted.

This handler will not close metadata and edition accounts where the token has already been burned and the mint has a supply of 0. At that point there is no official "owner" of the NFT.

  • Name: BurnEditionNft
  • Discriminator: 37 (u8)

Accounts

NameTypeDescription
Metadata
Metadata (pda of ['metadata', program id, mint id])
Owner
NFT owner
Print Edition Mint
Mint of the print edition NFT
Master Edition Mint
Mint of the original/master NFT
Print Edition Token Account
Token account the print edition NFT is in
Master Edition Token Account
Token account the Master Edition NFT is in
Master Edition Account
MasterEdition2 of the original NFT
Print Edition Account
Print Edition account of the NFT
Edition Marker Account
Edition Marker PDA of the NFT
Spl Token Program
SPL Token Program

Indicate the primary sale has happened

Description

This instruction flips the Primary Sale Happened flag to True, indicating that the first sale has happened. Note that this field is indicative and is typically used by marketplaces to calculate royalties.

  • Name: UpdatePrimarySaleHappenedViaToken
  • Discriminator: 4 (u8)

Accounts

NameTypeDescription
Metadata
Metadata key (pda of ['metadata', program id, mint id])
Owner
Owner on the token account
Token
Account containing tokens from the metadata's mint

Verify a creator

Description

This instruction verifies one creator on the Metadata account. As long as the provided Creator account signs the transaction, the Verified boolean will be set to True on the appropriate creator of the Creators array.

  • Name: SignMetadata
  • Discriminator: 7 (u8)

Accounts

NameTypeDescription
Metadata
Metadata (pda of ['metadata', program id, mint id])
Creator
Creator

Unverify a creator

Description

This instruction unverifies one creator on the Metadata account. As long as the provided Creator account signs the transaction, the Verified boolean will be set to False on the appropriate creator of the Creators array.

  • Name: RemoveCreatorVerification
  • Discriminator: 28 (u8)

Accounts

NameTypeDescription
Metadata
Metadata (pda of ['metadata', program id, mint id])
Creator
Creator

Create a Master Edition account

Description

This instruction creates and initializes a new Master Edition account for a given Mint account. It requires the following conditions to be met:

  • The Mint account has been created and initialized by the Token Program.
  • The Mint account has zero decimals.
  • The Mint account has a supply of exactly 1 token.

If these conditions are met, it will transfer the Mint Authority and the Freeze Authority from the Mint account to the Master Edition PDA (Check the FAQ to understand why).

  • Name: CreateMasterEditionV3
  • Discriminator: 17 (u8)

Accounts

NameTypeDescription
Edition
Unallocated edition V2 account with address as pda of ['metadata', program id, mint, 'edition']
Mint
Metadata mint
Update Authority
Update authority
Mint Authority
Mint authority on the metadata's mint - THIS WILL TRANSFER AUTHORITY AWAY FROM THIS KEY
Payer
payer
Metadata
Metadata account
Token Program
Token program
System Program
System program
Rent
Rent info

Arguments

ArgumentOffsetSizeDescription
Create Master Edition Args
0~An object containing all the arguments for the CreateMasterEditionV3 instruction.
Max Supply
09(Optional) The maximum number of times NFTs can be printed from this Master Edition. When set to None, the program will enable unlimited prints. You can disable NFT printing by setting the Max Supply to 0.

Via owning the token

Description

Given a Masted Edition, this instruction creates a new Edition derived from a new Mint account.

It requires the owner of the Master Edition's Token account to sign the transaction, to prove they are allowed to print new editions from it.

It requires the same conditions as the Master Edition account regarding the Mint account, and it will also transfer the Mint Authority and the Freeze Authority from the Mint account to the new Edition PDA (Check the FAQ to understand why).

  • Name: MintNewEditionFromMasterEditionViaToken
  • Discriminator: 11 (u8)

Accounts

NameTypeDescription
New Metadata
New Metadata key (pda of ['metadata', program id, mint id])
New Edition
New Edition (pda of ['metadata', program id, mint id, 'edition'])
Master Edition
Master Record Edition V2 (pda of ['metadata', program id, master metadata mint id, 'edition'])
New Mint
Mint of new token - THIS WILL TRANSFER AUTHORITY AWAY FROM THIS KEY
Edition Mark Pda
Edition pda to mark creation - will be checked for pre-existence. (pda of ['metadata', program id, master metadata mint id, 'edition', edition_number]) where edition_number is NOT the edition number you pass in args but actually edition_number = floor(edition/EDITION_MARKER_BIT_SIZE).
New Mint Authority
Mint authority of new mint
Payer
payer
Token Account Owner
owner of token account containing master token (#8)
Token Account
token account containing token from master metadata mint
New Metadata Update Authority
Update authority info for new metadata
Metadata
Master record metadata account
Token Program
Token program
System Program
System program
Rent
Rent info

Arguments

ArgumentOffsetSizeDescription
Mint New Edition From Master Edition Via Token Args
0~An object containing all the arguments necessary to print a new edition.
Edition
08The edition number of this printed edition. For instance, the 10th printed NFT will have Edition = 10.

Via a Vault proxy

Description

This instruction is very similar to the one above, but it uses a Vault proxy instead of a Token account to prove we are allowed to print new editions from the given Master Edition.

It requires the same conditions as the Master Edition account regarding the Mint account, and it will also transfer the Mint Authority and the Freeze Authority from the Mint account to the new Edition PDA (Check the FAQ to understand why).

  • Name: MintNewEditionFromMasterEditionViaVaultProxy
  • Discriminator: 13 (u8)

Accounts

NameTypeDescription
New Metadata
New Metadata key (pda of ['metadata', program id, mint id])
New Edition
New Edition (pda of ['metadata', program id, mint id, 'edition'])
Master Edition
Master Record Edition V2 (pda of ['metadata', program id, master metadata mint id, 'edition']
New Mint
Mint of new token - THIS WILL TRANSFER AUTHORITY AWAY FROM THIS KEY
Edition Mark Pda
Edition pda to mark creation - will be checked for pre-existence. (pda of ['metadata', program id, master metadata mint id, 'edition', edition_number]) where edition_number is NOT the edition number you pass in args but actually edition_number = floor(edition/EDITION_MARKER_BIT_SIZE).
New Mint Authority
Mint authority of new mint
Payer
payer
Vault Authority
Vault authority
Safety Deposit Store
Safety deposit token store account
Safety Deposit Box
Safety deposit box
Vault
Vault
New Metadata Update Authority
Update authority info for new metadata
Metadata
Master record metadata account
Token Program
Token program
Token Vault Program
Token vault program
System Program
System program
Rent
Rent info

Arguments

ArgumentOffsetSizeDescription
Mint New Edition From Master Edition Via Token Args
0~An object containing all the arguments necessary to print a new edition.
Edition
08The edition number of this printed edition. For instance, the 10th printed NFT will have Edition = 10.

Verify a collection item

Description

This instruction verifies the collection of a Metadata account for unsized parent NFTs, by setting the Verified boolean to True on the Collection field. Calling it on a collection whose parent NFT has a size field will throw an error.

Clients should detect if a NFT is part of a sized collection or not and call the appropriate handler for the user to abstract away this detail.

  • Name: VerifyCollection
  • Discriminator: 18 (u8)

Accounts

NameTypeDescription
Metadata
Metadata account
Collection Authority
Collection Update authority
Payer
payer
Collection Mint
Mint of the Collection
Collection
Metadata Account of the Collection
Collection Master Edition Account
MasterEdition2 Account of the Collection Token

Verify a sized collection item

Description

This instruction verifies the collection of a Metadata account, by setting the Verified boolean to True on the Collection field, and increments the size field of the parent NFT. Calling it on a collection whose parent NFT does not have a size field will throw an error.

Clients should detect if a NFT is part of a sized collection or not and call the appropriate handler for the user to abstract away this detail.

  • Name: VerifySizedCollectionItem
  • Discriminator: 30 (u8)

Accounts

NameTypeDescription
Metadata
Metadata account
Collection Authority
Collection Update authority
Payer
payer
Collection Mint
Mint of the Collection
Collection
Metadata Account of the Collection
Collection Master Edition Account
MasterEdition2 Account of the Collection Token
Collection Authority Record
Collection Authority Record PDA

Unverify a collection item

Description

This instruction unverifies the collection of a Metadata account for unsized parent NFTs, by setting the Verified boolean to False on the Collection field. Calling it on a collection whose parent NFT has a size field will throw an error.

Clients should detect if a NFT is part of a sized collection or not and call the appropriate handler for the user to abstract away this detail.

  • Name: UnverifyCollection
  • Discriminator: 22 (u8)

Accounts

NameTypeDescription
Metadata
Metadata account
Collection Authority
Collection Authority
Collection Mint
Mint of the Collection
Collection
Metadata Account of the Collection
Collection Master Edition Account
MasterEdition2 Account of the Collection Token
Collection Authority Record
Collection Authority Record PDA

Unverify a sized collection item

Description

This instruction unverifies the collection of a Metadata account, by setting the Verified boolean to False on the Collection field, and increments the size field of the parent NFT. Calling it on a collection whose parent NFT does not have a size field will throw an error.

Clients should detect if a NFT is part of a sized collection or not and call the appropriate handler for the user to abstract away this detail.

  • Name: UnverifySizedCollectionItem
  • Discriminator: 31 (u8)

Accounts

NameTypeDescription
Metadata
Metadata account
Collection Authority
Collection Authority
Payer
payer
Collection Mint
Mint of the Collection
Collection
Metadata Account of the Collection
Collection Master Edition Account
MasterEdition2 Account of the Collection Token
Collection Authority Record
Collection Authority Record PDA

Set and verify the collection

Description

This instruction updates the Collection field of a Metadata account using the provided Collection Mint account as long as its Collection Authority signs the transaction and the parent NFT does not have the collection details field populated (unsized).

Clients should detect if a NFT is part of a sized collection or not and call the appropriate handler for the user to abstract away this detail.

  • Name: SetAndVerifyCollection
  • Discriminator: 25 (u8)

Accounts

NameTypeDescription
Metadata
Metadata account
Collection Authority
Collection Update authority
Payer
Payer
Update Authority
Update Authority of Collection NFT and NFT
Collection Mint
Mint of the Collection
Collection
Metadata Account of the Collection
Collection Master Edition Account
MasterEdition2 Account of the Collection Token
Collection Authority Record
Collection Authority Record PDA

Set and verify a sized collection item

Description

This instruction updates the Collection field of a Metadata account for sized collections using the provided Collection Mint account as long as its Collection Authority signs the transaction and the parent NFT has the collection details field populated (sized).

Clients should detect if a NFT is part of a sized collection or not and call the appropriate handler for the user to abstract away this detail.

  • Name: SetAndVerifySizedCollectionItem
  • Discriminator: 32 (u8)

Accounts

NameTypeDescription
Metadata
Metadata account
Collection Authority
Collection Update authority
Payer
payer
Update Authority
Update Authority of Collection NFT and NFT
Collection Mint
Mint of the Collection
Collection
Metadata Account of the Collection
Collection Master Edition Account
MasterEdition2 Account of the Collection Token
Collection Authority Record
Collection Authority Record PDA

Approve a new Collection Authority

Description

This instruction allows the provided New Collection Authority account to update the Collection field of a Metadata account.

The program keeps track of all the collection authorities that have been approved using Collection Authority Record PDAs.

  • Name: ApproveCollectionAuthority
  • Discriminator: 23 (u8)

Accounts

NameTypeDescription
Collection Authority Record
Collection Authority Record PDA
New Collection Authority
A Collection Authority
Update Authority
Update Authority of Collection NFT
Payer
Payer
Metadata
Collection Metadata account
Mint
Mint of Collection Metadata
System Program
System program
Rent
Rent info

Revoke an existing Collection Authority

Description

This instruction revokes an existing collection authority, meaning they will no longer be able to update the Collection field of the Metadata account associated with that Mint account.

It does this by deleting the provided Collection Authority Record PDA.

  • Name: RevokeCollectionAuthority
  • Discriminator: 24 (u8)

Accounts

NameTypeDescription
Collection Authority Record
Collection Authority Record PDA
Delegate Authority
Delegated Collection Authority
Revoke Authority
Update Authority, or Delegated Authority, of Collection NFT
Metadata
Metadata account
Mint
Mint of Metadata

Reduce the number of uses

Description

This instruction reduces the number of uses of a Metadata account.

This can either be done by the Update Authority of the Metadata account or by an approved Use Authority.

  • Name: Utilize
  • Discriminator: 19 (u8)

Accounts

NameTypeDescription
Metadata
Metadata account
Token Account
Token Account Of NFT
Mint
Mint of the Metadata
Use Authority
A Use Authority / Can be the current Owner of the NFT
Owner
Owner
Token Program
Token program
Ata Program
Associated Token program
System Program
System program
Rent
Rent info
Use Authority Record
Use Authority Record PDA If present the program Assumes a delegated use authority
Burner
Program As Signer (Burner)

Arguments

ArgumentOffsetSizeDescription
Utilize Args
0~An object containing all the arguments necessary to utilize the NFT
Number Of Uses
08The number of uses to reduce.

Approve a new Use Authority

Description

This instruction allows the provided User account to utilize a Metadata account.

The program keeps track of all the use authorities that have been approved via Use Authority Record PDAs.

  • Name: ApproveUseAuthority
  • Discriminator: 20 (u8)

Accounts

NameTypeDescription
Use Authority Record
Use Authority Record PDA
Owner
Owner
Payer
Payer
User
A Use Authority
Owner Token Account
Owned Token Account Of Mint
Metadata
Metadata account
Mint
Mint of Metadata
Burner
Program As Signer (Burner)
Token Program
Token program
System Program
System program
Rent
Rent info

Arguments

ArgumentOffsetSizeDescription
Approve Use Authority Args
0~An object containing all the arguments necessary to approve a new Use Authority.
Number Of Uses
08The total number of uses allowed for the new authority.

Revoke an existing Use Authority

Description

This instruction revokes an existing use authority, meaning they will no longer be able to reduce the uses of the Metadata account associated with that Mint account.

It does this by deleting the provided Use Authority Record PDA.

  • Name: RevokeUseAuthority
  • Discriminator: 21 (u8)

Accounts

NameTypeDescription
Use Authority Record
Use Authority Record PDA
Owner
Owner
User
A Use Authority
Owner Token Account
Owned Token Account Of Mint
Mint
Mint of Metadata
Metadata
Metadata account
Token Program
Token program
System Program
System program
Rent
Rent info

Freeze the token account as a delegate

Description

This instruction freezes a Token account but only if you are the Delegate Authority of the Token account.

Because Mint Authority and Freeze Authority of NFTs are transferred to the Master Edition / Edition PDA, this instruction is the only way for a delegate to prevent the owner of an NFT to transfer it.

This enables a variety of use-cases such as preventing someone to sell its NFT whilst being listed in an escrowless marketplace.

Here's a small guide on how to freeze a Token account using this instruction.

  • Name: FreezeDelegatedAccount
  • Discriminator: 26 (u8)

Accounts

NameTypeDescription
Delegate
Delegate
Token Account
Token account to freeze
Edition
Edition
Mint
Token mint
Token Program
Token Program

Thaw the token account as a delegate

Description

This instruction reverts the instruction above by unfreezing a Token account, only if you are the Delegate Authority of the Token account.

  • Name: ThawDelegatedAccount
  • Discriminator: 27 (u8)

Accounts

NameTypeDescription
Delegate
Delegate
Token Account
Token account to thaw
Edition
Edition
Mint
Token mint
Token Program
Token Program

Add padding to Metadata account fields

Description

This instruction adds padding to the Name, Symbol and URI strings of the provided Metadata account. As a result, these fields will have a fixed size and will be easier to filter.

Note that, this is automatically done by the Token Metadata program when creating and updating Metadata accounts. This instruction serves as a migration tool for old NFTs that do not have that padding.

  • Name: PuffMetadata
  • Discriminator: 14 (u8)

Accounts

NameTypeDescription
Metadata
Metadata account

Upgrade Master Edition from V1 to V2

Description

This instruction serves as a migration tool that upgrades a Master Edition account of an NFT from V1 to V2.

  • Name: ConvertMasterEditionV1ToV2
  • Discriminator: 12 (u8)

Accounts

NameTypeDescription
Master Edition
Master Record Edition V1 (pda of ['metadata', program id, master metadata mint id, 'edition'])
One Time Auth
One time authorization mint
Printing Mint
Printing mint

Set collection size

Description

This instruction allows the update authority of a collection parent NFT to set the size of the collection once in order to allow existing unsized collections to be updated to track size. Once a collection is sized it can only be verified and unverified by the sized handlers and can't be changed back to unsized.

  • Name: SetCollectionSize
  • Discriminator: 34 (u8)

Accounts

NameTypeDescription
Collection Metadata
Collection Metadata account
Collection Authority
Collection Update authority
Collection Mint
Mint of the Collection
Collection Authority Record
Collection Authority Record PDA

Arguments

ArgumentOffsetSizeDescription
Set Collection Size Args
0~
Size
0~

Set token standard

Description

This instruction allows an update authority to pass in a metadata account with an optional edition account and then it determines what the correct TokenStandard type is and writes it to the metadata. See Token Standard for more information.

  • Name: SetTokenStandard
  • Discriminator: 35 (u8)

Accounts

NameTypeDescription
Metadata
Metadata account
Update Authority
Metadata update authority
Mint
Mint account
Edition
Edition account