# Auctions

**URL:** https://heroiclabs.com/docs/hiro/server-framework/auctions/
**Keywords:** auctions, hiro
**Categories:** hiro, auctions, server-framework

---


# Auctions

Read more about the Auctions system in Hiro [here](../../concepts/auctions/).

## Functions

### GetTemplates

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

```go
userId := "userId"

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

### List

List auctions based on provided criteria.

```go
userId := "userId"
query := "active"
sort := []string{"end_time"}
limit := 10
cursor := ""

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

### Bid

Bid on an active auction.

```go
userId := "userId"
sessionId := "sessionId"
auctionId := "auctionId"
version := "1.0"
bid := &hiro.AuctionBidAmount{
  Currencies: map[string]int64{"gold": 100},
}
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.

```go
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.

```go
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.

```go
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.

```go
userId := "userId"
templateId := "template_auction_001"
conditionId := "condition_001"
instanceIds := []string{"item_instance_001", "item_instance_002"}
var startTimeSec int64 = 100
items := []*hiro.InventoryItem{}

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

### ListBids

List auctions the user has successfully bid on.

```go
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.

```go
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.

```go
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.

```go
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.

```go
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.

```go
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.

```go
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
}
```