HomeForumWebsite
GitHub Icon

ERC 721

Outdated Version

You're viewing an older version (v3.x) The latest documentation is available for the current version. Click here to visit latest version.
AnthropicOpen in Claude

This document is better viewed at https://docs.openzeppelin.com/contracts/api/token/erc721

This set of interfaces, contracts, and utilities are all related to the ERC721 Non-Fungible Token Standard.

For a walk through on how to create an ERC721 token read our ERC721 guide.

The EIP consists of three interfaces, found here as IERC721, IERC721Metadata, and IERC721Enumerable. Only the first one is required in a contract to be ERC721 compliant. However, all three are implemented in ERC721.

Additionally, IERC721Receiver can be used to prevent tokens from becoming forever locked in contracts. Imagine sending an in-game item to an exchange address that can’t send it back!. When using safeTransferFrom, the token contract checks to see that the receiver is an IERC721Receiver, which implies that it knows how to handle ERC721 tokens. If you’re writing a contract that needs to receive ERC721 tokens, you’ll want to include this interface.

Additionally there are multiple custom extensions, including:

  • designation of addresses that can pause token transfers for all users (ERC721Pausable).
  • destruction of own tokens (ERC721Burnable).

This core set of contracts is designed to be unopinionated, allowing developers to access the internal functions in ERC721 (such as [_mint](#_mint(address-to,-uint256-tokenid) *internal*)) and expose them as external functions in the way they prefer. On the other hand, ERC721 Presets (such as ERC721PresetMinterPauserAutoId) are designed using opinionated patterns to provide developers with ready to use, deployable contracts.

Core

IERC721

Required interface of an ERC721 compliant contract.

Functions

IERC165

Events

balanceOf(address owner) → uint256 balance *external*

Returns the number of tokens in ``owner`’s account.

ownerOf(uint256 tokenId) → address owner *external*

Returns the owner of the tokenId token.

Requirements:

  • tokenId must exist.

safeTransferFrom(address from, address to, uint256 tokenId) *external*

Safely transfers tokenId token from from to to, checking first that contract recipients are aware of the ERC721 protocol to prevent tokens from being forever locked.

Requirements:

  • from cannot be the zero address.
  • to cannot be the zero address.
  • tokenId token must exist and be owned by from.
  • If the caller is not from, it must be have been allowed to move this token by either approve or setApprovalForAll.
  • If to refers to a smart contract, it must implement IERC721Receiver-onERC721Received, which is called upon a safe transfer.

Emits a Transfer event.

transferFrom(address from, address to, uint256 tokenId) *external*

Transfers tokenId token from from to to.

Usage of this method is discouraged, use safeTransferFrom whenever possible.

Requirements:

  • from cannot be the zero address.
  • to cannot be the zero address.
  • tokenId token must be owned by from.
  • If the caller is not from, it must be approved to move this token by either approve or setApprovalForAll.

Emits a Transfer event.

approve(address to, uint256 tokenId) *external*

Gives permission to to to transfer tokenId token to another account. The approval is cleared when the token is transferred.

Only a single account can be approved at a time, so approving the zero address clears previous approvals.

Requirements:

  • The caller must own the token or be an approved operator.
  • tokenId must exist.

Emits an Approval event.

getApproved(uint256 tokenId) → address operator *external*

Returns the account approved for tokenId token.

Requirements:

  • tokenId must exist.

setApprovalForAll(address operator, bool _approved) *external*

Approve or remove operator as an operator for the caller. Operators can call transferFrom or safeTransferFrom for any token owned by the caller.

Requirements:

  • The operator cannot be the caller.

Emits an ApprovalForAll event.

isApprovedForAll(address owner, address operator) → bool *external*

Returns if the operator is allowed to manage all of the assets of owner.

See setApprovalForAll

safeTransferFrom(address from, address to, uint256 tokenId, bytes data) *external*

Safely transfers tokenId token from from to to.

Requirements:

  • from cannot be the zero address.
  • to cannot be the zero address.
  • tokenId token must exist and be owned by from.
  • If the caller is not from, it must be approved to move this token by either approve or setApprovalForAll.
  • If to refers to a smart contract, it must implement IERC721Receiver-onERC721Received, which is called upon a safe transfer.

Emits a Transfer event.

Transfer(address from, address to, uint256 tokenId) *event*

Emitted when tokenId token is transferred from from to to.

Approval(address owner, address approved, uint256 tokenId) *event*

Emitted when owner enables approved to manage the tokenId token.

ApprovalForAll(address owner, address operator, bool approved) *event*

Emitted when owner enables or disables (approved) operator to manage all of its assets.

IERC721Metadata

See https://eips.ethereum.org/EIPS/eip-721

Functions

IERC721

IERC165

Events

IERC721

name() → string *external*

Returns the token collection name.

symbol() → string *external*

Returns the token collection symbol.

tokenURI(uint256 tokenId) → string *external*

Returns the Uniform Resource Identifier (URI) for tokenId token.

IERC721Enumerable

See https://eips.ethereum.org/EIPS/eip-721

Functions

IERC721

IERC165

Events

IERC721

totalSupply() → uint256 *external*

Returns the total amount of tokens stored by the contract.

tokenOfOwnerByIndex(address owner, uint256 index) → uint256 tokenId *external*

Returns a token ID owned by owner at a given index of its token list. Use along with balanceOf to enumerate all of ``owner`’s tokens.

tokenByIndex(uint256 index) → uint256 *external*

Returns a token ID at a given index of all the tokens stored by the contract. Use along with totalSupply to enumerate all tokens.

ERC721

see https://eips.ethereum.org/EIPS/eip-721

Functions

ERC165

Events

IERC721

constructor(string name_, string symbol_) *public*

Initializes the contract by setting a name and a symbol to the token collection.

balanceOf(address owner) → uint256 *public*

See IERC721-balanceOf.

ownerOf(uint256 tokenId) → address *public*

See IERC721-ownerOf.

name() → string *public*

See IERC721Metadata-name.

symbol() → string *public*

See IERC721Metadata-symbol.

tokenURI(uint256 tokenId) → string *public*

See IERC721Metadata-tokenURI.

baseURI() → string *public*

Returns the base URI set via _setBaseURI. This will be automatically added as a prefix in tokenURI to each token’s URI, or to the token ID if no specific URI is set for that token ID.

tokenOfOwnerByIndex(address owner, uint256 index) → uint256 *public*

See IERC721Enumerable-tokenOfOwnerByIndex.

totalSupply() → uint256 *public*

See IERC721Enumerable-totalSupply.

tokenByIndex(uint256 index) → uint256 *public*

See IERC721Enumerable-tokenByIndex.

approve(address to, uint256 tokenId) *public*

See IERC721-approve.

getApproved(uint256 tokenId) → address *public*

See IERC721-getApproved.

setApprovalForAll(address operator, bool approved) *public*

See IERC721-setApprovalForAll.

isApprovedForAll(address owner, address operator) → bool *public*

See IERC721-isApprovedForAll.

transferFrom(address from, address to, uint256 tokenId) *public*

See IERC721-transferFrom.

safeTransferFrom(address from, address to, uint256 tokenId) *public*

See IERC721-safeTransferFrom.

safeTransferFrom(address from, address to, uint256 tokenId, bytes _data) *public*

See IERC721-safeTransferFrom.

_safeTransfer(address from, address to, uint256 tokenId, bytes _data) *internal*

Safely transfers tokenId token from from to to, checking first that contract recipients are aware of the ERC721 protocol to prevent tokens from being forever locked.

_data is additional data, it has no specified format and it is sent in call to to.

This internal function is equivalent to safeTransferFrom, and can be used to e.g. implement alternative mechanisms to perform token transfer, such as signature-based.

Requirements:

  • from cannot be the zero address.
  • to cannot be the zero address.
  • tokenId token must exist and be owned by from.
  • If to refers to a smart contract, it must implement IERC721Receiver-onERC721Received, which is called upon a safe transfer.

Emits a Transfer event.

_exists(uint256 tokenId) → bool *internal*

Returns whether tokenId exists.

Tokens can be managed by their owner or approved accounts via approve or setApprovalForAll.

Tokens start existing when they are minted (_mint), and stop existing when they are burned (_burn).

_isApprovedOrOwner(address spender, uint256 tokenId) → bool *internal*

Returns whether spender is allowed to manage tokenId.

Requirements:

  • tokenId must exist.

_safeMint(address to, uint256 tokenId) *internal*

Safely mints tokenId and transfers it to to.

Requirements: d*

  • tokenId must not exist.
  • If to refers to a smart contract, it must implement IERC721Receiver-onERC721Received, which is called upon a safe transfer.

Emits a Transfer event.

_safeMint(address to, uint256 tokenId, bytes _data) *internal*

Same as _safeMint, with an additional data parameter which is forwarded in IERC721Receiver-onERC721Received to contract recipients.

_mint(address to, uint256 tokenId) *internal*

Mints tokenId and transfers it to to.

Usage of this method is discouraged, use _safeMint whenever possible

Requirements:

  • tokenId must not exist.
  • to cannot be the zero address.

Emits a Transfer event.

_burn(uint256 tokenId) *internal*

Destroys tokenId. The approval is cleared when the token is burned.

Requirements:

  • tokenId must exist.

Emits a Transfer event.

_transfer(address from, address to, uint256 tokenId) *internal*

Transfers tokenId from from to to. As opposed to transferFrom, this imposes no restrictions on msg.sender.

Requirements:

  • to cannot be the zero address.
  • tokenId token must be owned by from.

Emits a Transfer event.

_setTokenURI(uint256 tokenId, string _tokenURI) *internal*

Sets _tokenURI as the tokenURI of tokenId.

Requirements:

  • tokenId must exist.

_setBaseURI(string baseURI_) *internal*

Internal function to set the base URI for all token IDs. It is automatically added as a prefix to the value returned in tokenURI, or to the token ID if tokenURI is empty.

_approve(address to, uint256 tokenId) *internal*

Approve to to operate on tokenId

Emits an Approval event.

`_beforeTokenTransfer(address from, address to, uint256 tokenId) internal

Hook that is called before any token transfer. This includes minting and burning.

Calling conditions:

*Whenfromandto are both non-zero, ``from’s tokenId will be transferred to to.

  • When from is zero, tokenId will be minted for to.
  • When to is zero, ``from’s tokenId` will be burned.
  • from cannot be the zero address.
  • to cannot be the zero address.

To learn more about hooks, head to Using Hooks.

IERC721Receiver

Interface for any contract that wants to support safeTransfers from ERC721 asset contracts.

Functions

onERC721Received(address operator, address from, uint256 tokenId, bytes data) → bytes4 *external*

Whenever an IERC721 tokenId token is transferred to this contract via IERC721-safeTransferFrom by operator from from, this function is called.

It must return its Solidity selector to confirm the token transfer. If any other value is returned or the interface is not implemented by the recipient, the transfer will be reverted.

The selector can be obtained in Solidity with IERC721.onERC721Received.selector.

Extensions

ERC721Pausable

ERC721 token with pausable token transfers, minting and burning.

Useful for scenarios such as preventing trades until the end of an evaluation period, or having an emergency switch for freezing all token transfers in the event of a large bug.

Functions

Pausable

ERC721

ERC165

Events

Pausable

IERC721

`_beforeTokenTransfer(address from, address to, uint256 tokenId) internal

See ERC721-_beforeTokenTransfer.

Requirements:

*` the contract must not be paused.

ERC721Burnable

ERC721 Token that can be irreversibly burned (destroyed).

Functions

ERC721

ERC165

Events

IERC721

burn(uint256 tokenId) *public*

Burns tokenId. See ERC721-_burn.

Requirements:

  • The caller must own tokenId or be an approved operator.

Convenience

ERC721Holder

Implementation of the IERC721Receiver interface.

Accepts all token transfers. Make sure the contract is able to use its token with IERC721-safeTransferFrom, IERC721-approve or IERC721-setApprovalForAll.

Functions

onERC721Received(address, address, uint256, bytes) → bytes4 *public*

See IERC721Receiver-onERC721Received.

Always returns IERC721Receiver.onERC721Received.selector.

On this page

CoreIERC721balanceOf(address owner) → uint256 balance *external*ownerOf(uint256 tokenId) → address owner *external*safeTransferFrom(address from, address to, uint256 tokenId) *external*transferFrom(address from, address to, uint256 tokenId) *external*approve(address to, uint256 tokenId) *external*getApproved(uint256 tokenId) → address operator *external*setApprovalForAll(address operator, bool _approved) *external*isApprovedForAll(address owner, address operator) → bool *external*safeTransferFrom(address from, address to, uint256 tokenId, bytes data) *external*Transfer(address from, address to, uint256 tokenId) *event*Approval(address owner, address approved, uint256 tokenId) *event*ApprovalForAll(address owner, address operator, bool approved) *event*IERC721Metadataname() → string *external*symbol() → string *external*tokenURI(uint256 tokenId) → string *external*IERC721EnumerabletotalSupply() → uint256 *external*tokenOfOwnerByIndex(address owner, uint256 index) → uint256 tokenId *external*tokenByIndex(uint256 index) → uint256 *external*ERC721constructor(string name_, string symbol_) *public*balanceOf(address owner) → uint256 *public*ownerOf(uint256 tokenId) → address *public*name() → string *public*symbol() → string *public*tokenURI(uint256 tokenId) → string *public*baseURI() → string *public*tokenOfOwnerByIndex(address owner, uint256 index) → uint256 *public*totalSupply() → uint256 *public*tokenByIndex(uint256 index) → uint256 *public*approve(address to, uint256 tokenId) *public*getApproved(uint256 tokenId) → address *public*setApprovalForAll(address operator, bool approved) *public*isApprovedForAll(address owner, address operator) → bool *public*transferFrom(address from, address to, uint256 tokenId) *public*safeTransferFrom(address from, address to, uint256 tokenId) *public*safeTransferFrom(address from, address to, uint256 tokenId, bytes _data) *public*_safeTransfer(address from, address to, uint256 tokenId, bytes _data) *internal*_exists(uint256 tokenId) → bool *internal*_isApprovedOrOwner(address spender, uint256 tokenId) → bool *internal*_safeMint(address to, uint256 tokenId) *internal*_safeMint(address to, uint256 tokenId, bytes _data) *internal*_mint(address to, uint256 tokenId) *internal*_burn(uint256 tokenId) *internal*_transfer(address from, address to, uint256 tokenId) *internal*_setTokenURI(uint256 tokenId, string _tokenURI) *internal*_setBaseURI(string baseURI_) *internal*_approve(address to, uint256 tokenId) *internal*`_beforeTokenTransfer(address from, address to, uint256 tokenId) internalIERC721ReceiveronERC721Received(address operator, address from, uint256 tokenId, bytes data) → bytes4 *external*ExtensionsERC721Pausable`_beforeTokenTransfer(address from, address to, uint256 tokenId) internalERC721Burnableburn(uint256 tokenId) *public*ConvenienceERC721HolderonERC721Received(address, address, uint256, bytes) → bytes4 *public*