Web3 Reseller APIs (v. 1.0)
Business Logic in general
Reseller APIs are provided to organizations or companies (ie. the “Reseller”) that wish to sell Web3 domains to their customers through the Freename infrastructure. Freename assign, mint and delegate control of one or more TLDs to the Reseller allowing it to issue and mint domains for the assigned TLDs.
Upon contract definition, Freename and the Reseller agree the invoicing terms for the creation, minting and control of domains, minting rates and the related API calls quotas. The Reseller is able to control the status of quotas and its Web3 domains set through control and utility APIs respectively.
Reseller Control Logic and Utilities
Freename Resell APIs are intended for Resellers that want to offer domains to their customers without exposing any information about their customers to Freename. The Resell APIs do not need any personal or organizational information to be able to create, control and mint domains and records. The Reseller must therefore maintain himself a coherent relation between domains and the end user (i.e. the Reseller’s customer) that owns these domains.
Through the Logic APIs the Reseller can:
check if a domain already exists both in Freename database and on-chain
create a domain (and implicitly a Web3 zone similar to a DNS zone) and manage it
asynchronously mint a domain on one or more blockchains and deposit them on one or more wallets in the chosen blockchains and check the status of minting through a polling end point
list and retrieve domains and their related records
create and manage a set of Web3 zone records
Through the Utilities APis the Reseller can:
fetch Whois information for any Web3 domain created and minted through Freename
generate reports on various domain management activities, including minted zones and usage statistics.
obtain a status and counters for quota usage and limits
obtain the billing status with time filters and/or domain filters
The Reseller APIs are provided with the RESTful paradigm with a Json payload for requests and responses.
Web3 records
The records management APIs support the following record types:
A, AAAA, MX, CNAME, NS, SOA, TXT, PTR
and the following Web3 records. The Web3 records can be used to create alias to addresses, wallets, etc…
TOKEN, PROFILE, LINK, CONTRACT, OTHER
Minting & Web3 Features
Assigned TLDs for a given Reseller are minted and transferred to the Reseller wallet of his choice by Freename itself. The Reseller can then chose to mint domains for the assigned TLDs on his wallet(s) or his customers' wallets depending on the features and user journeys that the Reseller whish to provide to his own customers.
Although the domain creation and minting can be requested “at the same time” by the reseller, the Minting process takes in general a few minutes. That means that the Reseller take into account this behavior and is responsible to control the effective successful minting of a domain using the minting status API and eventually inform its end user about the minting status.
Fees and gas
On-chain fees and gas for transactions (domain minting and records creation) are provided by a Freename wallet and will be invoiced through the normal billing process previously agreed.
Supported blockchains
Ethereum
Binance Smartchain
Polygon
Base
Solana
Access and Quotas
APIs are privately exposed, i.e. the Reseller will provide a set of IPs to Freename to be white-listed. Freename will create API users for the Reseller and deliver the credentials to the Reseller with the proper permissions.
The Reseller may not delegate or resell access credentials to anybody and he is the sole entity allowed to access APIs endpoints.
Freename and the Reseller agree on a timespan minting rate i.e. on the maximal number of possible minted domains in a given period.
APIs quotas are a way to limit Reseller calls to the Freename backend preventing unintended flood of the system. In some cases the Reseller and Freename may agree on a 0-quota policy provided that the integration implemented by the Reseller is bug free and properly tested. The only API endopint always subject to quota is the Whois API.
Reseller APIs System Architecture
The Reseller APIs are a subset of the Freename APIs. The APIs controllers inquiry and read state and data from the Freename Backend. The Freename backend is composed by a set of microservices with a shared state and shared database cluster.
A servicing independent and redundant Web3 driver to read and write from and to the blockchain is exposed to the backend microservices.
Infrastructure Architecture
The Freename Reseller APIs are implemented in a redundant, geographically segregated and balanced infrastructure. Two Application load balancers facing third parties distribute calls on a multi-instance target group of REST controllers. The Cloud infrastructure provider is Amazon AWS.
Last updated
