ENS API
Ethereum Name Service (ENS) has a friendly overview.
Continue below for the detailed specs on each method and class in the ens module.
ens.ens module
- class ens.ens.ENS(provider: BaseProvider = <object object>, addr: ChecksumAddress = None, middlewares: ~typing.Sequence[~typing.Tuple[Middleware, str]] | None = None)
Quick access to common Ethereum Name Service functions, like getting the address for a name.
Unless otherwise specified, all addresses are assumed to be a str in checksum format, like:
"0x314159265dD8dbb310642f98f50C066173C1259b"
- classmethod from_web3(w3: Web3, addr: ChecksumAddress = None) ENS
Generate an ENS instance from a Web3 instance
- Parameters:
w3 (web3.Web3) – to infer connection, middleware, and codec information
addr (hex-string) – the address of the ENS registry on-chain. If not provided, defaults to the mainnet ENS registry address.
- address(name: str) ChecksumAddress | None
Look up the Ethereum address that name currently points to.
- Parameters:
name (str) – an ENS name to look up
- Raises:
InvalidName – if name has invalid syntax
- setup_address(name: str, address: Address | ChecksumAddress | HexAddress = <object object>, transact: TxParams | None = None) HexBytes | None
Set up the name to point to the supplied address. The sender of the transaction must own the name, or its parent name.
Example: If the caller owns
parentname.eth
with no subdomains and calls this method withsub.parentname.eth
, thensub
will be created as part of this call.- Parameters:
name (str) – ENS name to set up
address (str) – name will point to this address, in checksum format. If
None
, erase the record. If not specified, name will point to the owner’s address.transact (dict) – the transaction configuration, like in
send_transaction()
- Raises:
InvalidName – if
name
has invalid syntaxUnauthorizedError – if
'from'
in transact does not own name
- name(address: ChecksumAddress) str | None
Look up the name that the address points to, using a reverse lookup. Reverse lookup is opt-in for name owners.
- Parameters:
address (hex-string) –
- setup_name(name: str, address: ChecksumAddress | None = None, transact: TxParams | None = None) HexBytes
Set up the address for reverse lookup, aka “caller ID”. After successful setup, the method
name()
will return name when supplied with address.- Parameters:
- Raises:
AddressMismatch – if the name does not already point to the address
InvalidName – if name has invalid syntax
UnauthorizedError – if
'from'
in transact does not own nameUnownedName – if no one owns name
- owner(name: str) ChecksumAddress
Get the owner of a name. Note that this may be different from the deed holder in the ‘.eth’ registrar. Learn more about the difference between deed and name ownership in the ENS Managing Ownership docs
- setup_owner(name: str, new_owner: ChecksumAddress = <object object>, transact: TxParams | None = None) ChecksumAddress | None
Set the owner of the supplied name to new_owner.
For typical scenarios, you’ll never need to call this method directly, simply call
setup_name()
orsetup_address()
. This method does not set up the name to point to an address.If new_owner is not supplied, then this will assume you want the same owner as the parent domain.
If the caller owns
parentname.eth
with no subdomains and calls this method withsub.parentname.eth
, thensub
will be created as part of this call.- Parameters:
name (str) – ENS name to set up
new_owner – account that will own name. If
None
, set owner to empty addr. If not specified, name will point to the parent domain owner’s address.transact (dict) – the transaction configuration, like in
send_transaction()
- Raises:
InvalidName – if name has invalid syntax
UnauthorizedError – if
'from'
in transact does not own name
- Returns:
the new owner’s address
- resolver(name: str) Contract | None
Get the resolver for an ENS name.
- Parameters:
name (str) – The ENS name
- get_text(name: str, key: str) str
Get the value of a text record by key from an ENS name.
- Parameters:
- Returns:
ENS name’s text record value
- Return type:
- Raises:
UnsupportedFunction – If the resolver does not support the “0x59d1d43c” interface id
ResolverNotFound – If no resolver is found for the provided name
- set_text(name: str, key: str, value: str, transact: TxParams = None) HexBytes
Set the value of a text record of an ENS name.
- Parameters:
name (str) – ENS name
key (str) – Name of the attribute to set
value (str) – Value to set the attribute to
transact (dict) – The transaction configuration, like in
send_transaction()
- Returns:
Transaction hash
- Return type:
HexBytes
- Raises:
UnsupportedFunction – If the resolver does not support the “0x59d1d43c” interface id
ResolverNotFound – If no resolver is found for the provided name
ens.async_ens module
- class ens.async_ens.AsyncENS(provider: AsyncBaseProvider = <object object>, addr: ChecksumAddress = None, middlewares: ~typing.Sequence[~typing.Tuple[AsyncMiddleware, str]] | None = None)
Quick access to common Ethereum Name Service functions, like getting the address for a name.
Unless otherwise specified, all addresses are assumed to be a str in checksum format, like:
"0x314159265dD8dbb310642f98f50C066173C1259b"
- classmethod from_web3(w3: AsyncWeb3, addr: ChecksumAddress = None) AsyncENS
Generate an AsyncENS instance with web3
- Parameters:
w3 (web3.Web3) – to infer connection information
addr (hex-string) – the address of the ENS registry on-chain. If not provided, defaults to the mainnet ENS registry address.
- async address(name: str) ChecksumAddress | None
Look up the Ethereum address that name currently points to.
- Parameters:
name (str) – an ENS name to look up
- Raises:
InvalidName – if name has invalid syntax
- async setup_address(name: str, address: Address | ChecksumAddress | HexAddress = <object object>, transact: TxParams | None = None) HexBytes | None
Set up the name to point to the supplied address. The sender of the transaction must own the name, or its parent name.
Example: If the caller owns
parentname.eth
with no subdomains and calls this method withsub.parentname.eth
, thensub
will be created as part of this call.- Parameters:
name (str) – ENS name to set up
address (str) – name will point to this address, in checksum format. If
None
, erase the record. If not specified, name will point to the owner’s address.transact (dict) – the transaction configuration, like in
send_transaction()
- Raises:
InvalidName – if
name
has invalid syntaxUnauthorizedError – if
'from'
in transact does not own name
- async name(address: ChecksumAddress) str | None
Look up the name that the address points to, using a reverse lookup. Reverse lookup is opt-in for name owners.
- Parameters:
address (hex-string) –
- async setup_name(name: str, address: ChecksumAddress | None = None, transact: TxParams | None = None) HexBytes
Set up the address for reverse lookup, aka “caller ID”. After successful setup, the method
name()
will return name when supplied with address.- Parameters:
- Raises:
AddressMismatch – if the name does not already point to the address
InvalidName – if name has invalid syntax
UnauthorizedError – if
'from'
in transact does not own nameUnownedName – if no one owns name
- async owner(name: str) ChecksumAddress
Get the owner of a name. Note that this may be different from the deed holder in the ‘.eth’ registrar. Learn more about the difference between deed and name ownership in the ENS Managing Ownership docs
- async setup_owner(name: str, new_owner: ChecksumAddress = <object object>, transact: TxParams | None = None) ChecksumAddress | None
Set the owner of the supplied name to new_owner.
For typical scenarios, you’ll never need to call this method directly, simply call
setup_name()
orsetup_address()
. This method does not set up the name to point to an address.If new_owner is not supplied, then this will assume you want the same owner as the parent domain.
If the caller owns
parentname.eth
with no subdomains and calls this method withsub.parentname.eth
, thensub
will be created as part of this call.- Parameters:
name (str) – ENS name to set up
new_owner – account that will own name. If
None
, set owner to empty addr. If not specified, name will point to the parent domain owner’s address.transact (dict) – the transaction configuration, like in
send_transaction()
- Raises:
InvalidName – if name has invalid syntax
UnauthorizedError – if
'from'
in transact does not own name
- Returns:
the new owner’s address
- async resolver(name: str) AsyncContract | None
Get the resolver for an ENS name.
- Parameters:
name (str) – The ENS name
- async get_text(name: str, key: str) str
Get the value of a text record by key from an ENS name.
- Parameters:
- Returns:
ENS name’s text record value
- Return type:
- Raises:
UnsupportedFunction – If the resolver does not support the “0x59d1d43c” interface id
ResolverNotFound – If no resolver is found for the provided name
- async set_text(name: str, key: str, value: str, transact: TxParams = None) HexBytes
Set the value of a text record of an ENS name.
- Parameters:
name (str) – ENS name
key (str) – Name of the attribute to set
value (str) – Value to set the attribute to
transact (dict) – The transaction configuration, like in
send_transaction()
- Returns:
Transaction hash
- Return type:
HexBytes
- Raises:
UnsupportedFunction – If the resolver does not support the “0x59d1d43c” interface id
ResolverNotFound – If no resolver is found for the provided name
ens.exceptions module
- exception ens.exceptions.AddressMismatch
Bases:
ENSException
In order to set up reverse resolution correctly, the ENS name should first point to the address. This exception is raised if the name does not currently point to the address.
- exception ens.exceptions.InvalidName
Bases:
IDNAError
,ENSException
This exception is raised if the provided name does not meet the syntax standards specified in EIP 137 name syntax.
For example: names may not start with a dot, or include a space.
- exception ens.exceptions.UnauthorizedError
Bases:
ENSException
Raised if the sending account is not the owner of the name you are trying to modify. Make sure to set
from
in thetransact
keyword argument to the owner of the name.
- exception ens.exceptions.UnownedName
Bases:
ENSException
Raised if you are trying to modify a name that no one owns.
If working on a subdomain, make sure the subdomain gets created first with
setup_address()
.
- exception ens.exceptions.ResolverNotFound
Bases:
ENSException
Raised if no resolver was found for the name you are trying to resolve.
- exception ens.exceptions.UnsupportedFunction
Bases:
ENSException
Raised if a resolver does not support a particular method.
- exception ens.exceptions.BidTooLow
Bases:
ENSException
Raised if you bid less than the minimum amount
- exception ens.exceptions.InvalidBidHash
Bases:
ENSException
Raised if you supply incorrect data to generate the bid hash.
- exception ens.exceptions.InvalidLabel
Bases:
ENSException
Raised if you supply an invalid label
- exception ens.exceptions.OversizeTransaction
Bases:
ENSException
Raised if a transaction you are trying to create would cost so much gas that it could not fit in a block.
For example: when you try to start too many auctions at once.
- exception ens.exceptions.UnderfundedBid
Bases:
ENSException
Raised if you send less wei with your bid than you declared as your intent to bid.
- exception ens.exceptions.ENSValidationError
Bases:
ENSException
,ValidationError
Raised if there is a validation error