# Auctions

Time-boxed bidding with a clear winner and a buy-out finalization step. Built on top of the basic listing flow.

***

## Auction lifecycle

```
       ┌─────────┐       ┌────────┐       ┌─────────┐
create │ waiting │──────▶│ active │──────▶│  ended  │ ──▶ winner buys out
       └─────────┘       └────────┘       └─────────┘
            ▲                                  │
            │                                  │
       (no bids,                          (winner inactive
        can remove)                       48h auto-cleanup)
```

* **waiting** — `now < auction_starts_at`. Visible in the market but `Submit bid` is disabled.
* **active** — bids accepted; current price = highest bid.
* **ended** — `now > auction_ends_at`. No more bids. Only the highest bidder sees **Buy out**.

***

## Bidding rules

A bid is **accepted** if **all** of these hold:

1. Listing exists and is of type `auction`.
2. Auction has not ended (`auction_ends_at > NOW()`).
3. `amount >= price` (the seller's reserve).
4. `amount > currentMax` (must outbid the leader).
5. Bidder has at least `amount` in their bank.

:::hint{type="warning"}
Rule #5 was added in **v1.0.0**. Earlier versions let players bid arbitrarily and refuse to pay later — now you must have the funds at bid-time.
:::

***

## What auctions cost

* **No fee to bid** — submitting an offer is free.
* **Listing fees** still apply to the seller, same as buy-now. See [Exchange](/free/carmarket/configuration/exchange).
* **Commission** is taken from the final sale price the same way as buy-now.

***

## After the auction ends

The seller has nothing to do. The winner sees a **Buy out** button next to the listing:

1. Winner clicks **Buy out**.
2. Server validates: are they the highest bidder? does the auction actually end?
3. Money moves: winner → seller (minus commission) → zone owner (if any).
4. Vehicle is transferred to the winner's garage; listing is deleted.

:::hint{type="info"}
If the winner never claims, a periodic sweep deletes the listing after a grace period. The vehicle stays with the original seller.
:::

***

## Cancellation

You **can** cancel an auction:

* If `status == 'waiting'` (no bids yet)

You **cannot** cancel:

* Once `active` (any bid placed locks the auction)
* Once `ended` (winner gets first dibs)

***

## UI events

The frontend listens to `koja_carmarket:client:auctionUpdated`:

```ts
{ listingId: number, event: 'started' | 'ended' | 'bid_placed' }
```

* `started` — fires the minute `auction_starts_at` is crossed
* `bid_placed` — fires on every accepted bid (broadcast to all clients)
* `ended` — fires when the auction is over (either by time or by buy-out)

The market view auto-refreshes on these events so bidders see live data without polling.

## Related pages

- [Exchange Zones](/free/carmarket/features/exchange-zones) — A player can own an entire zone and run it like a small business: set listing fees, take commission on every sale, cap how many listings can run concurrently.
- [Overview](/free/carmarket/features/overview) — What players can actually do with Koja-Carmarket, from their POV.
- [Parking Slots](/free/carmarket/features/parking-slots) — Before a player can list a car, they need at least one parking slot in the zone they want to list in.
- [Listings](/free/carmarket/features/listings) — The simplest flow: a player lists a vehicle from their garage at a fixed price; another player walks up to the market zone, opens the tablet, and buys it.
- [Test Drives](/free/carmarket/features/test-drives) — Let a buyer try the vehicle before they commit.
- [Features](/free/carmarket/features) — back to the section overview