The DomainSale command-line interface (CLI) provides access to the DomainSale process for both buyers and sellers. It is highly useful in automated or bulk environments, and allows scripting and other advanced integration with DomainSale.

Before using the CLI, or any other DomainSale tool, please read the introductory article to ensure familiarity with the process for both buying and selling domains.

Installation and Setup

DomainSale uses geth's keystores to hold account information. If you do not have geth installed on your computer then you should install it following the official instructions.

To confirm that geth is configured correctly run geth account list in a terminal. You should see your addresses displayed, amongst other information. If you need to import addresses in to geth please follow the official instructions.

Operating system-specific installation instructions are provided below.

Windows

Download the relevant binary for your system architecture below. If you are not sure then then download the x86 binary.

• Windows AMD64 (64-bit)
• Windows x86 (32-bit)

The binary is standalone and does not require installation, however it can be moved to C:\Windows\System32 to make it accessible to all users.

Linux

Download the relevant binary for your system architecture below. If you are not sure then typing uname -m should provide you with an answer.

• Linux AMD64 (64-bit)
• Linux x86 (32-bit)
• Linux ARM5 (32-bit)
• Linux ARM6 (32-bit)
• Linux ARM7 (32-bit)
• Linux ARM64 (64-bit)

Once the binary has been downloaded it needs to be made executable with the command chmod 755 domainsale. The binary is standalone and does not require installation, however it can be moved to /usr/bin to make it accessible to all users.

OSX

Download the relevant binary for your system architecture below. If you are not sure then typing uname -m should provide you with an answer.

• OSX AMD64 (64-bit)
• OSX x86 (32-bit)

Once the binary has been downloaded it needs to be made executable with the command chmod 755 domainsale. The binary is standalone and does not require installation, however it can be moved to /usr/bin to make it accessible to all users.

Commands

DomainSale is configured as a single binary with sub-commands. Details on each of these commands is listed below. In addition, help can be obtained for any command by entereing the command with the --help option.

There are a number of options that are available for all commands. These are:

• quiet do not display any output, and provide an exit status of 0 or 1 to indicate success or failure. Details of exactly what constitutes success is provided in the help for each individual command
• connection the connection to the geth instance that will be used to obtain DomainSale information and send transactions. This defaults to a remote server, which allows the CLI to be used from anywhere with a network connection. If you would prefer to use a different geth instance then you can change this to point to its HTTP port or IPC connection
• log log information about transactions generated by the CLI to a log file. By default this will create a file domainsale.log in your home directory

Any commands that send transactions have the following additional options:

• passphrase the passphrase to unlock the account being used for the command. This is required to sign any transaction sent to the network, which is any action around buying or selling domains
• gasprice the price of gas for the transaction. This defaults to a relatively low value of 4GWei. If you are in a hurry with your transaction you might need to increase this to 20GWei or even higher. An overview of the expected transaction wait time for differing gas prices can be seen at http://ethgasstation.info/
• nonce the nonce for the transaction. Sending multiple commands in quick succession (for example, offering or bidding on multiple domains as part of a script) require nonces to avoid the issue where one command might attempt to override another in the chain. Sample scripts using nonces are shown in the examples section at the end of this document

General

The DomainSale process for buyers consists of a number of possibilities depending on if the buyer wants to purchase a domain outright or to bid for a domain.

search

Search for domains that match a given substring. An example of this is:

domainsale search myd

Breaking this down:

• search is the command to be carried out
• myd is the string for which any matching domain sale is returned

If domains are found this command will return info on each of them, for example:

mydomain61 auction closed at Sat Sep 23 06:40:37 with a winning bid of 0.2 Ether
mydomain62 is under auction and closes at Sun Sep 24 08:18:04.  It can be bid on for 0.44 Ether
mydomain76 can be purchased for 7 Ether or auctioned with a starting bid of 0.18 Ether
mydomain78 can be purchased for 8 Ether
mydomain86 can be auctioned with a starting bid of 0.16 Ether

info

Obtaining information about a sale is accomplished using the info command. An example of this is:

domainsale info mydomain.eth

Breaking this down:

• info is the command to be carried out
• mydomain.eth is the domain for which information is being sought

If the domain is not for sale this command will return

mydomain.eth is not for sale

If the domain is for sale this command will return (for example)

mydomain.eth can be bought for 9 Ether
Auction will start on bid of at least 0.7 Ether

If the domain is undergoing auction this command will return (for example)

Auction started at 2017-09-22 07:40:37 +0100 BST
Winning bid is 0.2 Ether
Next bid must be at least 0.22 Ether
Auction will end if no further bids received by 2017-09-23 07:40:37 +0100 BST

Buying domains

buy

Purchasing a domain outright is accomplished using the buy command. An example of this is:

domainsale buy --price="4 ether" --address=0xce4a68eafa7eda08e16419a14c146e1277fdebb5 --passphrase=my_secret_phrase mydomain.eth

Breaking this down:

