# BookWalker — 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 Japanese ebooks including manga and light novels on BookWalker Japan, with access to book details, rankings, category listings, and autocomplete suggestions. Discover new titles through curated rankings and explore the full catalog by category.

**Category:** Marketplaces | **Website:** [bookwalker.jp/](https://bookwalker.jp/) | **Docs:** [parse.bot/marketplace/e897c34e-7b41-4e4a-ad67-62da650668ef/bookwalker-jp-api](https://parse.bot/marketplace/e897c34e-7b41-4e4a-ad67-62da650668ef/bookwalker-jp-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/bookwalker/`
**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

### Autocomplete

Retrieve search suggestions from BookWalker's autocomplete API. Returns up to 10 matching series and book titles with their type, series/item ID, and category. Useful for validating search terms before a full search.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `term` | string | Yes | Search term for autocomplete suggestions. |

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

### Get book details

Fetch full metadata for a single book by its UUID. Returns structured details including title, authors, publisher, price, rating, description, category, series information, and cover image URL. The UUID is found in search results or ranking entries.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `uuid` | string | Yes | Book UUID (from search_books or get_rankings results). |

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

### Get category books

Browse books on a category landing page. Returns multiple named sections (e.g. new releases, rankings, recommended) each containing a list of books. Sections vary by category and are curated by the site.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | Yes | Category page slug. |

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

### Get rankings

Retrieve ranked book lists by time period and category. Returns up to ~50 books ordered by sales rank. Supports daily, weekly, and monthly periods across genre categories. Each entry includes rank position, title, author, price, rating, and cover image.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Category for rankings. Accepts 'total' for overall, category codes like 'ct2' (manga), 'ct3' (light novel), 'ct1' (literature), or name aliases: 'manga', 'lightnovel', 'novel', 'literature', 'practical'. |
| `period` | string | No | Ranking period: 'daily', 'weekly', or 'monthly'. |

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

### Search books

Full-text search over BookWalker's catalog. Returns paginated book results matching the query keyword. Results include series-level entries with price ranges when applicable. Pagination via page number; each page returns up to ~20 results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Category filter code passed as 'ct' parameter to the site search (e.g. 'ct2' for manga). |
| `order` | string | No | Sort order for results. |
| `page` | integer | No | Page number for pagination. |
| `query` | string | Yes | Search keyword (Japanese or English). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/bookwalker/search-books \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","order":"<string>","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.