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.Optional[~typing.Sequence[~typing.Tuple[Middleware, str]]] = 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 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.

address(name: str) → Optional[ChecksumAddress]

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: ~typing.Union[Address, ChecksumAddress, HexAddress] = <object object>, transact: ~typing.Optional[TxParams] = None) → Optional[HexBytes]

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 with sub.parentname.eth, then sub 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
name(address: ChecksumAddress) → Optional[str]

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: Optional[ChecksumAddress] = None, transact: Optional[TxParams] = 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

  • name (str) – ENS name that address will point to

  • address (str) – to set up, in checksum format

  • transact (dict) – the transaction configuration, like in send_transaction()

Raises
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

Parameters

name (str) – ENS name to look up

Returns

owner address

Return type

str

setup_owner(name: str, new_owner: ChecksumAddress = <object object>, transact: ~typing.Optional[TxParams] = None) → Optional[ChecksumAddress]

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() or setup_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 with sub.parentname.eth, then sub 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
Returns

the new owner’s address

resolver(name: str) → Optional[Contract]

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

  • name (str) – ENS name to look up

  • key (str) – ENS name’s text record key

Returns

ENS name’s text record value

Return type

str

Raises
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

ens.async_ens module

class ens.async_ens.AsyncENS(provider: AsyncBaseProvider = <object object>, addr: ChecksumAddress = None, middlewares: ~typing.Optional[~typing.Sequence[~typing.Tuple[Middleware, str]]] = 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) → 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) → Optional[ChecksumAddress]

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: ~typing.Union[Address, ChecksumAddress, HexAddress] = <object object>, transact: ~typing.Optional[TxParams] = None) → Optional[HexBytes]

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 with sub.parentname.eth, then sub 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
async name(address: ChecksumAddress) → Optional[str]

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: Optional[ChecksumAddress] = None, transact: Optional[TxParams] = 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

  • name (str) – ENS name that address will point to

  • address (str) – to set up, in checksum format

  • transact (dict) – the transaction configuration, like in send_transaction()

Raises
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

Parameters

name (str) – ENS name to look up

Returns

owner address

Return type

str

async setup_owner(name: str, new_owner: ChecksumAddress = <object object>, transact: ~typing.Optional[TxParams] = None) → Optional[ChecksumAddress]

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() or setup_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 with sub.parentname.eth, then sub 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
Returns

the new owner’s address

async resolver(name: str) → Optional[AsyncContract]

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

  • name (str) – ENS name to look up

  • key (str) – ENS name’s text record key

Returns

ENS name’s text record value

Return type

str

Raises
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

ens.exceptions module

exception ens.exceptions.AddressMismatch

Bases: ValueError

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

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: Exception

Raised if the sending account is not the owner of the name you are trying to modify. Make sure to set from in the transact keyword argument to the owner of the name.

exception ens.exceptions.UnownedName

Bases: Exception

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: Exception

Raised if no resolver was found for the name you are trying to resolve.

exception ens.exceptions.UnsupportedFunction

Bases: Exception

Raised if a resolver does not support a particular method.

exception ens.exceptions.BidTooLow

Bases: ValueError

Raised if you bid less than the minimum amount

exception ens.exceptions.InvalidBidHash

Bases: ValueError

Raised if you supply incorrect data to generate the bid hash.

exception ens.exceptions.InvalidLabel

Bases: ValueError

Raised if you supply an invalid label

exception ens.exceptions.OversizeTransaction

Bases: ValueError

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: ValueError

Raised if you send less wei with your bid than you declared as your intent to bid.