Get Started: Freename Documentation

Get started with Freename documentation

freename documentation

Freename Service (FNS) Docs

Freename is a Web3 domain service that allows users to mint, buy, own, and utilize Web3 top-level domains as well as earn royalties from them.

Freename’s Web3 domains are represented as NFTs compliant with the ERC-721 standard and can thus seamlessly integrate with existing apps and marketplaces and can be relied upon as a building block to build on top of.

This documentation provides a reference for the set of contracts that together make up the Freename Service (FNS).

Supported Blockchains

Freename currently supports the following blockchains:

  • Aurora
  • Binance Smart Chain
  • Cronos
  • Polygon

All contracts that will be described in the following section have been deployed on each of the blockchains.

Freename Smart Contracts

The Freename Service (FNS) currently consists of 3 different smart contracts:

  1. The FNS Registry contract, which is the heart of the Freename domain management and is the main constituent of the Freename Service (FNS)
  2. The ProxyAdmin contract, which gives necessary admin rights to the Freename team to allow for upgradeability
  3. The MintingManager contract, which enables the Freename team to mint Top Level and Second Level Domains

The following section will give an overview of the functionality of each contract. Also, the addresses of each contract on each chain can be found here.

FNSRegistry Contract

The FNSRegistry contract acts as the registry that maintains records of all Freename domains. It is the most essential smart contract of FNS.

Interaction with these contracts allows users to manage their domains and perform actions like setting records, delegating management and more. It implements the OpenZeppelin ERC-721 Enumerable Metadata token standard and thus stores a list of all domains as NFTs. The Metadata extension allows linking to associated metadata that is individual for each domain, like crypto addresses, IPFS hashes, avatars and more (see section records management for further information).

Information stored in the Registry

In total, following information is stored in the FNSRegistry contract:

  • The registered domains (stored as namehashes)
  • The owner addresses of domains
  • The approved address of domains
  • The operator/manager addresses of domains
  • The records stored in key-value format that are associated with an address.
  • The whitelisted minters

The storing of the registered domain names in the registry is done via a process called Namehashing. Namehashing works by hashing the domain (for example example.domain) and using the hash as ERC-721 tokenID. This standardized format allows for the storage of arbitrary domains of any length.

The usage of the ERC-721 Enumerable standard allows for simple indexing and querying of the stored domains and thus enables developers to easily build on top of the Freename system.

Permissionlessness & Rights

The FNSRegistry contract has no administrators and is fully governed by its code. This means that no interference in the domain ownership and management for any owned domain by any third party is possible in the FNS system.

The Freename team operates addresses that are specified as “whitelisted minters”. This grants the Freename team the right to mint top level domains (like .metaverse) and second level domains (like my.metaverse).

Ownership of a name grants an address the right to

  • transfer ownership
  • set domain records
  • set an approved address as well as manager/operator addresses (see section domain management for further information)

Contract addresses

The FNSRegistry contact has the following addresses on the blockchain supported by FNS:

ProxyAdmin Contract

The ProxyAdmin contract gives the Freename team the option to upgrade the FNSRegistry contract. For more information, please consult the OpenZeppelin documentation.

Contract addresses

The ProxyAdmin contact has the following addresses on the blockchain supported by FNS:

MintingManager Contract

The Freename team is supposed to have the right to mint Top Level Domains and Second Level Domains. At the same time, it should be avoided that any party has total admin rights over the registry.

To achieve this, MintingManager is used as a controller contract that gives the Freename team superuser powers within a limited scope. MintingManager therefore provides an interface that allows the Freename team to mint TLDs and SLDs and forwards all calls to the FNSRegistry contract.

Contract addresses

The MintingManager contact has the following addresses on the blockchain supported by FNS:

Domain Ownership and Management

Domain Ownership

