Bids — Bidyear API

GET /api/v1/lots/{lot}/bids Public

Returns the bid history for a lot. Bidder identities are anonymised as Bidder #N. Proxy/max bid amounts are never exposed.

Path parameters

Param	Type	Description
lot	integer	Lot ID

Response 200

{
  "success": true,
  "data": [
    {
      "id": 101,
      "amount": 15000.00,
      "is_proxy": false,
      "bidder": "Bidder #3",
      "is_winning": true,
      "placed_at": "2026-07-10T14:32:00Z"
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 15, "total": 1 }
}

POST /api/v1/lots/{lot}/bids write ability

Places a bid. Runs through ProxyBiddingService — identical logic to the web UI.

Same engine as the web UI. Verification, deposit checks, proxy-war resolution, bid-placed events, and outbound webhook triggers all fire identically for API-placed bids.

Enforcement chain

Lot and auction must be currently open for bidding
Bidder verification tier check (bid amount vs. tier limit)
Bid deposit registration check for the auction
User capability service check
Row-level lock to prevent concurrent bid races
Proxy war logic — automatically outbids existing proxy holders if your amount exceeds their max
Fires BidPlaced event → WebhookDispatchService::bidPlaced() → outbound partner webhooks

Request body

Field	Type	Required	Description
bid_amount	number	Yes	Bid amount in the auction's currency
is_proxy	boolean	No	Register as a max/proxy bid (default: false)

Example request

curl -X POST "https://bidyear.com/api/v1/lots/55/bids" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"bid_amount": 18500, "is_proxy": false}'

Response 200 — bid placed

{
  "success": true,
  "message": "Bid placed successfully",
  "data": {
    "id": 202,
    "amount": 18500.00,
    "is_proxy": false,
    "bidder": "You",
    "is_winning": true,
    "placed_at": "2026-07-12T09:15:00Z"
  }
}

Error responses

HTTP	code	Cause
401	unauthenticated	No or invalid token
403	insufficient_token_ability	Token lacks `write`
403	bidder_not_verified	Verification tier too low for this bid amount
403	deposit_required	Bid deposit not registered for this auction
422	bid_too_low	Amount does not exceed current bid + minimum increment
422	auction_closed	Lot/auction not open

POST /api/v1/lots/{lot}/watchlist write ability

Adds the lot to the authenticated user's watchlist. Idempotent.

Response 200

{ "success": true, "message": "Added to watchlist" }

DELETE /api/v1/lots/{lot}/watchlist write ability

Removes the lot from the authenticated user's watchlist. Idempotent.

Response 200

{ "success": true, "message": "Removed from watchlist" }