Onchain.ERC721 (onchain v0.5.4)

Copy Markdown View Source

ERC-721 (NFT) read operations.

Thin wrappers around Onchain.Contract.call/5 for standard ERC-721 queries. Returns checksummed hex addresses for owner_of/3 and get_approved/3.

Error Format

Errors pass through from underlying modules:

SourceError Shape
Onchain.Address.validate/1{:error, {:invalid_address, input}}
Onchain.Contract.call/5{:error, {:encode_error, ...}}, {:error, {:rpc_error, ...}}, {:error, {:decode_error, ...}}

Functions

FunctionPurpose
balance_of/3Number of NFTs owned by an address
balance_of!/3Same, raises on error
owner_of/3Owner address of a specific token ID
owner_of!/3Same, raises on error
token_uri/3Metadata URI for a token ID
token_uri!/3Same, raises on error
name/2Collection name
name!/2Same, raises on error
symbol/2Collection symbol
symbol!/2Same, raises on error
get_approved/3Approved operator for a token ID
get_approved!/3Same, raises on error
approved_for_all?/4Whether an operator is approved for all tokens
approved_for_all!/4Same, raises on error

API Functions

FunctionArityDescriptionParam Kinds
approved_for_all!4Check if an operator is approved for all tokens. Raises on error.contract: value, owner: value, operator: value, opts: value
approved_for_all?4Check if an operator is approved for all tokens of an owner.contract: value, owner: value, operator: value, opts: value
get_approved!3Get the approved address for a specific token ID. Raises on error.contract: value, token_id: value, opts: value
get_approved3Get the approved address for a specific token ID.contract: value, token_id: value, opts: value
symbol!2Get the collection symbol. Raises on error.contract: value, opts: value
symbol2Get the collection symbol.contract: value, opts: value
name!2Get the collection name. Raises on error.contract: value, opts: value
name2Get the collection name.contract: value, opts: value
token_uri!3Get the metadata URI for a token ID. Raises on error.contract: value, token_id: value, opts: value
token_uri3Get the metadata URI for a token ID.contract: value, token_id: value, opts: value
owner_of!3Get the owner of a specific token ID. Raises on error.contract: value, token_id: value, opts: value
owner_of3Get the owner of a specific token ID.contract: value, token_id: value, opts: value
balance_of!3Get the number of NFTs owned by an address. Raises on error.contract: value, owner: value, opts: value
balance_of3Get the number of NFTs owned by an address.contract: value, owner: value, opts: value

Summary

Functions

approved_for_all!(contract, owner, operator, opts \\ [])

Check if an operator is approved for all tokens. Raises on error.

approved_for_all?(contract, owner, operator, opts \\ [])

Check if an operator is approved for all tokens of an owner.

balance_of(contract, owner, opts \\ [])

Get the number of NFTs owned by an address.

balance_of!(contract, owner, opts \\ [])

Get the number of NFTs owned by an address. Raises on error.

get_approved(contract, token_id, opts \\ [])

Get the approved address for a specific token ID.

get_approved!(contract, token_id, opts \\ [])

Get the approved address for a specific token ID. Raises on error.

name(contract, opts \\ [])

Get the collection name.

name!(contract, opts \\ [])

Get the collection name. Raises on error.

owner_of(contract, token_id, opts \\ [])

Get the owner of a specific token ID.

owner_of!(contract, token_id, opts \\ [])

Get the owner of a specific token ID. Raises on error.

symbol(contract, opts \\ [])

Get the collection symbol.

symbol!(contract, opts \\ [])

Get the collection symbol. Raises on error.

token_uri(contract, token_id, opts \\ [])

Get the metadata URI for a token ID.

token_uri!(contract, token_id, opts \\ [])

Get the metadata URI for a token ID. Raises on error.

Functions

approved_for_all!(contract, owner, operator, opts \\ [])

@spec approved_for_all!(
  String.t() | binary(),
  String.t() | binary(),
  String.t() | binary(),
  keyword()
) :: boolean()

Check if an operator is approved for all tokens. Raises on error.

Parameters

  • contract - ERC-721 contract address (value)
  • owner - Token owner address (value)
  • operator - Operator address to check (value)
  • opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

Whether the operator is approved for all tokens (boolean)