Like most other ERC-721-compliant NFTs, a freename top or second level domain can be owned by both external end user addresses (EOAs) as well as internal addresses (smart contracts. The domain management via smart contract opens up many interesting new ways to structure ownership. A simple example includes domains that are governed by a multi-signaturemulti-sigature wallet, but also many more complex setups are within the realm of possibilities.

Domain Management

Freename allows members to delegate transaction execution to accounts that aren’t domain owners. This is implemented via supporting for EIP-2771 — Secure Protocol for Native Meta Transactions in the FNSRegistry contract.

One prominent use-case of meta transactions is that they allow delegation of (gas-using) blockchain calls to other accounts. Like this, domain owners can manage their domains from other accounts they own or even have some third party pay for the transaction fees associated with domain management.

Delegation to Freename

The delegation feature of FNS Domains is used by the Freename team to operate our managed domain platform. An internal transaction processor queues transactions and then submits them to the blockchain on behalf of our users. This way, domain owners can mint and manage their domains on without having to worry about blockchain fees.

In the case of mintings of domains no signature from the domain owner is required, since the Freename team is a whitelisted minter in the FNSRegistry and therefore allowed to mint TLDs and second level domains.

Freename uses this delegation feature to operate an internal transaction processor. Our transaction processor makes it possible for members to mint and manage their domains without having to worry about their wallet’s balance. Under the hood, the transaction processor is a queue-based job processor that sends transactions from Freename-owned accounts.

Managing domains, in contrast, can only be performed with a domain owner’s permission, since the FNS system is fully trustless. Therefore each “management act”, like e.g. setting a domain record, requires a signature from the owner’s wallet in order to be performed. (Please note: This feature is part of the roadmap, but not yet live on

Records management

Similar to the internet’s traditional DNS system Freename NFT domains also enable users to set records. Records allow owners of NFT domains to link arbitrary information to their domain via a key-value format. This means that each key corresponds to a certain value (examples include crypto addresses, websites, social media accounts and many others) that can be looked up when being given the key as an input.

By this, users can customize their resolving preferences and provide different resolutions for different use-cases and services.

Users can set their own records using the Freename Platform in the domain management. It provides a set of possible records that users can set. Developers can configure their own records or resolve specific records using the SDK or directly interacting with the Smart Contract.

While Freename offers developers the liberty to set records in the way they wish and that’s useful to their application, some specific standards to follow on how to set the proper record key name are being provided. This helps keeping a clean set of records and brings order to the keyspace of every NFT domain.

Key & value structure

In the FNS domain records key-value store, each key follows the following structure:


Example A record key: record.A.0

Example BTC address key (index 0): token.BTC.0

Example BTC address key (index 1): token.BTC.1

The format of values depends on the type of record being set and therefore could follow various standards (e.g. crypto addresses, URIs, etc.).

Standard key record structure

The list below shows all standard keys that FNS supports, including desired value formats:

Custom key record structure

FNS allows setting of non-standard custom keys with arbitrary value formats. This allows developers to build on top of FNS and safe arbitrary data that can be used for their custom dApp integration. The table below lists some examples:

Fill the info to receive the PDF guide

Stay up to date!

How does it work?

Accordingly to the day when you will finalise your purchase, you have the right to receive from 1 to 3 NFT Domains for FREE!

Once you have completed your order, within 48h you will automatically receive on platform, in your personal area “portfolio” the randomly assigned NFT Domain/s.

You can chose on which blockchain you want to mint on and minting fee is covered by Freename!


Once you have added your favorite items to the cart, you proceed to “checkout” and add your coupon to the “coupon box”.

Said coupon will instantly do its magic and your due total will drop!


How does it work?

Once you have completed your order, you will automatically receive on platform, in your personal area “portfolio” the randomly assigned NFT Domain value $50 or if you’re lucky a randomly assigned TLD with value $699 (between these: .immersive; .multiverse; .freelancer; .cashback; .hologram)

you can chose on which blockchain you want to mint your NFT Domain/TLD on and minting fee is covered by Freename!


Fill in the form to Apply

Want to work with us? Let us know!

Why do i Need a Wallet?

Freename domains are blockchain-based assets and would be minted and stored using a wallet. Users are required to mint and manage their domains using a Metamask or Coinbase-configured wallet. It must be a non-custodial wallet, meaning that one must own the private keys to the wallet in order to approve transactions via a signature.

To benefit from Freename Web 3 domains/TLDs, you must have a wallet. This is because Web 3 domains/TLDs are blockchain-based assets. Users can mint and manage their domains using Metamask or Coinbase-configured wallets.

Keep in mind that it must be a non-custodial wallet. You own the private keys to the wallet (in order to approve transactions via a signature).

Are the Domains Associated with ICANN?

ICANN does not manage domains. believes their TLDs/domains must allow customers to operate independently. wants to build a utility infrastructure, allowing customers to use their services for valuable and generative purposes. By leveraging blockchain technology, Freename Web 3 domains/TLDs have no centralized authority imposing rules and regulations.

What is a Wallet?

Every blockchain user requires a wallet in order to interact with the network. A wallet is essentially an account on the blockchain where transactions can be sent and received. It is also where one can store blockchain assets such as cryptocurrency or NFTs (non-fungible tokens). There is no personal information associated with a wallet and none is required to create one. A wallet consists of a public key and a private key. The public key can be safely shared with anyone who wishes to send assets to the corresponding wallet, however, the private key should not be shared and is the key to accessing the wallet in the event where access is lost or to create another instance.

A crypto wallet (cryptocurrency wallet) is software or hardware that enables users to store and use cryptocurrency. With cryptocurrencies, there isn’t any actual money to carry around in a wallet. They exist on the blockchain. Similarly to traditional bank transfers, crypto wallets enable users to send and receive cryptocurrencies, NFTs, etc.

A wallet consists of a public key and a private key. To receive assets, you share your public key associated with your wallet. You should NEVER share your private key.

How do i Claim my Earnings from Freename

ou can withdraw revenues generated passively through a cryptocurrency transfer. Connect your cryptocurrency wallet and, once your withdrawal request is confirmed, the desired amount is pulled from Freename’s reserves and conveniently delivered to you!

Claim your earnings by following these steps:

  1. Connect your cryptocurrency wallet to
  2. Request a withdrawal
  3. Receive request confirmation
  4. Receive withdrawal directly to your wallet.

Can i Transfer Domains?

Yes. The domain is stored in your cryptocurrency wallet and can be transferred by you after you have minted it. Access your portfolio, select the TLD or Domain you wish to transfer and type the recipient’s address. Afterwards, you must paste the OTP code you received by mail to confirm the transaction. Keep in mind that currently, it is not possible to import the domain that has been transferred, but it will be possible soon!

Yes. Domains are transferable ONLY after a TLD/domain has been minted and stored in a user’s wallet.

To transfer the TLD (or domain), the user must:

  • Access their wallet
  • Select the item they want to transfer
  • Enter the recipient’s address.
  • Confirm the transaction by pasting the OTP received by email

In the future, will support importing domains that have been transferred.

What about Trademarks?

Registering a trademark on your Freename Web3 TLD will allow you to protect your web3 TLD and your logo worldwide juridically.

From the moment you deposit a trademark request, your web3 TLD will be protected worldwide for 6 months awaiting for the Swiss Federal Institute of Intellectual Property ( to confirm and register the availability of your TLD.****

A trademark is any symbol, phrase, or word that allows customers to identify a company’s goods or services. Freename is a web3 domain/TLD provider that also provides trademark registration.

A user must reach out to the trademark department to register a trademark. To get your trademark filed for review at the Swiss Federal Institute of Intellectual Property, a user must provide the following:

  1. Complete a Know your customer (KYC)
  2. A list of TLDs they wish to trademark
  3. Proof of payment

Once these conditions are met, it takes one week for the trademark to be reviewed and logo/TLDs to be provided with six months of worldwide protection.

Is Minting the same as Buying?

Purchasing a TLD (or domain) on Freename and minting it on the blockchain are two distinct steps. When you purchase a TLD (or domain), the transaction is recorded in Freename’s database and not on the blockchain. Minting a TLD (or domain) on the blockchain requires a second step: log into the user’s personal area, select the TLD (or domain) and press “mint TLD” (or domain): done! Don’t worry, once you have purchased a Freename domain, no one can take it away from you!

No. Buying and Minting a TLD/domain are two different things.**

Buying **is the process of recording a transaction on Freename’s database and not on the blockchain.

Minting is the process of pushing a user’s domain from data onto the public ledger of a blockchain and into a user’s wallet. Giving the user full control over the TLD/domain.

It is very easy to mint a domain/TLD once you purchase it. Simply:

  • Log into your personal area
  • Select the TLD (or domain)
  • Press “mint TLD” (or domain)

What is Domain Minting?

Minting is the process of publishing a Freename domain (or TLD) on the blockchain via your wallet to gain full custody of the domain. This means that the only person that has control over the domain (or TLD) is the person who controls (has access to) the wallet.

Minting is the process of pushing a user’s domain from data onto the public ledger of a blockchain and into a user’s wallet. Giving the user full ownership over the domain.

Minting on is as simple as the following steps:

  1. Go to the website
  2. Enter the TLD/domain you want to buy in the search bar
  3. Add the TLD/domain to your cart
  4. Go to checkout
  5. Create a account
  6. Purchase the TLD/domain with cryptocurrency or a credit card
  7. Go to “portfolio and incomes.”
  8. Click on mint TLD/domain

Which domains are Protected?

Protected domains and TLDs are domains and TLDs that we’ve detected are associated with a brand, organization, or notable person. We believe it is important to increase adoption for the next generation of the internet by helping to onboard brands into the Web3 era. If you are interested in applying for a Protected domain, please contact us.

TLDs/Domains associated with a notable person, brand or organization are considered Protected Domains. Protected domains help onboard brands in Web 3 increasing adoption. Protected domains also protect users from others impersonating/stealing their domains.

Reach out to to apply for a protected domain.

Why use Freename?

Freename domains are unique by their very nature: only with Freename you can register domains with unique TLDs for your digital identity while passively earning money! is not only the leading TLD and Domains platform in Web 3, but also lets users generate passive income!

Owning a Freename Web 3 TLD entitles users to receive passive income whenever a domain is bought on their TLD. Users can register and mint TLD/domains of their choice if available.

What is a Domain?

A domain name is a string of letters and/or numbers that points to the IP address of the corresponding website. Generally, it is easier to remember a name than a long string of numbers.

A domain name is an address that people type into a browser bar to find a website. It consists of a Top-Level Domain (TLD), everything that comes after the dot, and the Second-Level Domain (SLD), everything that comes before the dot.

For example, “” is the domain name, “Freename” is the SLD and “io” is the TLD.

Which Chains are Supported?

Freename has a multi-chain approach. You can choose on which Blockchain to mint your Web3 Domains and TLDs ranging Among Polygon, Cronos, and Binance.

A user can mint a domain/TLD on the following blockchains:

  • Polygon
  • Cronos
  • Binance

Freename plans to expand its multi-chain approach by adding blockchains upon which domains can be minted.

Are there Renewal Fees?

No! Once you’ve bought a Freename Domain or TLD, it’s yours forever, no renewal fees ever!

No. There are no renewal fees on Once a user has paid a one-time payment for a domain/TLD, they own it. Forever.

This is the significant advantage of Web 3 domain/TLD over traditional alternatives.

Ask Away!