• price is the amount of ether used to buy the domain
• address is the address of the account purchasing the domain
• passphrase is the passphrase to the account purchasing the domain
• mydomain.eth is the domain being purchased

If this command completes successfully it will present the transaction ID for the purchase of the domain. If it fails then it will present details about why it failed.

Bidding for domains

Bidding for a domain outright is accomplished using the bid command. An example of this is:

domainsale bid --bid="0.1 ether" --address=0xce4a68eafa7eda08e16419a14c146e1277fdebb5 --passphrase=my_secret_phrase mydomain.eth

Breaking this down:

• bid is the amount of ether used to bid for the domain
• address is the address of the account bidding for the domain
• passphrase is the passphrase to the account bidding for the domain
• mydomain.eth is the domain being bid upon

If this command completes successfully it will present the transaction ID for the bid for the domain. If it fails then it will present details about why it failed.

Winning and losing auctions

finish

After a domain auction auction has finished either the buyer or seller can finish the auction to exchange the domain for the winning bid. An example of this is:

domainsale finish --passphrase=my_secret_phrase mydomain.eth

Breaking this down:

• passphrase is the passphrase to the account that bought or sold the domain
• mydomain.eth is the domain for which the auction has finished

If this command completes successfully it will present the transaction ID for the completion of the auction. If it fails then it will present details about why it failed.

Checking and obtaining funds

balance

If a user bid as part of an auction but failed to win their funds will be held pending withdrawal. This is also true of all funds received by sellers of domains. This command lists any funds that are owed to the given address. An example of this is:

domainsale balance 0xce4a68eafa7eda08e16419a14c146e1277fdebb5

Breaking this down:

• 0xce4a68eafa7eda08e16419a14c146e1277fdebb5 is the address of the account that is being checked for funds

If this command completes successfully it will state the amount of funds pending withdrawal. If it fails then it will present details about why it failed.

withdraw

If a user bid as part of an auction but failed to win their funds will be held pending withdrawal. This is also true of all funds received by sellers of domains. This command withdraws any funds that are owed to the given address. An example of this is:

domainsale withdraw --passphrase=my_secret_phrase 0xce4a68eafa7eda08e16419a14c146e1277fdebb5

Breaking this down:

• passphrase is the passphrase to the account that has funds to withdraw
• 0xce4a68eafa7eda08e16419a14c146e1277fdebb5 is the address of the account that has funds to withdraw

If this command completes successfully it will present the transaction ID for the withdrawal of the funds. If it fails then it will present details about why it failed.

Selling domains

transfer

Prior to selling a domain on DomainSale the domain must be transferred to DomainSale's control. An example of this is:

domainsale transfer --passphrase=my_secret_phrase mydomain.eth

Breaking this down:

• passphrase is the passphrase to the account that currently owns mydomain.eth
• mydomain.eth is the domain being transferred

If this command completes successfully it will present the transaction ID for the transfer of the domain. If it fails then it will present details about why it failed.

offer

A seller can offer a transferred domain for either or both of sale or auction. An example of this is:

domainsale offer --price="10 ether" --reserve="1 ether" --passphrase=my_secret_phrase mydomain.eth

Breaking this down:

• price is the price at which the domain can be purchased directly; leave this out if not required
• reserve is the price at which the domain can be auctioned; leave this out if not required
• passphrase is the passphrase to the account that transferred mydomain.eth to DomainSale
• mydomain.eth is the domain being offered

If this command completes successfully it will present the transaction ID for the offer of the domain. If it fails then it will present details about why it failed.

cancel

A seller can cancel an offered domain if it has not been purchased and is not under auction. An example of this is:

domainsale cancel --passphrase=my_secret_phrase mydomain.eth

Breaking this down:

• passphrase is the passphrase to the account that transferred mydomain.eth to DomainSale
• mydomain.eth is the domain being cancelled

If this command completes successfully it will present the transaction ID for the cancellation of the domain sale. If it fails then it will present details about why it failed.

Examples

Bulk operations

A common requirement is to run bulk operations. A seller might want to list many domains, or a buyer might wish to bid on many domains. This can be accompished using the domainsale CLI and suitable scripting, for example using the script below:

# The address of the owning account of the names to be transferred
DOMAINS_OWNER=0x18a745ca319caf07a34049092c856f6bf8b367f3
# The current nonce
NONCE=`domainsale nonce ${DOMAINS_OWNER}`

for DOMAIN in `cat domains_i_want_to_transfer`
do
    # Carry out the transfer
    domainsale transfer --passphrase=my_secret_phrase --gasprice=20gwei --nonce=${NONCE} ${DOMAIN} && NONCE=$((NONCE+1))
done

There are two important points to note with this script. Firstly, it uses the nonce option and manually increments this after each successful operation. This is required as when sending a large number of transactions one after the other geth can become confused as to the current nonce when attempting to work it out automatically. Secondly, it provides an explicit gas price. This is important when carrying out bulk transactions as it ensures that the overall cost of operations is understood as well as the time for transactions to be mined.