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.

Auctions can also be used for direct trades by restricting a listing to specific players. You can limit who is allowed to bid on a listing, let bidders pay with inventory items in addition to currency. You can also configure an ‘immediate buyout’ auction that settles the moment a bidder meets the asking price.

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. The seller can optionally restrict the listing to a set of allowed players, for example a guild, a friends list, or a single player.
2. Bidding: Other users bid with currency, items, or both. Currency and items are escrowed at placement to guarantee the bidder can honor 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 are outbid get their currency and items 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 winning bid amount in currency and items (minus fees).
   • The bidder receives the item.

For a fixed-price listing configured with immediate_buyout, the auction settles inline as soon as a bidder meets the asking price exactly. The bidder receives the item immediately, and the seller claims the bid amount through the normal claim flow.

Restrict a listing to specific players #

By default an auction is public and any eligible player can find and bid on it. To restrict a listing, pass a list of allowed player IDs when creating it. Only those players can see, follow, and bid on the auction. Bids and follows from anyone not on the list are rejected. This supports a range of private auctions: a guild or team sale, a friends-only listing, or a one-to-one trade offered to a single player.

The allowed players are set per listing at creation time, not in the auction template, so the same auction configuration can back both public and restricted listings.

Restricting a listing controls who can access it, not how they learn about it. Notifying a targeted player is up to your game, for example through your own messaging or a Hiro notification. The targeted player can also discover the auctions directed at them at any time by calling the list auctions API with the allowed_only filter set to true, described in the next section.

Separate public and restricted listings #

Listing queries are scoped to the requesting player and are disjoint by intent:

• A standard listing query returns only public auctions.
• A directed query returns only auctions where the requesting player is on the allowed players list.

This lets a client show a player the public marketplace and the restricted auctions they’ve been invited to as two separate views, without leaking restricted listings to players who weren’t invited.

Bid with items #

Bidders can offer items from their inventory alongside or instead of currency. Item bids follow the same escrow guarantees as currency:

• Items are escrowed from the bidder’s inventory when the bid is placed.
• Items are returned to the bidder if they are outbid. If the previous bidder’s account was deleted before the refund, the items are forfeited.
• Items transfer to the seller when the auction is won.

Item requirements are counted by unit, not by item instance. A required count of three is satisfied by a single stack of three, or by three separate instances. The bid must match the required item counts exactly: supplying the wrong quantity or extra instances is rejected. When the seller claims a won auction, the escrowed items are returned in the claim result so the game can grant them.

The item requirement is fixed for the lifetime of the listing and does not change between bids. Competitors raise the currency portion of their bid, while the required items stay constant. Bid increments apply to currencies only.

Fixed-price auctions with instant buyout #

Set immediate_buyout on an auction condition to create a fixed-price listing. When a bidder submits a bid that matches the required amount exactly, in currency and/or items, the auction completes immediately instead of running to its end time. The bidder receives the item straight away, and the seller claims the bid amount through the normal claim flow. A bid that over-pays the asking amount is rejected, so bidders must match the price exactly.

Combined with an allowed players list, immediate_buyout gives you a fixed-price private sale: a restricted listing that settles the moment an invited player meets the price. Restrict it to a single player for a one-to-one trade, or to a group for a first-come fixed-price offer.

Customization Parameters: #

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

{
  "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
          }
        },
        "fixed_trade": {
          "duration_sec": 3600,
          "immediate_buyout": true,
          "listing_cost": {
            "currencies": {
              "coins": 50
            }
          },
          "bid_start": {
            "currencies": {
              "coins": 100
            },
            "item_counts": {
              "repair_kit": 2
            }
          }
        }
      }
    }
  }
}

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.

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

Auction #

Auction Condition #

Auction Condition Cost #

Auction Condition Bid #

Auction Condition Bid Increment #

Auction Condition Fee #