# descripex:contract
%{
  params: %{
    owner: %{description: "Token owner address", kind: :value},
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    operator: %{description: "Operator address to check", kind: :value},
    contract: %{description: "ERC-721 contract address", kind: :value}
  },
  returns: %{
    type: :boolean,
    description: "Whether the operator is approved for all tokens"
  }
}

approved_for_all?(contract, owner, operator, opts \\ [])

@spec approved_for_all?(
  String.t() | binary(),
  String.t() | binary(),
  String.t() | binary(),
  keyword()
) :: {:ok, boolean()} | {:error, term()}

Check if an operator is approved for all tokens of an owner.

Parameters

  • contract - ERC-721 contract address (value)
  • owner - Token owner address (value)
  • operator - Operator address to check (value)
  • opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

Whether the operator is approved for all tokens ({:ok, boolean()} | {:error, term()})

# descripex:contract
%{
  params: %{
    owner: %{description: "Token owner address", kind: :value},
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    operator: %{description: "Operator address to check", kind: :value},
    contract: %{description: "ERC-721 contract address", kind: :value}
  },
  returns: %{
    type: "{:ok, boolean()} | {:error, term()}",
    description: "Whether the operator is approved for all tokens",
    example: "false"
  }
}

balance_of(contract, owner, opts \\ [])

@spec balance_of(String.t() | binary(), String.t() | binary(), keyword()) ::
  {:ok, non_neg_integer()} | {:error, term()}

Get the number of NFTs owned by an address.

Parameters

  • contract - ERC-721 contract address (value)
  • owner - Address to check balance for (value)
  • opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

Number of NFTs owned ({:ok, non_neg_integer()} | {:error, term()})

# descripex:contract
%{
  params: %{
    owner: %{description: "Address to check balance for", kind: :value},
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    contract: %{description: "ERC-721 contract address", kind: :value}
  },
  returns: %{
    type: "{:ok, non_neg_integer()} | {:error, term()}",
    description: "Number of NFTs owned",
    example: "3"
  }
}

balance_of!(contract, owner, opts \\ [])

@spec balance_of!(String.t() | binary(), String.t() | binary(), keyword()) ::
  non_neg_integer()

Get the number of NFTs owned by an address. Raises on error.

Parameters

  • contract - ERC-721 contract address (value)
  • owner - Address to check balance for (value)
  • opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

Number of NFTs owned (non_neg_integer)

# descripex:contract
%{
  params: %{
    owner: %{description: "Address to check balance for", kind: :value},
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    contract: %{description: "ERC-721 contract address", kind: :value}
  },
  returns: %{type: :non_neg_integer, description: "Number of NFTs owned"}
}

get_approved(contract, token_id, opts \\ [])

@spec get_approved(String.t() | binary(), non_neg_integer(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

Get the approved address for a specific token ID.

Parameters

  • contract - ERC-721 contract address (value)
  • token_id - Token ID (non-negative integer) (value)
  • opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

Approved address as EIP-55 checksummed hex string (zero address if none) ({:ok, String.t()} | {:error, term()})

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    contract: %{description: "ERC-721 contract address", kind: :value},
    token_id: %{description: "Token ID (non-negative integer)", kind: :value}
  },
  returns: %{
    type: "{:ok, String.t()} | {:error, term()}",
    description: "Approved address as EIP-55 checksummed hex string (zero address if none)",
    example: "\"0x0000000000000000000000000000000000000000\""
  }
}

get_approved!(contract, token_id, opts \\ [])

@spec get_approved!(String.t() | binary(), non_neg_integer(), keyword()) :: String.t()

Get the approved address for a specific token ID. Raises on error.

Parameters

  • contract - ERC-721 contract address (value)
  • token_id - Token ID (non-negative integer) (value)
  • opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

Approved address as EIP-55 checksummed hex string (string)

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    contract: %{description: "ERC-721 contract address", kind: :value},
    token_id: %{description: "Token ID (non-negative integer)", kind: :value}
  },
  returns: %{
    type: :string,
    description: "Approved address as EIP-55 checksummed hex string"
  }
}

name(contract, opts \\ [])

@spec name(
  String.t() | binary(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Get the collection name.

Parameters

  • contract - ERC-721 contract address (value)
  • opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

Collection name ({:ok, String.t()} | {:error, term()})

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    contract: %{description: "ERC-721 contract address", kind: :value}
  },
  returns: %{
    type: "{:ok, String.t()} | {:error, term()}",
    description: "Collection name",
    example: "\"BoredApeYachtClub\""
  }
}

