Collectible Auctions

What are Auctions?

When you own a collectible, you can choose to auction it off via the ORB Marketplace. But what is an auction? And how do they work?

There are three types of auctions: Highest Bid, Price Drop and Sealed Bid. At the moment, ORB offer auctions only of the Highest Bid type.

Auction Start

At the start of the auction, the owner of the collectible will determine the number of editions they would like to add to this auction, together with the minimum bid they will set for the auction and the minimum increment. The minimum bid defines the minimum someone has to bid for the collectible to be auctioned, otherwise if the price point is not met, the collectible will be returned to your wallet address. On the other hand, the minimum increment defines the minimum added bid a user can set when bidding in the auction - the current bid needs to be incremented by at least the minimum bid. Another important parameter which needs to be determined at the start is the expiration date for the auction. This date will decide when the auction will end.

Auction Process

While the collectible is in an active auction, the collectible will have an indication to show users of ORB that the auction is ongoing. It will also show the current bid, and the expiration time for when the auction will end. Users will be able to bid based on the parameters set at the start of the auction.

Auction End

The auction ends once the time elapses. The user with the highest bid will get the collectible, and the previous owner of the collectible will receive the highest bid.

Using the API calls mentioned below, you can include the auction functionality to your projects. Here is how.

Create an Auction

Use the following mutation to create an auction for a collectible in ORB.

CreateAuction
mutation CreateAuction($input: CreateAuctionInput!) {
  CreateAuction(input: $input) {
    state
    transactionHash
  }
}
Input Variables
"input": {
    "collectionId": "KT1AcxKcwf5bdNfwY6qYMVFjx4mGVftLThP2",
    "currentPrice": 250,
    "endTime": "1700642468",
    "priceIncrement": 10.5,
    "startTime": "1700642470",
    "tokenId": "25"
 }

In terms of the input variables of the mutation, here are a few tips to help you understand the process:

  • collectionId: This is the collectionId of the collectible on which this mutation will have an effect on. More specifically, this is the collectionId under which you have created your collectible, which you wish to add in an auction.

  • currentPrice: This is the minimum bid that you will set for the auction of the collectible.

  • endTime: This is the time that the auction will end. The format of this input needs to be in epoch. Here is a very handy date time to epoch converter, to help you with this input parameter.

  • priceIncrement: This is minimum increment a user needs to add to their bid if they wish to take part in the auction.

  • startTime: This is the time that the auction will start. You can set this to a future time if you want it to not directly start, or the current time otherwise. The format of this input needs to be in epoch. Here is a very handy date time to epoch converter, to help you with this input parameter.

  • tokenId: This is the tokenId of the collectible on which this mutation will have an effect on.

Once you call the mutation, you will receive the following transaction. Upon signing the transaction, the collectible will be send to the Marketplace contract and the auction will be created in the ORB Marketplace.

Sample Response
{
  "data": {
    "CreateAuction": {
      "state": "operation_response",
      "transactionHash": "opYHmJNbksexJwxVYL47dqzgHXduAqG4KnqmYUvM53DicAXVHAf"
    }
  }
}

Once the transaction has been signed from the developer, the auction will appear in the ORB Marketplace. In case the auction is not set to start right away, the collectible will have an indication to show users that an auction for it is scheduled. Otherwise, the collectible will have an indication to show that it is in an active auction and so that users can actively participate and bid.

Bid in an Auction

Use the following mutation to bid in an ongoing, active auction in ORB.

FulFillOffer
mutation Bid($input: AuctionBidInput!) {
  Bid(input: $input) {
    state
    transactionHash
  }
}
Input Variables
"input": {
    "Amount": 260.50
    "AuctionId": "862"
 }

In terms of the input variables of the mutation, here are a few tips to help you understand the process:

  • Amount: This defines the amount you want to bid in this active auction.

  • AuctionId: This is the AuctionId of the auction on which this mutation will have an effect on.

Once you call the mutation, you will receive the following transaction. Upon signing the transaction, the collectible will be sold, and the listing fulfilled.

Sample Response
{
  "data": {
    "Bid": {
      "state": "applied",
      "transactionHash": "opC2d7YNjau2ncARApPnP5vUX7PauLrkkHz62ER2uvu9FWymau7Xa2"
    }
  }
}

Once the transaction has been signed from the developer, the bid, if it follows the rules set by the auction, will be set as the current latest and highest bid of the auction.

Cancel an Auction

You can always cancel an auction you have created in the ORB Marketplace, before the time remaining ends. Once an auction gets canceled, the collectible will return to your wallet address even if bids have already been made in the auction.

Use the following mutation to cancel an auction in ORB.

CancelAuction
mutation CancelAuction($input: RetractListingInput!) {
  CancelAuction(input: $input) {
    state
    transactionHash
  }
}
Input Variables
"input": {
    "AuctionId": "3"
 }

In terms of the input variables of the mutation, here are a few tips to help you understand the process:

  • AuctionId: This is the AuctionId of the listing on which this mutation will have an effect on.

Once you call the mutation, you will receive the following transaction. Upon signing the transaction, the auction of the collectible will be canceled and removed from the ORB Marketplace immediately.

Sample Response
{
  "data": {
    "CancelAuction": {
      "state": "applied",
      "transactionHash": "opC9y7YNYCgGRApPnP5vUX7LeuLrkkHz62ER2uvu9FWymau7Xa2"
    }
  }
}

Last updated