Auctions

Read more about the Auctions system in Hiro here .

Functions #

GetTemplates #

List all available auction configurations that can be used to create auction listings.

1
2
3
4
5
6
userId := "userId"

templates, err := systems.GetAuctionsSystem().GetTemplates(ctx, logger, nk, userId)
if err != nil {
  return err
}

List #

List auctions based on provided criteria.

Set allowedOnly to true to return only the directed auctions this user is allowed to bid on, and false to return only public auctions. The two result sets are disjoint, so a client can present the public marketplace and a player’s restricted auctions as separate views. This supports private auctions such as guild or team sales, friends-only listings, and one-to-one trades: a seller restricts a listing to specific players, and each allowed player queries with allowedOnly set to true to find the listings they’ve been invited to.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
userId := "userId"
query := "active"
allowedOnly := false
sort := []string{"end_time"}
limit := 10
cursor := ""

templates, err := systems.GetAuctionsSystem().List(ctx, logger, nk, userId, query, allowedOnly, sort, limit, cursor)
if err != nil {
  return err
}

Bid #

Bid on an active auction.

A bid can include Currencies, item InstanceIds, or both. Item instances are escrowed from the bidder’s inventory when the bid is placed, refunded if the bidder is outbid, and transferred to the seller when the auction is won. If the auction is directed with allowedUserIds, a bid from any player not on that list is rejected.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
userId := "userId"
sessionId := "sessionId"
auctionId := "auctionId"
version := "1.0"
bid := &hiro.AuctionBidAmount{
  Currencies:  map[string]int64{"gold": 100},
  InstanceIds: []string{"item_instance_001"},
}
marshaller := &protojson.MarshalOptions{
  UseEnumNumbers:  true,
  UseProtoNames:   true,
  EmitUnpopulated: false,
}

auction, err := systems.GetAuctionsSystem().Bid(ctx, logger, nk, userId, sessionId, auctionId, version, bid, marshaller)
if err != nil {
  return err
}

ClaimBid #

Claim a completed auction as the successful bidder.

1
2
3
4
5
6
7
userId := "userId"
auctionId := "auctionId"

auctionClaimBid, err := systems.GetAuctionsSystem().ClaimBid(ctx, logger, nk, userId, auctionId)
if err != nil {
  return err
}

ClaimCreated #

Claim a completed auction as the auction creator.

The returned AuctionClaimCreated includes ReceivedItems, the items escrowed by the winning bidder that now transfer to the seller. For an instant-buyout listing the bidder receives the item inline at bid time, but the seller still calls ClaimCreated to collect the winning bid currency and items.

1
2
3
4
5
6
7
userId := "userId"
auctionId := "auctionId"

auctionClaimCreated, err := systems.GetAuctionsSystem().ClaimCreated(ctx, logger, nk, userId, auctionId)
if err != nil {
  return err
}

Cancel #

Cancel an active auction before it reaches its scheduled end time.

1
2
3
4
5
6
7
userId := "userId"
auctionId := "auctionId"

auctionCancel, err := systems.GetAuctionsSystem().Cancel(ctx, logger, nk, userId, auctionId)
if err != nil {
  return err
}

Create #

Create a new auction based on supplied parameters and available configuration.

Pass allowedUserIds to restrict the listing to specific players, for example a guild, a friends list, or a single player for a one-to-one trade. Only those players can see, follow, and bid on it. Leave the slice empty for a public auction. Pass overrideConfig to override the template configuration for this listing, or nil to use the template as defined.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
userId := "userId"
templateId := "template_auction_001"
conditionId := "condition_001"
instanceIds := []string{"item_instance_001", "item_instance_002"}
var startTimeSec int64 = 100
allowedUserIds := []string{"buyerUserId"}
items := []*hiro.InventoryItem{}
var overrideConfig *hiro.AuctionsConfigAuction

auction, err := systems.GetAuctionsSystem().Create(ctx, logger, nk, userId, templateId, conditionId, instanceIds, startTimeSec, allowedUserIds, items, overrideConfig)
if err != nil {
  return err
}

ListBids #

List auctions the user has successfully bid on.

1
2
3
4
5
6
7
8
userId := "userId"
limit := 10
cursor := ""

auctionList, err := systems.GetAuctionsSystem().ListBids(ctx, logger, nk, userId, limit, cursor)
if err != nil {
  return err
}

ListCreated #

List auctions the user has created.

1
2
3
4
5
6
7
8
userId := "userId"
limit := 10
cursor := ""

auctionList, err := systems.GetAuctionsSystem().ListCreated(ctx, logger, nk, userId, limit, cursor)
if err != nil {
  return err
}

Follow #

The user will receive real-time updates for auctions they have an interest in.

If an auction is directed with allowedUserIds, only the allowed players can follow it. Follow requests from other players are rejected.

1
2
3
4
5
6
7
8
userId := "userId"
sessionId := "sessionId"
auctionIds := []string{"auctionId1", "auctionId2"}

auctionList, err := systems.GetAuctionsSystem().Follow(ctx, logger, nk, userId, sessionId, auctionIds)
if err != nil {
  return err
}

Hooks #

SetOnClaimBid #

Set a custom reward function which will run after an auction’s reward is claimed by the winning bidder.

1
2
3
4
5
6
systems.GetAuctionsSystem().SetOnClaimBid(OnClaimBid)

func OnClaimBid(ctx context.Context, logger runtime.Logger, nk runtime.NakamaModule, userID, sourceID string, source *hiro.Auction, reward *hiro.AuctionReward) (*hiro.AuctionReward, error) {
	// Modify reward or take additional actions.
	return reward, nil
}

SetOnClaimCreated #

Set a custom reward function which will run after an auction’s winning bid is claimed by the auction creator. This hook now fires for item-only winning bids as well as currency bids.

1
2
3
4
5
6
systems.GetAuctionsSystem().SetOnClaimCreated(OnClaimCreated)

func OnClaimCreated(ctx context.Context, logger runtime.Logger, nk runtime.NakamaModule, userID, sourceID string, source *hiro.Auction, reward *hiro.AuctionBidAmount) (*hiro.AuctionBidAmount, error) {
	// Modify reward or take additional actions.
	return reward, nil
}

SetOnClaimCreatedFailed #

Set a custom reward function which will run after a failed auction is claimed by the auction creator.

1
2
3
4
5
6
systems.GetAuctionsSystem().SetOnClaimCreatedFailed(OnClaimCreatedFailed)

func OnClaimCreatedFailed(ctx context.Context, logger runtime.Logger, nk runtime.NakamaModule, userID, sourceID string, source *hiro.Auction, reward *hiro.AuctionReward) (*hiro.AuctionReward, error) {
	// Modify reward or take additional actions.
	return reward, nil
}

SetOnCancel #

Set a custom reward function which will run after an auction is cancelled by the auction creator.

1
2
3
4
5
6
systems.GetAuctionsSystem().SetOnCanceç(OnCancel)

func OnCancel(ctx context.Context, logger runtime.Logger, nk runtime.NakamaModule, userID, sourceID string, source *hiro.Auction, reward *hiro.AuctionReward) (*hiro.AuctionReward, error) {
	// Modify reward or take additional actions.
	return reward, nil
}

Heroic Cloud