name!(contract, opts \\ [])

@spec name!(
  String.t() | binary(),
  keyword()
) :: String.t()

Get the collection name. Raises on error.

Parameters

  • contract - ERC-721 contract address (value)
  • opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

Collection name (string)

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    contract: %{description: "ERC-721 contract address", kind: :value}
  },
  returns: %{type: :string, description: "Collection name"}
}

owner_of(contract, token_id, opts \\ [])

@spec owner_of(String.t() | binary(), non_neg_integer(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

Get the owner of a specific token ID.

Parameters

  • contract - ERC-721 contract address (value)
  • token_id - Token ID (non-negative integer) (value)
  • opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

Owner address as EIP-55 checksummed hex string ({:ok, String.t()} | {:error, term()})

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    contract: %{description: "ERC-721 contract address", kind: :value},
    token_id: %{description: "Token ID (non-negative integer)", kind: :value}
  },
  returns: %{
    type: "{:ok, String.t()} | {:error, term()}",
    description: "Owner address as EIP-55 checksummed hex string",
    example: "\"0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed\""
  }
}

owner_of!(contract, token_id, opts \\ [])

@spec owner_of!(String.t() | binary(), non_neg_integer(), keyword()) :: String.t()

Get the owner of a specific token ID. Raises on error.

Parameters

  • contract - ERC-721 contract address (value)
  • token_id - Token ID (non-negative integer) (value)
  • opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

Owner address as EIP-55 checksummed hex string (string)

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    contract: %{description: "ERC-721 contract address", kind: :value},
    token_id: %{description: "Token ID (non-negative integer)", kind: :value}
  },
  returns: %{
    type: :string,
    description: "Owner address as EIP-55 checksummed hex string"
  }
}

symbol(contract, opts \\ [])

@spec symbol(
  String.t() | binary(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Get the collection symbol.

Parameters

  • contract - ERC-721 contract address (value)
  • opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

Collection symbol ({:ok, String.t()} | {:error, term()})

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    contract: %{description: "ERC-721 contract address", kind: :value}
  },
  returns: %{
    type: "{:ok, String.t()} | {:error, term()}",
    description: "Collection symbol",
    example: "\"BAYC\""
  }
}

symbol!(contract, opts \\ [])

@spec symbol!(
  String.t() | binary(),
  keyword()
) :: String.t()

Get the collection symbol. Raises on error.

Parameters

  • contract - ERC-721 contract address (value)
  • opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

Collection symbol (string)

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    contract: %{description: "ERC-721 contract address", kind: :value}
  },
  returns: %{type: :string, description: "Collection symbol"}
}

token_uri(contract, token_id, opts \\ [])

@spec token_uri(String.t() | binary(), non_neg_integer(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

Get the metadata URI for a token ID.

Parameters

  • contract - ERC-721 contract address (value)
  • token_id - Token ID (non-negative integer) (value)
  • opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

Token metadata URI ({:ok, String.t()} | {:error, term()})

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    contract: %{description: "ERC-721 contract address", kind: :value},
    token_id: %{description: "Token ID (non-negative integer)", kind: :value}
  },
  returns: %{
    type: "{:ok, String.t()} | {:error, term()}",
    description: "Token metadata URI",
    example: "\"ipfs://QmeSjSinHpPnmXmspMjwiXyN6zS4E9zccariGR3jxcaWtq/1\""
  }
}

token_uri!(contract, token_id, opts \\ [])

@spec token_uri!(String.t() | binary(), non_neg_integer(), keyword()) :: String.t()

Get the metadata URI for a token ID. Raises on error.

Parameters

  • contract - ERC-721 contract address (value)
  • token_id - Token ID (non-negative integer) (value)
  • opts - Options: :rpc_url, :timeout, :block (default: [], value)

Returns

Token metadata URI (string)

# descripex:contract
%{
  params: %{
    opts: %{
      default: [],
      description: "Options: :rpc_url, :timeout, :block",
      kind: :value
    },
    contract: %{description: "ERC-721 contract address", kind: :value},
    token_id: %{description: "Token ID (non-negative integer)", kind: :value}
  },
  returns: %{type: :string, description: "Token metadata URI"}
}