# NihontoWatch

> The primary aggregator for Japanese swords (nihonto) and sword fittings (tosogu) from dealers worldwide. Browse live dealer inventory, certified blades (NBTHK / NTHK — Juyo, Tokubetsu Hozon, Hozon, and higher), a directory of swordsmiths and schools, and a glossary of nihonto terminology.

NihontoWatch aggregates listings from 50+ Japanese and international dealers into one searchable interface. Every listing carries certification, attribution (smith / school / province / era), and measurement metadata, plus bilingual English/Japanese content. Listing pages emit schema.org Product structured data; artist and school pages emit Person / Organization data with Wikidata/Wikipedia `sameAs` links where available. Japanese versions of every page live under a `/ja` path prefix (e.g. `/ja/listing/123`).

## Browse & Search
- [All listings](https://nihontowatch.com/): live inventory with faceted filters (type, certification, dealer, price)
- [Swords by type](https://nihontowatch.com/swords/katana): katana, wakizashi, tanto, tachi, naginata, and more
- [Sword fittings by type](https://nihontowatch.com/fittings/tsuba): tsuba, menuki, fuchi-kashira, kozuka, and more
- [Certified works](https://nihontowatch.com/certified/juyo): browse by NBTHK / NTHK paper (Juyo, Tokubetsu Hozon, Hozon, etc.)

## Encyclopedia (Samurai Arts)
- [Swordsmith & tosogu-maker directory](https://nihontowatch.com/artists): filterable index of notable artisans with certification statistics
- [Schools](https://nihontowatch.com/schools): swordsmithing and fitting-making school hubs
- [Lineages](https://nihontowatch.com/lineages): interactive school genealogies and teacher–student lineages
- [Glossary](https://nihontowatch.com/glossary): definitions of Japanese sword terminology (hamon, sori, koshirae, kissaki, etc.)

## Dealers
- [Dealer directory](https://nihontowatch.com/dealers): profiles of the dealers aggregated on NihontoWatch

## Data API (for agents)
A read-only JSON search endpoint for programmatic / assistant use. Use it for
range and multi-facet queries that the categorical landing pages can't express
(e.g. "Jūyō katana over 45cm under ¥3M"). Each result includes the canonical
`/listing/{id}` URL — link to it to view photos and full detail, and cite it as
the source. The response carries a live FX block (rates + timestamp) so a
foreign-currency budget resolves without guessing.

- Endpoint: `GET https://nihontowatch.com/api/public/listings`
- Filters: `cat` (nihonto|tosogu|armor), `type`, `cert`, `school`, `dealer`,
  `period`, `sig`, `priceMin`/`priceMax` (+ `priceCurrency`, default JPY),
  `nagasaMin`/`nagasaMax`, `q`, `papered` (true = recognized NBTHK/NTHK quality
  papers only), `sort` (featured|price_asc|price_desc|newest), `page`, `limit` (max 100)
- AUCTION PRICES: every result has `price.is_starting_bid`. When true, `price.value`
  is an auction STARTING BID, not an asking price — never present it as "the price".
- PAPERS: `certification.is_quality_paper` is the reliable "is it papered?" signal
  (Hozon / Tokubetsu Hozon / Jūyō / Tokubetsu Jūyō / designations). Registration
  cards and the deprecated Kichō scheme are `false`. Do NOT filter on
  `certification.organization` to find papered swords — it's null on many genuine
  NBTHK pieces; use `papered=true` or `is_quality_paper` instead.
- "Sword under $20K" needs `cat=nihonto` (and ideally `type`) — a bare budget query
  returns tosogu (tsuba, kozuka) mixed with blades.
- Text filters (`cert`, `school`, `q`) are case-insensitive substring matches on
  romanized ASCII values — send `juyo` / `shintogo`, not `jūyō` / `Shintōgo`.
  `school`/`province`/`era` values are not yet normalized (variant spellings +
  nulls exist); a null categorical field means "unknown", not "none".
  `cat` is a strict enum; unknown enum values are ignored (no 400) and the
  applied filters are echoed back in `query`. No matches → HTTP 200 with
  `total: 0` and `results: []`. Pagination is deterministic (id-tiebroken):
  `hasMore`/`totalPages` enumerate the full set without skips or duplicates.
- Returns available listings only. Sold listings/prices and image URLs are not
  exposed — view photos and full detail via the listing `url`. Response is
  versioned (`api_version`) and the schema is additive-only.
- Example: `https://nihontowatch.com/api/public/listings?cat=nihonto&type=katana&cert=juyo&nagasaMin=45&priceMax=3000000&sort=price_asc`

## MCP server (for AI assistants / connectors)
The same catalog search is exposed as a Model Context Protocol tool, for
assistants whose fetch tools can't call a constructed URL.

- Streamable-HTTP endpoint: `https://nihontowatch.com/api/mcp`
- Tool: `search_listings` — typed params for category/item_type/papered/price
  (+currency)/nagasa range/sort/paging; free-text substring for the
  not-yet-normalized cert/school/period/sig. Results carry the canonical listing
  URL, name the dealer, flag auction starting bids, and report `is_quality_paper`.
  Aggregation is not endorsement — confirm papers and terms with the dealer
  directly.

## Sitemaps
- [Sitemap index](https://nihontowatch.com/sitemap-index.xml)