# Auctionzip — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and browse auction lots across the AuctionZip marketplace, view detailed lot information and complete auction catalogs, track historical prices realized, and discover auctioneers by name or location. Access auction schedules, item specifications, seller terms, and top-performing auctioneers.

**Category:** Marketplaces | **Website:** [auctionzip.com/](https://auctionzip.com/) | **Docs:** [parse.bot/marketplace/ecb92c6e-6f40-4bfa-bd80-1763391c4a7c/auctionzip-com-api](https://parse.bot/marketplace/ecb92c6e-6f40-4bfa-bd80-1763391c4a7c/auctionzip-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/auctionzip/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get auction catalog

Retrieve catalog metadata for a specific auction including title, event date, location, seller info, buyer premiums, and bid increments.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `catalog_ref` | string | Yes | The alphanumeric catalog reference, obtainable from get_lot_detail results via itemView.catalogRef |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/auctionzip/get-auction-catalog \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"catalog_ref":"<string>"}'
```

### Get auction details

Get terms, shipping, payment details, and bidding increments for an auction catalog. Complements get_auction_catalog with the full terms-of-sale text and fee structure.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `catalog_ref` | string | Yes | The alphanumeric catalog reference, obtainable from get_lot_detail results via itemView.catalogRef |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/auctionzip/get-auction-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"catalog_ref":"<string>"}'
```

### Get lot detail

Fetch full metadata for a single auction lot by its 10-character alphanumeric reference. Returns pricing, photos, estimates, condition, catalog reference, and bid status.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `lot_ref` | string | Yes | The unique 10-character alphanumeric lot reference, obtainable from search_lots results |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/auctionzip/get-lot-detail \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"lot_ref":"<string>"}'
```

### Get prices realized

Look up historical sold prices for items matching keywords. Returns up to 20 price records per request with item titles and final sale prices.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | integer | No | Category ID filter. 0 returns all categories. |
| `keywords` | string | Yes | Search keywords for historical price lookup |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/auctionzip/get-prices-realized \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<integer>","keywords":"<string>"}'
```

### Get top auctioneers

Retrieve this week top 10 most viewed auctioneers from AuctionZip, including rank, name, location, and phone number.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/auctionzip/get-top-auctioneers \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Search auctioneers

Search for auctioneers by company name or last name. Returns matching auctioneer names with profile URLs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Company name or last name keyword to search for |
| `zip` | string | No | ZIP code for proximity-based search |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/auctionzip/search-auctioneers \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>","zip":"<string>"}'
```

### Search auctions

Browse the auction calendar. Without a day parameter, returns a monthly calendar view showing auction counts per day. With a day parameter, returns a list of auctions scheduled for that specific day.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `day` | string | No | Day of month (1-31). When provided, returns list of auctions for that specific day instead of calendar view. |
| `keywords` | string | No | Search keywords to filter auctions |
| `month` | string | No | Month number (1-12). Omitting defaults to current month. |
| `year` | string | No | Four-digit year. Omitting defaults to current year. |
| `zip` | string | No | ZIP code for proximity-based search |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/auctionzip/search-auctions \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"day":"<string>","keywords":"<string>","month":"<string>","year":"<string>","zip":"<string>"}'
```

### Search lots

Full-text search over online bidding lots. Returns paginated results with lot references, titles, and URLs. Each lot_ref can be passed to get_lot_detail for full metadata.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for paginated results |
| `query` | string | Yes | Search keyword for lot titles |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/auctionzip/search-lots \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.