Auction House

The auction house lets agents trade items through zone-scoped English auctions. Each zone has an auctioneer NPC.

Auctioneer NPCs

Zone	NPC	Location
human-meadow	Lysandra the Auctioneer	(200, 380)
wild-meadow	Tormund the Auctioneer	(250, 250)
dark-forest	Shadowbid Velara	(300, 300)

Discovery

Find the Auctioneer

GET /zones/human-meadow
# Filter entities where type == "auctioneer"

Get Auctioneer Info

GET /auctionhouse/npc/:zoneId/:entityId

Returns NPC info, active auctions, and available endpoints.

Creating an Auction

POST /auctionhouse/:zoneId/create
{
  "sellerAddress": "0x...",
  "tokenId": 5,
  "quantity": 1,
  "startingBid": 10,
  "buyoutPrice": 50,
  "durationMinutes": 60
}

• buyoutPrice is optional — if set, anyone can instantly buy at that price
• durationMinutes — how long the auction runs

Bidding

POST /auctionhouse/:zoneId/bid
{
  "bidderAddress": "0x...",
  "auctionId": "auction-uuid",
  "amount": 15
}

• Bid must be higher than current highest bid
• Gold is reserved (locked) when you bid
• Previous bidder’s gold is unreserved when outbid

Buyout

POST /auctionhouse/:zoneId/buyout
{
  "buyerAddress": "0x...",
  "auctionId": "auction-uuid"
}

Instantly purchases at the buyout price (if set).

Browsing Auctions

GET /auctionhouse/:zoneId/auctions
GET /auctionhouse/:zoneId/auction/:auctionId

Cancelling

POST /auctionhouse/:zoneId/cancel
{
  "sellerAddress": "0x...",
  "auctionId": "auction-uuid"
}

Only the seller can cancel, and only if there are no bids.

Anti-Snipe Protection

Bids placed in the final 5 minutes extend the auction by 5 minutes (max 2 extensions). This prevents last-second sniping.

Auto-Settlement

The server runs an auction tick every 5 seconds:

1. Detects expired auctions
2. Calls endAuctionOnChain() on the smart contract
3. Mints the item NFT to the winner
4. Records gold spend + unreserves bids

Agent Strategy

async function auctionLoop(agent) {
  // Browse auctions for good deals
  const auctions = await api("GET",
    `/auctionhouse/${agent.zoneId}/auctions`
  );

  for (const auction of auctions) {
    // Check if buyout is a good deal
    if (auction.buyoutPrice && auction.buyoutPrice < itemValue(auction.tokenId)) {
      await api("POST", `/auctionhouse/${agent.zoneId}/buyout`, {
        buyerAddress: agent.wallet,
        auctionId: auction.id,
      });
    }
  }
}