Torify API Docs

Overview

Torify handles Japan-specific data that AI agents routinely need but cannot reliably compute on their own: era-calendar conversion (Meiji through Reiwa), invoice number validation against the NTA registry, corporate lookup by legal entity number, postal-code address resolution, Japanese name parsing and romanization, bank-code lookup, and more.

All 36 endpoints return structured JSON with optional confidence scores so your agent knows how authoritative each answer is. No Japanese locale knowledge required on your side — just call the API and parse the result.

Three access methods are available, depending on your use case:

MCP — plug-and-play with Claude Desktop or Claude Code, free tier included.
x402 — pay per call in USDC on Base L2, no subscription needed.
API Key — monthly flat-rate plan for production workloads.

Note: Discovery endpoints (/health, /openapi.json, /llms.txt, /.well-known/*) are always free and require no authentication. All /v1/* endpoints require one of the three methods below in production.

Quick Start

MCP (Free) x402 (per-call) API Key (monthly)

Option A: MCP — Free tier, zero setup

Add the Torify MCP server to Claude Desktop or Claude Code CLI. No API key, no wallet, no signup required.

Claude Desktop — edit ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "torify": {
      "transport": {
        "type": "http",
        "url": "https://torify-mcp.torify.workers.dev"
      }
    }
  }
}

Claude Code CLI:

claude mcp add torify --transport http https://torify-mcp.torify.workers.dev

Then just ask Claude naturally:

"Convert 2019-05-01 to Japanese era"
"Is 2026-01-01 a Japanese public holiday?"
"Look up postal code 1000001"

Claude will call Torify automatically and return a structured answer. Free tier: 100 requests/day/IP.

Option B: x402 — Pay per call ($0.02/call USDC on Base L2)

Call any /v1/* endpoint without a subscription. The server returns HTTP 402 with payment instructions; you sign and retry with an X-PAYMENT header. Compatible wallets: Coinbase CDP, any EIP-1193 wallet on Base.

Step 1 — Call the endpoint, receive the 402 payment instructions:

curl 'https://torify.dev/v1/wareki/convert?direction=g2w&date=2019-05-01'

# HTTP 402 response:
{
  "x402Version": 1,
  "error": "Payment required",
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "0.02",
    "asset": "USDC",
    "payTo": "0x...",
    "extra": { "name": "Torify Japanese Era Conversion" }
  }]
}

Step 2+3 — Pay and call in one shot using the x402-fetch TypeScript SDK:

import { wrapFetchWithPayment } from 'x402-fetch';
import { createWalletClient } from 'viem';
// ... configure your Base wallet

const fetch402 = wrapFetchWithPayment(fetch, wallet);

const res = await fetch402(
  'https://torify.dev/v1/wareki/convert?direction=g2w&date=2019-05-01'
);
const data = await res.json();
// { ok: true, data: { era: "令和", eraYear: 1, ... } }

wrapFetchWithPayment handles the 402 flow automatically: it reads the accepts array, signs a micropayment on Base, and retries the request with the X-PAYMENT header.

Option C: API Key — Monthly flat rate

Best for production agents with predictable call volumes. Pass your key in the X-API-Key header.

curl -H "X-API-Key: YOUR_KEY"   'https://torify.dev/v1/wareki/convert?direction=g2w&date=2019-05-01'

Plans:

Plan	Price	Requests
Pro	$49/mo	Unlimited (fair use)
Enterprise	$499/mo	Unlimited + priority support + SLA

To get a key, email contact@torify.dev with your intended use case.

Authentication

Method	How	Limit	Price
MCP	Claude Desktop / Claude Code — no headers needed	100 req/day/IP	Free
x402	`X-PAYMENT` header (USDC on Base L2)	Unlimited	$0.02/call
API Key	`X-API-Key: YOUR_KEY` header	Per plan	$49/mo or $499/mo

Free endpoints (no auth required): /health, /openapi.json, /llms.txt, /.well-known/agent.json, /v1/invoice/validate/bulk. All other /v1/* endpoints require authentication in production.

Endpoints

Examples below omit authentication headers for brevity. Add your chosen auth method from the Quick Start section.

Era & Calendar

GET /v1/wareki/convert

Convert between Gregorian and Japanese era (wareki). Supports Meiji / Taisho / Showa / Heisei / Reiwa.

Param	Type	Required	Description
`direction`	g2w \| w2g	Yes	Gregorian-to-wareki or wareki-to-Gregorian
`date`	YYYY-MM-DD	For g2w	Input date (Gregorian)
`era`	string	For w2g	Era name in kanji, e.g. 令和
`eraYear`	int	For w2g	Year within the era
`month`	int	No	Month (1–12)
`day`	int	No	Day (1–31)

curl 'https://torify.dev/v1/wareki/convert?direction=g2w&date=2019-05-01'

{
  "ok": true,
  "data": {
    "gregorian": "2019-05-01",
    "era": "令和",
    "eraYear": 1,
    "eraYearKanji": "元",
    "formatted": "令和元年5月1日"
  }
}

GET /v1/holiday/check

Check if a date is a Japanese public holiday. Covers fixed holidays, Happy Monday rules, and substitute holidays (振替休日).

Param	Type	Required	Description
`date`	YYYY-MM-DD	Yes*	Date to check
`year`	YYYY	Yes*	Return full holiday list for the year

* Provide either date or year.

curl 'https://torify.dev/v1/holiday/check?date=2026-01-01'

{
  "ok": true,
  "data": {
    "date": "2026-01-01",
    "isHoliday": true,
    "name": "元日",
    "type": "fixed"
  }
}

GET /v1/age/calculate

Calculate age, school year, and era-based age from a birthdate. Handles the Japanese April 1 school-year entry rule correctly.

Param	Type	Required	Description
`birthdate`	YYYY-MM-DD	Yes	Date of birth
`asOf`	YYYY-MM-DD	No	Reference date (defaults to today)

curl 'https://torify.dev/v1/age/calculate?birthdate=1990-04-02'

{
  "ok": true,
  "data": {
    "age": 36,
    "schoolYear": "昭和65年度生→平成3年度入学",
    "eraAge": "昭和65年生まれ"
  }
}

Invoice & Tax

GET /v1/invoice/validate

Validate invoice number format and check digit locally — instant, no external API call. Format: "T" followed by 13 digits.

Param	Type	Required	Description
`number`	string	Yes	Invoice number (T + 13 digits)

curl 'https://torify.dev/v1/invoice/validate?number=T8010401050783'

{
  "ok": true,
  "data": {
    "valid": true,
    "normalized": "T8010401050783",
    "houjinBangou": "8010401050783"
  }
}

GET /v1/invoice/verify

Verify invoice number existence against the NTA (National Tax Agency) public registry (インボイス公表サイト). Returns a confidence score and registrant name.

Param	Type	Required	Description
`number`	string	Yes	Invoice number (T + 13 digits)

curl 'https://torify.dev/v1/invoice/verify?number=T8010401050783'

{
  "ok": true,
  "data": {
    "registered": true,
    "confidence": 0.99,
    "verified_at": "2026-05-08T00:00:00Z",
    "registrantName": "○○株式会社",
    "source": "nta_invoice_kohyo"
  },
  "meta": {
    "disclaimer": "Data from NTA public registry; may lag by 1 business day."
  }
}

POST /v1/invoice/validate/bulk FREE

Validate up to 100 invoice numbers in one request. Format-only check (no NTA lookup). No payment required.

Body field	Type	Required	Description
`numbers`	string[]	Yes	Array of invoice numbers (max 100)

curl -X POST https://torify.dev/v1/invoice/validate/bulk   -H 'Content-Type: application/json'   -d '{"numbers":["T8010401050783","T1234567890123"]}'

GET /v1/tax/calculate

Calculate Japanese consumption tax. Supports standard rate (10%) and reduced rate (8%), with configurable rounding.

Param	Type	Required	Description
`amount`	number	Yes	Pre-tax amount in JPY
`rate`	standard \| reduced	No	Tax rate (default: standard)
`rounding`	floor \| ceil \| round	No	Rounding method (default: floor)

curl 'https://torify.dev/v1/tax/calculate?amount=1000&rate=standard'

{
  "ok": true,
  "data": {
    "amount": 1000,
    "tax": 100,
    "total": 1100,
    "rate": 0.1,
    "rateLabel": "標準税率"
  }
}

POST /v1/eltax/check

Electronic bookkeeping compliance checklist (電子帳簿保存法). Returns the required fields and retention rules for a given document type. POST with JSON body (not GET).

Body field	Type	Required	Description
`type`	invoice \| receipt \| contract \| other	Yes	Document type
`format`	pdf \| jpeg \| png \| xml \| tiff \| other	No	File format (optional)

curl -X POST 'https://torify.dev/v1/eltax/check'   -H 'Content-Type: application/json'   -d '{"type":"invoice","format":"pdf"}'

Corporate & Business

GET /v1/houjin/lookup

Look up company information by 13-digit corporate number (法人番号) via the NTA registry. Returns legal name, registered address, active/inactive status, and confidence score.

Param	Type	Required	Description
`number`	string	Yes	13-digit corporate number

curl 'https://torify.dev/v1/houjin/lookup?number=8010401050783'

{
  "ok": true,
  "data": {
    "number": "8010401050783",
    "name": "○○株式会社",
    "address": "東京都千代田区...",
    "status": "active",
    "confidence": 0.99,
    "verified_at": "2026-05-08T00:00:00Z"
  }
}

GET /v1/industry/lookup

Look up industry classification by JSIC code (Japan Standard Industrial Classification Rev.14). Returns Japanese and English descriptions at major, medium, and minor levels.

Param	Type	Required	Description
`code`	string	Yes	JSIC code, e.g. G55

curl 'https://torify.dev/v1/industry/lookup?code=G55'

Address & Location

GET /v1/postal/lookup

Look up address components by 7-digit Japanese postal code (郵便番号). Returns prefecture, city, and town name.

Param	Type	Required	Description
`zipcode`	string	Yes	7-digit code or NNN-NNNN format
`all`	boolean	No	Return all matching towns when ambiguous

curl 'https://torify.dev/v1/postal/lookup?zipcode=1000001'

{
  "ok": true,
  "data": {
    "zipcode": "1000001",
    "prefecture": "東京都",
    "city": "千代田区",
    "town": "千代田"
  }
}

GET /v1/address/normalize

Parse and normalize a Japanese address string into structured components: prefecture, city, district, block, building.

Param	Type	Required	Description
`address`	string	Yes	Raw Japanese address string

curl 'https://torify.dev/v1/address/normalize?address=東京都千代田区千代田1-1'

GET /v1/region/lookup

Look up prefecture or municipality by JIS X 0402 code. Pass a 2-digit code for prefecture or 5-digit code for municipality.

Param	Type	Required	Description
`code`	string	Yes	2-digit prefecture or 5-digit municipality code

curl 'https://torify.dev/v1/region/lookup?code=13'

GET /v1/coordinate/convert

Convert coordinates between WGS84 (GPS standard) and JGD2011 (Japanese Geodetic Datum 2011). Offset is approximately 0.4″ — significant for precision mapping.

Param	Type	Required	Description
`lat`	float	Yes	Latitude in decimal degrees
`lng`	float	Yes	Longitude in decimal degrees
`direction`	wgs2jgd \| jgd2wgs	Yes	Conversion direction

curl 'https://torify.dev/v1/coordinate/convert?lat=35.6895&lng=139.6917&direction=wgs2jgd'

Name & Text

GET /v1/name/romanize

Romanize a Japanese name from kana to Modified Hepburn (passport-style, all caps).

Param	Type	Required	Description
`name`	string (kana)	Yes	Name in hiragana or katakana
`order`	family-first \| given-first	No	Word order (default: family-first)

curl 'https://torify.dev/v1/name/romanize?name=すずき%20いちろう'

{
  "ok": true,
  "data": {
    "romaji": "SUZUKI ICHIRO",
    "order": "family-first"
  }
}

GET /v1/name/split

Split a Japanese full name into family and given name. Uses space boundary, a 100-surname dictionary, or positional heuristic, in that priority order.

Param	Type	Required	Description
`name`	string	Yes	Full name in kanji or kana

curl 'https://torify.dev/v1/name/split?name=山田太郎'

{
  "ok": true,
  "data": {
    "original": "山田太郎",
    "family": "山田",
    "given": "太郎",
    "confidence": 0.85,
    "method": "dictionary"
  }
}

GET /v1/name/validate

Validate a Japanese name against the approved kanji list for personal names (人名用漢字 — Ministry of Justice list). Returns invalid characters if any are found.

Param	Type	Required	Description
`name`	string	Yes	Name to validate

curl 'https://torify.dev/v1/name/validate?name=山田太郎'

GET /v1/kana/convert

Convert between hiragana, katakana, and half-width katakana (半角カナ).

Param	Type	Required	Description
`text`	string	Yes	Input text
`to`	katakana \| hiragana \| half-katakana	Yes	Target script

curl 'https://torify.dev/v1/kana/convert?text=アイウエオ&to=hiragana'

{
  "ok": true,
  "data": {
    "original": "アイウエオ",
    "converted": "あいうえお",
    "from": "katakana",
    "to": "hiragana"
  }
}

GET /v1/text/normalize

Normalize Japanese text: NFKC Unicode normalization, full-width ASCII to half-width, or half-width ASCII to full-width (for form-field compatibility).

Param	Type	Required	Description
`text`	string	Yes	Input text
`mode`	nfkc \| ascii-narrow \| ascii-wide	Yes	Normalization mode

curl 'https://torify.dev/v1/text/normalize?text=ＡＢＣＤ&mode=ascii-narrow'

GET /v1/kanji/to-kana

Convert kanji text to kana reading via Yahoo! Japan Language Processing API. Requires YAHOO_APP_ID to be configured on the server.

Param	Type	Required	Description
`text`	string	Yes	Input text containing kanji
`output`	hiragana \| katakana	No	Output script (default: hiragana)

curl 'https://torify.dev/v1/kanji/to-kana?text=東京都'

POST /v1/kanji/normalize

Normalize non-standard kanji and variant characters (異体字) to standard JIS forms. Removes IVS (Ideographic Variation Selector) sequences and converts 300+ old-form characters (旧字体) to their modern equivalents (新字体). POST with JSON body (not GET).

Body field	Type	Required	Description
`text`	string	Yes	Text containing variant kanji

curl -X POST 'https://torify.dev/v1/kanji/normalize'   -H 'Content-Type: application/json'   -d '{"text":"髙橋"}'

Finance & Payment

GET /v1/bank/lookup

Look up bank name and kana by Zengin bank code (全銀協コード, 4 digits). Optionally resolve a 3-digit branch code.

Param	Type	Required	Description
`bankCode`	string	Yes	4-digit Zengin bank code
`branchCode`	string	No	3-digit branch code

curl 'https://torify.dev/v1/bank/lookup?bankCode=0001&branchCode=001'

{
  "ok": true,
  "data": {
    "bankCode": "0001",
    "bankName": "みずほ銀行",
    "bankNameEn": "Mizuho Bank",
    "bankKana": "ミズホ",
    "branchCode": "001",
    "branchName": "東京営業部",
    "branchKana": "トウキヨウエイギヨウブ",
    "found": true,
    "branchFound": true
  }
}

GET /v1/bank/search

Search Japanese financial institutions or their branches by partial name (kanji / kana / romaji). When bankCode is omitted, searches across all 1,150+ banks. When set, searches only that bank's branches.

Param	Type	Required	Description
`name`	string	Yes	Partial name (1-50 chars, case-insensitive)
`bankCode`	string	No	4-digit bank code (enables branch-mode search)
`limit`	integer	No	Max hits (1-100, default 20)

curl 'https://torify.dev/v1/bank/search?name=みずほ'

{
  "ok": true,
  "data": {
    "query": "みずほ",
    "mode": "bank",
    "hits": [
      { "bankCode": "0001", "bankName": "みずほ銀行", "bankKana": "ミズホ", "matchedField": "bankName" },
      { "bankCode": "0288", "bankName": "みずほ信託銀行", "bankKana": "ミズホシンタク", "matchedField": "bankName" }
    ],
    "total": 2,
    "truncated": false
  }
}

GET /v1/bank/list

List all Japanese financial institutions (~1,150 banks including credit unions and JA banks) with code, name, kana, romaji, and branch count. Paginated.

Param	Type	Required	Description
`offset`	integer	No	Pagination offset (default 0)
`limit`	integer	No	Page size (1-500, default 200)

curl 'https://torify.dev/v1/bank/list?limit=5'

{
  "ok": true,
  "data": {
    "total": 1152,
    "banks": [
      { "code": "0001", "name": "みずほ銀行", "kana": "ミズホ", "roma": "mizuho", "branchCount": 467 }
    ]
  }
}

GET /v1/bank/transfer/validate

Validate Japanese bank transfer details in Zengin format. Also handles Japan Post (ゆうちょ銀行) account numbers.

Param	Type	Required	Description
`bankCode`	string	Yes	4-digit Zengin bank code
`branchCode`	string	No	3-digit branch code
`accountType`	普通 \| 当座 \| 貯蓄	Yes	Account type in Japanese
`accountNumber`	string	Yes	Account number (up to 7 digits)

curl 'https://torify.dev/v1/bank/transfer/validate?bankCode=0001&branchCode=001&accountType=普通&accountNumber=1234567'

GET /v1/yucho/convert

Convert a Japan Post (ゆうちょ銀行) account symbol/number pair to the standard Zengin bank transfer format required for wire transfers.

Param	Type	Required	Description
`kigo`	string	Yes	5-digit account symbol (記号)
`bango`	string	Yes	8-digit account number (番号)

curl 'https://torify.dev/v1/yucho/convert?kigo=10010&bango=12345671'

GET /v1/payment/3ds/check

Determine 3D Secure 2.0 requirement based on MCC (Merchant Category Code) and BIN range. Useful for Japanese card processing compliance.

Param	Type	Required	Description
`merchantCategory`	string	Yes	4-digit Merchant Category Code
`binNumber`	string	Yes	6-digit card BIN (Bank Identification Number)

curl 'https://torify.dev/v1/payment/3ds/check?merchantCategory=5411&binNumber=411111'

Identity & Compliance

GET /v1/mynumber/validate

Validate Individual Number (マイナンバー) format and Verhoeff check digit. The number is never stored or echoed in the response.

Param	Type	Required	Description
`number`	string	Yes	12-digit Individual Number

curl 'https://torify.dev/v1/mynumber/validate?number=123456789012'

GET /v1/passport/validate

Validate Japanese passport number format (2 uppercase letters + 7 digits).

Param	Type	Required	Description
`number`	string	Yes	Passport number string

curl 'https://torify.dev/v1/passport/validate?number=AB1234567'

GET /v1/license/validate

Validate Japanese driver's license number format (12 digits with prefecture and year-of-issue encoding).

Param	Type	Required	Description
`number`	string	Yes	12-digit license number

curl 'https://torify.dev/v1/license/validate?number=123456789012'

GET /v1/insurance/validate

Validate Japanese social insurance number format. The number is not included in the response for privacy.

Param	Type	Required	Description
`number`	string	Yes	Social insurance number

curl 'https://torify.dev/v1/insurance/validate?number=12345678901'

GET /v1/plate/validate

Validate a Japanese vehicle license plate or VIN (Vehicle Identification Number).

Param	Type	Required	Description
`plate`	string	Yes	License plate string or VIN

curl 'https://torify.dev/v1/plate/validate?plate=品川500あ1234'

GET /v1/barcode/validate

Validate a JAN barcode (EAN-13) or ISBN-13 check digit.

Param	Type	Required	Description
`code`	string	Yes	13-digit JAN / EAN-13 / ISBN-13 barcode

curl 'https://torify.dev/v1/barcode/validate?code=4901234567894'

GET /v1/phone/validate

Validate and normalize a Japanese phone number to E.164 format (+81...). Accepts hyphenated, parenthesized, and plain digit formats.

Param	Type	Required	Description
`phone`	string	Yes	Phone number in any common format

curl 'https://torify.dev/v1/phone/validate?phone=03-1234-5678'

{
  "ok": true,
  "data": {
    "input": "03-1234-5678",
    "e164": "+81312345678",
    "areaCode": "03",
    "type": "fixed"
  }
}

Response Format

All endpoints wrap their payload in a consistent ApiResponse<T> envelope, making it easy to write generic error handling in your agent.

Success

{
  "ok": true,
  "data": {
    // endpoint-specific fields
  },
  "meta": {
    "source": "nta_invoice_kohyo",
    "note": "Data refreshed daily at 09:00 JST."
  }
}

Error

{
  "ok": false,
  "error": {
    "code": "MISSING_PARAM",
    "message": "Query parameter 'number' is required."
  }
}

Confidence Scores

Some endpoints include a confidence field (0–1) so your agent can decide how much weight to place on the result:

0.99

Verified against an official source (NTA, Japan Post, etc.)

0.85

Dictionary match (high confidence, not live-verified)

0.50

Heuristic / uncertain — human review recommended

0.00

Mock / placeholder — not found in any source

Errors

HTTP Status	Error Code	Meaning
`400`	`MISSING_PARAM`	A required query parameter is absent
`400`	`INVALID_FORMAT`	Input value does not match the expected format
`402`	—	Payment required — see x402 response body for `accepts` array
`429`	—	Rate limit exceeded (MCP free tier: 100 req/day/IP)
`502`	`UPSTREAM_ERROR`	External API (NTA, Yahoo! JLP, Japan Post) unreachable or timed out

Retry guidance: 502 errors are transient — retry with exponential backoff (start at 1 s, cap at 30 s). 429 errors reset after 24 hours for the MCP free tier; upgrade to x402 or API Key for unlimited access.

Contact & Support

Questions, enterprise pricing, or custom integrations: contact@torify.dev

OpenAPI spec (machine-readable): /openapi.json
LLM-readable capabilities: /llms.txt
Agent discovery: /.well-known/agent.json

Listed on

x402scan · Smithery · Glama · MCP.so · Anthropic MCP Registry

Torify API Docs

Overview

Quick Start

Option A: MCP — Free tier, zero setup

Option B: x402 — Pay per call ($0.02/call USDC on Base L2)

Option C: API Key — Monthly flat rate

Authentication

Endpoints

Era & Calendar

Invoice & Tax

Corporate & Business

Address & Location

Name & Text

Finance & Payment

Identity & Compliance

Response Format

Success

Error

Confidence Scores

Errors

Contact & Support

Listed on

Legal