Skip to content

State Machines

This page details the state machines that our used by our Marketplace API. Examples of how to query, manage, and modify these states can be found in our examples page within this documentation.


Trades can currently take place in either BuyNow or Auction modes.

BuyNow trades are simple: an asset is put for sale for a certain amount of time, and the first buyer to pay acquires the asset.

Auctions start with an initial price, set by the seller, and permit increasing bids during a period of time (set when auction is initialised). When the auction finishes, the highest bidder has a certain amount of time to complete the payment.

The asset remains in custody of the seller until the payment arrives, which triggers a direct transfer of ownership to the buyer. The asset is never in anyone else's custody, other than that of the buyer and seller.


Both BuyNow and Auction trades, once created, can be in several states. These states may be queried by our API; your application should do so regularly to ensure it is in sync.

For both BuyNows and Auctions, an asset is free to be put for sale, in any mode, as long as the following statement is false:

` the asset is an auction or a buynow in STARTED, FROZEN or PAYING state`.

In other words:

CAN BE PUT FOR SALE = !(the asset is an auction/buynow in STARTED, FROZEN or PAYING state)

For both modes, we provide below the detailed state machine. To illustrate the meaning of each state, we also provide examples of messages that could be displayed to users for each state. We have divided the user role as seller, buyer for BuyNows or max bidder for auctions, and spectator; the latter referring to users who do not participate in the trade process.


This is the complete state machine.

BuyNow States Machine

Example of messages for ongoing BuyNows

BuyNow Ongoing

Example of messages for ended BuyNows

BuyNow Ended


This is the complete state machine.

Auctions States Machine

Example of messages for ongoing Auctions

Auctions Ongoing

Example of messages for ended Auctions

Auctions Ended