# AuctionBotPro — Full API Reference

> Precision auction sniping API for ShopGoodwill.com. This document contains everything an AI agent needs to use the API.

## Base URL

`https://api.auctionbotpro.com`

## Authentication

Three methods supported (in priority order):

### 1. x402 Pay-Per-Call (No Account Required)

Send a request without any auth headers. The server returns HTTP 402 with an `X-PAYMENT-REQUIRED` header containing a Base64-encoded JSON object:

```json
{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "evm:8453",
    "maxAmountRequired": "10000",
    "payTo": "0x767131d92c41D56546eC72fecD0F1d63900fa9D9",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "description": "Search ShopGoodwill listings"
  }]
}
```

Sign a USDC TransferWithAuthorization (EIP-3009) for the required amount, then retry the request with an `X-PAYMENT` header containing the Base64-encoded payment payload. The server verifies via the Coinbase facilitator and returns the result.

### 2. API Key

```
X-API-Key: your-api-key
```

### 3. Bearer Token (Session)

```
Authorization: Bearer <session-token>
```

---

## Endpoints

### POST /api/search

Search ShopGoodwill listings.

**x402 price:** $0.01

**Request body:**
```json
{
  "searchText": "vintage lamp",
  "categoryId": 0,
  "lowPrice": 1,
  "highPrice": 100,
  "sortColumn": 1,
  "sortOrder": 0,
  "page": 1,
  "pageSize": 40
}
```

Only `searchText` is required. Returns `searchResults.items` array with `itemId`, `title`, `currentPrice`, `endTime`, `imageUrl`, `bidCount`.

---

### GET /api/snipes/item/{itemId}

Get full item details from ShopGoodwill.

**x402 price:** $0.01

**Path params:** `itemId` (integer) — ShopGoodwill item ID

**Response:** `{ item: { title, currentPrice, minimumBid, endTime, imageServer, imageUrlString, description, sellerId, ... } }`

---

### POST /api/snipes/shipping

Calculate shipping cost for an item.

**x402 price:** $0.01

**Request body:**
```json
{
  "itemId": 123456,
  "zipCode": "90210"
}
```

`zipCode` is optional if the user has a saved zip code.

---

### POST /api/snipes

Create a snipe — an automated bid that fires in the final seconds of an auction.

**x402 price:** $1.00

**Request body:**
```json
{
  "itemId": 123456,
  "maxBid": 25.50,
  "secondsBefore": 10
}
```

- `itemId` (required): ShopGoodwill item ID
- `maxBid` (required): Maximum bid in USD. ShopGoodwill uses proxy bidding — you may win for less.
- `secondsBefore` (optional, default 10): How many seconds before auction end to fire the bid. Range: 3-120.

**Response (201):**
```json
{
  "ok": true,
  "snipe": {
    "id": "uuid",
    "itemId": 123456,
    "itemTitle": "Vintage Lamp",
    "maxBid": 25.50,
    "auctionEnd": "2025-03-15T22:00:00.000Z",
    "snipeAt": "2025-03-15T21:59:50.000Z",
    "secondsBefore": 10,
    "status": "sleeping",
    "workflowId": "uuid"
  }
}
```

---

### GET /api/snipes

List all snipes.

**x402 price:** $0.01

**Query params:** `status` (optional) — filter by: sleeping, scheduled, bidding, bid_placed, outbid, error, cancelled

**Response:** `{ snipes: [...] }`

---

### GET /api/snipes/{id}

Get detail for a specific snipe.

**x402 price:** $0.01

**Response:** `{ snipe: {...}, workflowStatus: {...} }`

---

### PATCH /api/snipes/{id}

Update max bid or timing for an existing snipe.

**x402 price:** $0.01

**Request body:**
```json
{
  "maxBid": 30.00,
  "secondsBefore": 5
}
```

Both fields are optional. Re-launches the workflow with new settings.

---

### DELETE /api/snipes/{id}

Cancel a snipe. Refunds 1 credit if cancelled before bid fires.

**x402 price:** $0.01

---

### POST /api/snipes/test-bid

Place an immediate bid (no scheduling).

**x402 price:** $0.50

**Request body:**
```json
{
  "itemId": 123456,
  "bidAmount": 15.00
}
```

---

### GET /api/history

List bid history with results.

**x402 price:** $0.01

**Response:** `{ history: [{ itemId, bidAmount, currentPriceAtBid, success, responseBody, createdAt }] }`

---

### POST /api/research

Research resale prices across eBay, Mercari, Poshmark, and Amazon.

**x402 price:** $0.25

**Request body:**
```json
{
  "query": "vintage brass lamp"
}
```

**Response includes:**
- `stats`: { count, min, max, median, mean, stdDev }
- `verdict`: great_deal | good_deal | fair | overpriced
- `estimatedProfit`: after 13% platform fees + $10 shipping
- `listings`: array of found listings with prices and sources

---

### GET /api/credits/balance

Check credit balance (authenticated users only, not available via x402).

**Response:**
```json
{
  "balance": 8,
  "totalPurchased": 10,
  "totalUsed": 2,
  "isUnlimited": false
}
```

---

### GET /api/status

Dashboard stats (authenticated users only).

---

## Snipe Lifecycle

`pending` → `scheduled` → `sleeping` → `bidding` → `bid_placed` / `outbid` / `error` / `cancelled`

The bot uses Cloudflare Durable Workflows with `step.sleepUntil()` for precision timing. While sleeping, it costs nothing. Prices are updated every 15 minutes via cron.

## Error Responses

All errors return JSON: `{ "error": "message" }`

- `400` — Bad request (missing params, invalid values)
- `401` — Unauthorized (no valid auth)
- `402` — Payment required (x402 payment needed, or insufficient credits)
- `403` — Forbidden (banned account)
- `404` — Not found
- `500` — Server error

## Rate Limits

No explicit rate limits, but ShopGoodwill API calls are proxied and subject to their own limits. The platform uses random delays and proxy rotation to maintain access.