# eBay — 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 monitor eBay listings across any category, with support for active and completed/sold listings. Retrieve item details, pricing history, seller profiles and feedback, and category data. Filter by keyword, category, condition, seller, and sort order to support price research, market analysis, and inventory monitoring.

**Category:** Marketplaces | **Website:** [ebay.com/](https://ebay.com/) | **Docs:** [parse.bot/marketplace/55d0638c-d45f-4901-aa25-8da1810b1ffe/ebay-com-api](https://parse.bot/marketplace/55d0638c-d45f-4901-aa25-8da1810b1ffe/ebay-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/ebay/`
**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 categories

Retrieve the hierarchy of eBay categories with their IDs and URLs. Returns all top-level and sub-categories available on eBay's all-categories page.

**Estimated cost:** Metered

_No parameters required._

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

### Get completed sold listings

Search for completed and sold eBay listings to track historical prices. Combines the sold and complete filters on eBay search. Returns the same listing format as search_listings.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |
| `query` | string | Yes | Search keyword. |
| `sort` | string | No | Sort order code. |

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

### Get item details

Retrieve full details of a single eBay item by its item ID, including title, price, condition, seller info, images, and item specifics (key-value pairs describing item attributes).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `item_id` | string | Yes | eBay item ID (numeric string, e.g. '296129124843'). Obtainable from search_listings results. |

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

### Get search suggestions

Get autocomplete search suggestions for a query prefix. Returns keyword suggestions that eBay would display in the search dropdown.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search query prefix (e.g. 'laptop'). |

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

### Get seller active listings

Search all active listings from a specific seller. Returns the same listing format as search_listings, filtered to a single seller's inventory.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |
| `sort` | string | No | Sort order code. |
| `username` | string | Yes | Seller username (e.g. 'thrift.books'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/ebay/get-seller-active-listings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","sort":"<string>","username":"<string>"}'
```

### Get seller feedback

Retrieve paginated feedback and reviews for a seller, including individual feedback cards with ratings, comments, item details, and pagination metadata.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Results per page (25, 50, or 100). |
| `page` | integer | No | Page number for pagination. |
| `username` | string | Yes | Seller username (e.g. 'thrift.books'). |

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

### Get seller profile

Get summary ratings and profile information for a seller including feedback scores, detailed seller ratings (accuracy, shipping cost, shipping speed), member details, and positive feedback percentage.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `username` | string | Yes | Seller username (e.g. 'thrift.books'). |

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

### Search listings

Search for eBay listings with filters for category, seller, sold/completed status, and sorting. Returns paginated results with item titles, prices, conditions, and item IDs. Each page returns up to ~60 results from eBay's search results page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | No | eBay category ID to filter by (numeric string). |
| `complete` | boolean | No | Filter to completed listings only. |
| `graded` | boolean | No | Filter to graded items only. Appends Graded=Yes to the search, useful for Collectible Card Games (category 2536) and related categories. |
| `page` | integer | No | Page number for pagination. |
| `query` | string | No | Search keyword. At least one of query, seller, or category_id should be provided. |
| `seller` | string | No | Seller username to filter results to a specific seller's listings. |
| `sold` | boolean | No | Filter to sold items only. |
| `sort` | string | No | Sort order code. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/ebay/search-listings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","complete":"<boolean>","graded":"<boolean>","page":"<integer>","query":"<string>","seller":"<string>","sold":"<boolean>","sort":"<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.