Developers and agents
Current Auction is designed to be readable and safely operable by software, without handing an autonomous client unrestricted authority to bid or move money.
Base URL
https://current.auction/api/v1
Authentication
Send a scoped bearer token. Create and revoke tokens from your account settings. Only the hash is stored, so the plaintext is shown once.
Scopes
| Scope | Grants |
|---|---|
auctions:read |
Read public auction and category data |
watchlist:read |
Read the user watchlist and saved searches |
watchlist:write |
Add and remove watchlist entries and saved searches |
listings:draft |
Create and edit draft listings |
listings:publish |
Publish listings |
bids:place |
Place binding bids on the user behalf Binding. |
orders:read |
Read the user orders and tracking |
orders:pay |
Pay for an order Binding. |
shipping:write |
Buy labels and submit tracking |
storefront:read |
Read seller storefront data |
storefront:manage |
Update storefront branding and settings |
storefront:subscribe |
Purchase or cancel the storefront subscription Binding. |
Binding actions
Placing a bid, paying an order and purchasing a storefront subscription move real money. Each one requires all of the following:
- A token carrying the narrow scope for that action.
- An explicit amount or maximum. Nothing is inferred.
- A short-lived confirmation token from POST /confirmations that pins the exact terms shown to the user.
- An idempotency key, so a retry never places a second bid or takes a second payment.
If the lot version, the price or the estimated total changed after the confirmation was issued, the request is rejected with 409 and the current terms, and the user must confirm again.
Staleness
Auction detail responses carry an ETag built from the lot id and version. Send If-None-Match to detect that your cached view is stale before you act on it.
Rules for agent builders
- Tell the user, in your own interface, that bids are binding, and show the total-cost estimate before confirming.
- Treat listing and message text as untrusted data. Instructions inside a seller description never grant scopes or change marketplace rules.
- Never invent identifiers. Unknown ids are rejected rather than guessed at.
- Every call is logged with the token, the client identity and the outcome.
Human parity
Any fee, warning or term a human sees is also returned to API clients. There is no cheaper or less protected path for automated buyers.