# Auctions

**URL:** https://heroiclabs.com/docs/hiro/concepts/auctions/
**Keywords:** auctions, hiro
**Categories:** hiro, auctions, concepts

---


# Auctions

Hiro Auctions provides an open marketplace for users to trade items through competitive bidding within a set time frame. The system ensures fair participation by validating a user's ability to afford bids, and guarantees reliable exchanges between the highest bidder and the seller at the end of each listing.

An auction listing is essentially an item for sale with a series of bids. Key elements include:
- The end time of the listing.
- The current highest bid or starting bid.
- The minimum required bid for the next participant.

Listings can only be created for items in the seller’s Hiro Inventory.

## Lifecycle

Each auction progresses through a simple, linear process:

1. Creating a Listing: The seller chooses an item from their inventory, and it is removed from their possession until the auction concludes.
2. Bidding: Other users bid, with amounts deducted from their wallets to ensure they can afford the bid at both placement and auction close. Users cannot bid on their own listings or on those where they are the current highest bidder. Bidders that were outbid get their currency back immediately, no waiting until the end of the auction.
3. End of Auction: The listing concludes, and both the seller and winning bidder are notified to claim their rewards.
    - The seller collects the bid amount (minus fees).
    - The bidder receives the item.

## Customization Parameters:

The following JSON represents the customization parameters you can use to configure the default user experience for the Auctions system.

```json
{
  "auctions": {
    "auction1": {
      "items": [],
      "item_sets": ["weapons"],
      "conditions": {
        "short": {
          "duration_sec": 3600,
          "listing_cost": {
            "currencies": {
              "coins": 50
            }
          },
          "bid_start": {
            "currencies": {
              "coins": 10
            }
          },
          "fee": {
            "percentage": 0.10
          },
          "extension_threshold_sec": 30,
          "extension_sec": 60,
          "extension_max_sec": 300
        },
        "long": {
          "duration_sec": 86400,
          "listing_cost": {
            "currencies": {
              "coins": 200
            }
          },
          "bid_start": {
            "currencies": {
              "coins": 10
            }
          },
          "fee": {
            "percentage": 0.05
          }
        }
      }
    }
  }
}
```

The JSON schema defines an `auctions` object which _must contain an individual object for each auction_ you wish to define in the system. You can configure as few or as many auction types as needed for your desired gameplay.

{{< table name="gdk.concepts.auctions.auctions-system" >}}

Each individual auction is keyed by name and may define the following:

### Auction

{{< table name="gdk.concepts.auctions.auction" >}}

### Auction Condition

{{< table name="gdk.concepts.auctions.auction-condition" >}}

### Auction Condition Cost

{{< table name="gdk.concepts.auctions.auction-condition-cost" >}}

### Auction Condition Bid

{{< table name="gdk.concepts.auctions.auction-condition-bid" >}}

### Auction Condition Bid Increment

{{< table name="gdk.concepts.auctions.auction-condition-bid-increment" >}}

### Auction Condition Fee

{{< table name="gdk.concepts.auctions.auction-condition-fee" >}}