# Buyee — 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 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. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-buyee-jp-api-76805420/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## 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.paywithlocus.com/api/wrapped/parse-buyee-jp-api-76805420/get_mercari_item \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-buyee-jp-api-76805420/get_yahoo_auction_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-buyee-jp-api-76805420/get_yahoo_auction_item \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-buyee-jp-api-76805420/search_all_platforms \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-buyee-jp-api-76805420/search_mercari_japan \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-buyee-jp-api-76805420/search_seller_profiles \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-buyee-jp-api-76805420/search_yahoo_auctions \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```