Auctions

Auctions enable players to interact within a player-driven economy by bidding on or directly purchasing items. Learn more in the Auctions concept guide .

Overview #

Auctions provide a dynamic system for players to trade items by:

Allowing players to list items for auction.
Facilitating competitive bidding processes.
Managing transactions securely and transparently.

Prerequisites #

Unity project set up with Hiro SDK
Nakama System integrated (guide )

Working with Auctions #

Creating an Auction #

Create a new auctions for players:

1
2
3
4
5
request = AuctionCreateRequest()
request.template_id = "template_auction_001"
request.condition_id = "condition_001"

auction = await hiro_client.auctions_create(request)

To restrict an auction to specific players, for example a guild, a friends list, or a single player for a one-to-one trade, set allowed_user_ids to the user IDs allowed to see and bid on it. Omit it to list the auction publicly.

1
2
3
4
5
6
request = AuctionCreateRequest()
request.template_id = "template_auction_001"
request.condition_id = "condition_001"
request.allowed_user_ids = ["8f34a3c2-1b1e-4b3a-9c9e-2f6a1d3e5b7c"]

auction = await hiro_client.auctions_create(request)

Placing a Bid on an Auction #

Submit a bid on an active auction:

1
2
3
4
5
6
7
8
9
request = AuctionBidRequest()
request.id = "auction_instance_123"
request.version = "1.0"
request.bid = AuctionBidAmount()
request.bid.currencies = {
    "gold": "1000"
}

auctions = await hiro_client.auctions_bid(request)

A bid can also include inventory items instead of, or alongside, currencies. Set instance_ids on the bid to the item instance IDs the player is escrowing, and leave currencies unset if the bid is items only.

1
2
3
4
5
6
7
request = AuctionBidRequest()
request.id = "auction_instance_123"
request.version = "1.0"
request.bid = AuctionBidAmount()
request.bid.instance_ids = ["item_instance_456", "item_instance_789"]

auctions = await hiro_client.auctions_bid(request)

Cancelling an Auction #

Cancel an ongoing action:

1
2
3
4
request = AuctionCancelRequest()
request.id = "auction_instance_123"

auctions = await hiro_client.auctions_cancel(request)

Claiming a Winning Bid #

Claim the item the player won:

1
2
3
4
request = AuctionClaimBidRequest()
request.id = "auction_instance_123"

auctions = await hiro_client.auctions_claim_bid(request)

List Available Auctions #

View current active auctions:

1
2
3
request = AuctionListRequest()

auctions = await hiro_client.auctions_list(request)

Set allowed_only to True to return only directed auctions where the caller is on the allowed_user_ids list. Leave it False or omit it to return only public auctions. The two result sets are disjoint, so query each separately if you need both.

1
2
3
4
request = AuctionListRequest()
request.allowed_only = True

auctions = await hiro_client.auctions_list(request)

Heroic Cloud