# Buyee — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.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 retrieve item listings across Japanese marketplaces — including Yahoo Auctions Japan and Mercari Japan — via the Buyee proxy shopping service. Browse products, check prices, and fetch item details across multiple platforms in one place.

**Category:** Marketplaces | **Website:** [buyee.jp/](https://buyee.jp/) | **Docs:** [parse.bot/marketplace/76805420-f7c6-4ae1-afb8-34ed98e52d29/buyee-jp-api](https://parse.bot/marketplace/76805420-f7c6-4ae1-afb8-34ed98e52d29/buyee-jp-api)

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

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/buyee/`
**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 mercari item

Get details of a specific Mercari Japan item via Buyee including title, price, images, item condition details, seller info, and description. The item_id can be obtained from search_mercari_japan results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `item_id` | string | Yes | Mercari Japan item ID (e.g. 'm93085015562') |

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

### Get yahoo auction categories

Get the shop list for Buyee's Any-to-Buyee service, organized by category (General products, Fashion, Toys & Games, etc.). Each category contains shops with names, descriptions, and URLs. Useful for discovering available marketplaces.

**Estimated cost:** Metered

_No parameters required._

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

### Get yahoo auction item

Get details of a specific JDirectItems Auction (formerly Yahoo! Auction Japan) item including title, images, price information, item condition details, time remaining, and description HTML. The item_id can be obtained from search_yahoo_auctions results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `item_id` | string | Yes | Yahoo Auctions Japan item ID (e.g. 'd1232761048', 'x1234567890') |

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

### Search all platforms

Cross-platform search across multiple Japanese marketplaces (Yahoo Auctions, Mercari, Rakuma, etc.) simultaneously. Returns structured results with item details, prices, and platform information. Paginates internally per-platform; the limit controls how many results are returned per platform in a single call.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum results per platform |
| `query` | string | Yes | Search keyword (e.g. 'pokemon', 'nintendo') |

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

### Search mercari japan

Search for items on Mercari Japan via Buyee. Returns paginated results with item titles, prices, and images. Each page returns up to ~97 items.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `keyword` | string | Yes | Search keyword |
| `page` | integer | No | Page number for pagination (1-based) |

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

### Search seller profiles

Search for seller profiles across Yahoo Auctions (JDirectItems) and Mercari Japan via Buyee. Accepts a keyword and returns seller profile details including name, ID, platform, profile URL, rating, and review count. Searches items matching the keyword via cross-platform search, then extracts unique seller profiles from the item detail pages. Each result requires one additional page fetch per seller, so response time scales with limit. Returns up to 10 sellers.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of seller profiles to return (1-10) |
| `query` | string | Yes | Search keyword to find sellers (matches items whose sellers are then profiled) |

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

### Search yahoo auctions

Search for items on JDirectItems Auction (formerly Yahoo! Auctions Japan) via Buyee. Returns paginated HTML-parsed results with item titles, prices, bids, and time remaining. Each page returns up to ~50 items.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination (1-based) |
| `query` | string | Yes | Search keyword |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/buyee/search-yahoo-auctions \
  -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://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.