Auction

English (ascending-price) auctions over any item identifier: create with starting, reserve, and buy-it-now prices, take manual and proxy bids with funds escrowed through the treasury, and settle automatically at the end time or on demand. Every example on this page was executed against a live server.

When to reach for it: marketplace listings, in-game item sales, ad-slot or resource allocation - anywhere the price should be discovered by open competitive bidding.

When not to: selling at a fixed price is the Item and Cart services; picking winners by weighted random draw is Lottery.

Concepts

• English auctions only - the first bid must meet the starting price; every later bid must be at least the current high bid plus bid_increment.
• Lifecycle - scheduled -> open -> closing -> sold | unsold, plus cancelled. Every auction is created scheduled; a background scheduler opens it at start_time and settles it at end_time, or the seller transitions and closes manually.
• Bids escrow real funds - each bid places a treasury hold for the full amount; the hold is released when outbid or when the bid does not win.
• Proxy bids are a private ceiling: the service auto-bids the minimum needed to keep the proxy owner in front, until a rival exceeds the ceiling.
• Reserve price is the seller's minimum. A high bid ending below it settles the auction unsold with no winner and every hold released. (The value is returned in detail responses, so it is not hidden from clients.)
• Buy-it-now - a bid at or above buy_it_now_price wins and settles the auction in the same request.
• Anti-sniping - a bid inside the protection window (180 seconds by default) pushes end_time out by that window; verified to the second.

Create and open

snug auctions create --item-id vintage-guitar --starting-price 100.0 \
  --reserve-price 500.0 --buy-it-now-price 1000.0 --bid-increment 5.0 \
  --end-time 2026-08-29T00:00:00Z
snug auctions get <auction-id>
snug auctions update-status <auction-id> --status open

start-time defaults to now, end-time to 24 hours out, and the currency to the server's configured one (auction_credits here). Reserve and buy-it-now prices must be at least the starting price (400 invalid_bid otherwise). The new auction is scheduled even when its start time has passed - the scheduler opens it within a few seconds, or update-status opens it immediately. Transitions are FSM-guarded (scheduled -> sold is 400 invalid_status_transition), and only the seller or a platform admin may transition, close, or cancel (403 otherwise). --item-container-id ties the auction to an item-service container so the real item transfers to the winner at settlement.

Bidding

snug auctions bid <auction-id> --amount 100.0
snug auctions bid <auction-id> --amount 150.0 --idempotency-key retry-1

A bid that fails the price floor is not an HTTP error - the server answers 200 with accepted: false (here, bidding 104.0 against a high bid of 100.0 with increment 5.0):

curl -X POST -H "Authorization: Bearer $SNUG_API_TOKEN" \
  -H "Content-Type: application/json" -d '{"amount": 104.0}' \
  http://localhost:4000/api/v1/auctions/NddLNdhWynZB/bids

{
  "status": 200,
  "msg": "OK",
  "data": {
    "accepted": false,
    "current_price": 100.0,
    "your_bid": 104.0,
    "closed": false,
    "message": "Bid rejected - amount too low or auction not open"
  }
}

The CLI treats accepted: false as a failure and exits non-zero. Real errors do use error responses: bidding on a scheduled auction is 400 auction_not_open, a wallet that cannot cover the hold is 400 insufficient_funds, and sellers cannot bid on their own auction (400). Retrying with the same --idempotency-key never double-bids: the duplicate comes back accepted: false.

A bid at or above the buy-it-now price ends everything at once - verified closed: true with message Bid accepted - auction closed (buy-it-now), the auction sold, and the funds already settled to the seller's wallet.

Proxy bidding

snug auctions proxy-bid <auction-id> --max-amount 300.0
snug auctions bid-history <auction-id> --limit 20

A proxy is a standing instruction: the service bids on the owner's behalf, always the minimum needed to lead, up to the ceiling - and it acts the moment it is set, plus instantly after each rival bid, within that rival's own request. The verified bidding war, the bid-history output that records it, and the proxy gotchas have their own page: Proxy bidding.

Closing, settlement, cancellation

snug auctions close <auction-id>    # settle now (seller or admin)
snug auctions cancel <auction-id>   # void and release all holds

close settles immediately; the scheduler does the same at end_time (verified: an expired auction settled sold to its high bidder within seconds). Settlement checks the reserve: closing an auction whose 400.0 high bid sat below its 500.0 reserve returned "status": "unsold", reserve_met: false, no winner, and released every hold. When it is met or absent, the winner's hold is captured and paid to the seller, losing holds are released, and the item transfers if a container was given. cancel works from scheduled or open and reports holds_released; sold and cancelled are terminal.

Batch create

snug auctions batch-create --file auctions.json

The file is a bare JSON array of auction objects - item_id, starting_price, bid_increment, start_time, and end_time are all required here (the file bypasses the CLI's flag defaults):

[
  { "item_id": "lot-1", "starting_price": 10.0, "bid_increment": 1.0,
    "start_time": "2026-08-28T13:00:00Z", "end_time": "2026-08-29T13:00:00Z" }
]

The batch is all-or-nothing, capped per request (100 by default). Verified: a batch with one valid and one invalid entry failed with 400 invalid_bid and created neither.

Finding auctions

snug auctions list --status open --limit 50

The HTTP list endpoint speaks the shared search grammar: filter supports eq on item_id, seller_id, auction_type, and status, plus epoch-millisecond ranges on start_time and end_time, which also sort. Verified: filter=status:eq:scheduled&sort_by=created_at&sort_order=desc. No field is full-text indexed, so q matches nothing - use filter.

Limits and configuration

The sniping window, proxy-bid maximum, default currency and its decimal places, bid-history cap (200), auction state TTL (30 days), scheduler interval, and batch cap are all tunable via the AUCTION_* variables in the Auction CONFIG reference.

Reference

• Auction API - every endpoint, callable
• Related: Treasury for the wallets, currencies, and holds that bids escrow against, Item for real item transfer at settlement, Lottery for weighted random draws