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 42 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.

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

Free Trial — 100 REST API calls/month with email signup (no wallet, no credit card). Use POST /v1/trial/signup to get an X-Trial-Key.
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

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

Option A: Free Trial — 100 calls/month, no credit card

Step 1 — Get your trial key:

curl -X POST https://torify.dev/v1/trial/signup   -H "Content-Type: application/json"   -d '{"email": "you@example.com", "consent": true}'

# Response:
# {
#   "ok": true,
#   "data": {
#     "trialKey": "torify_trial_xxxx...",
#     "email": "you@example.com",
#     "monthlyLimit": 100,
#     "message": "Trial key sent to your email."
#   }
# }

Step 2 — Use the trial key:

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

# { "ok": true, "data": { "era": "令和", "eraYear": 6, ... } }

Remaining calls are returned in the X-Trial-Remaining response header. Resets on the 1st of each month.

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	$19/mo	10,000 calls/month
Enterprise	$149/mo	1,000,000 calls/month (Fair Use) + priority support + SLA

Subscribe self-serve on Polar: Get Pro API Key →. For Enterprise or custom plans, email contact@torify.dev.

Authentication

Method	How	Limit	Price
Free Trial	`X-Trial-Key: YOUR_KEY` header — get key via `POST /v1/trial/signup`	100 calls/month	Free
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	$19/mo or $149/mo

Free endpoints (no auth required): /health, /openapi.json, /llms.txt, /.well-known/agent.json, /v1/wareki/convert/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年生まれ"
  }
}

GET /v1/legal-holiday/check

Determine whether a date is a statutory holiday (法定休日) under Labor Standards Act Article 35, and calculate the applicable overtime premium rate (35% for statutory / 25% for non-statutory rest days).

Param	Type	Required	Description
`date`	YYYY-MM-DD	Yes	Date to check
`restDays`	CSV of sun/mon/tue/wed/thu/fri/sat	No	Designated rest day(s) per work rules (default: `sun`)

curl 'https://torify.dev/v1/legal-holiday/check?date=2026-01-04&restDays=sun,sat'   -H 'X-Trial-Key: trial_YOUR_KEY'

{
  "ok": true,
  "data": {
    "date": "2026-01-04",
    "dayOfWeek": "sun",
    "dayOfWeekJa": "日",
    "isLegalHoliday": true,
    "restDays": ["sun", "sat"],
    "overtimePremiumRate": 0.35,
    "overtimePremiumRateDescription": "Overtime premium rate for statutory holiday work (Labor Standards Act Article 37)",
    "legalReference": "Labor Standards Act Article 35 (労働基準法第35条)"
  }
}

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=T7000012050002'

{
  "ok": true,
  "data": {
    "valid": true,
    "normalized": "T7000012050002",
    "houjinBangou": "7000012050002"
  }
}

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=T7000012050002'

{
  "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."
  }
}

GET /v1/invoice/company-profile Composite

Composite endpoint. One call returns invoice registration status + corporate details. T-number (T + 13 digits) → invoice registration check (NTA 適格請求書 API) plus corporate name, address, and kind (NTA 法人番号 API). Ideal for invoice processing AI agents that extract T-numbers from OCR and need to validate both compliance and company identity in one step. Note: government agencies (e.g. NTA) may return registered: false — this is correct per Japanese tax law.

Param	Type	Required	Description
`number`	string	Yes	T-number (T + 13 digits, e.g. T1180301018771)

curl 'https://torify.dev/v1/invoice/company-profile?number=T1180301018771'   -H 'X-Trial-Key: trial_YOUR_KEY'

{
  "ok": true,
  "data": {
    "invoiceNumber": "T1180301018771",
    "registered": true,
    "confidence": 0.99,
    "registrantName": "トヨタ自動車株式会社",
    "registrantAddress": "愛知県豊田市トヨタ町１番地",
    "registrationDate": "2023-10-01",
    "cancelDate": null,
    "houjin": {
      "houjinBangou": "1180301018771",
      "name": "トヨタ自動車株式会社",
      "address": { "full": "愛知県豊田市トヨタ町１番地" },
      "status": "active"
    },
    "sources": ["nta-invoice-kohyo", "nta-houjin-bangou"]
  }
}

POST /v1/invoice/validate/bulk TRIAL

Validate up to 100 invoice numbers in one request. Format-only check (no NTA lookup). Requires Trial key (1 call/month free) or x402 payment ($0.50/req). Authentication required to comply with NTA terms prohibiting mass data collection.

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":["T7000012050002","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
`category`	standard \| reduced \| food \| alcohol \| luxury	No	Tax category (default: standard)
`rounding`	floor \| ceil \| round	No	Rounding method (default: floor)
`taxIncluded`	boolean	No	If true, amount is tax-inclusive (default: false)

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

{
  "ok": true,
  "data": {
    "amount": 1000,
    "category": "standard",
    "taxRate": 0.1,
    "taxAmount": 100,
    "total": 1100,
    "taxIncluded": false,
    "basePrice": 1000
  }
}

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
`documentType`	invoice \| receipt \| contract \| other	Yes	Document type
`transaction.date`	string	No	Transaction date (ISO 8601)
`transaction.amountJpy`	number	No	Transaction amount in JPY
`transaction.counterpartyName`	string	No	Counterparty name
`storage.fileFormat`	pdf \| jpeg \| png \| xml \| tiff \| other	No	Storage file format
`storage.hasTimestamp`	boolean	No	Timestamp applied
`storage.hasAccessControl`	boolean	No	Tamper-prevention system in place
`storage.searchableByDate`	boolean	No	Searchable by date
`storage.searchableByAmount`	boolean	No	Searchable by amount
`storage.searchableByCounterparty`	boolean	No	Searchable by counterparty

curl -X POST 'https://torify.dev/v1/eltax/check'   -H 'Content-Type: application/json'   -d '{
    "documentType": "invoice",
    "transaction": { "date": "2024-04-01", "amountJpy": 110000, "counterpartyName": "株式会社ABC" },
    "storage": { "fileFormat": "pdf", "hasTimestamp": true, "hasAccessControl": false,
                 "searchableByDate": true, "searchableByAmount": true, "searchableByCounterparty": true }
  }'

{
  "ok": true,
  "data": {
    "overallResult": "pass",
    "complianceStatus": "compliant",
    "checks": [
      { "item": "取引年月日の記録", "itemEn": "Transaction date recorded", "result": "pass", "required": true },
      { "item": "取引金額の記録", "itemEn": "Transaction amount recorded", "result": "pass", "required": true }
    ],
    "applicableLaw": "電子帳簿保存法第7条（電子取引の保存義務）・規則第4条第1項",
    "note": "This is a reference checklist only. Consult a tax professional (税理士) for compliance decisions.",
    "noteEn": "Reference checklist only. Consult a qualified tax professional for compliance decisions.",
    "referenceDate": "2024-01-01"
  }
}

GET /v1/law/search

Search Japanese law titles via the e-Gov 法令 API v2 (政府標準利用規約・no API key required). Returns law ID, law number, official title, kana reading, and promulgation date.

Param	Type	Required	Description
`title`	string	Yes	Law title keyword (partial match), e.g. 労働基準法
`limit`	int 1–50	No	Max results to return (default: 10)

curl 'https://torify.dev/v1/law/search?title=%E5%8A%B4%E5%83%8D%E5%9F%BA%E6%BA%96%E6%B3%95&limit=3'   -H 'X-Trial-Key: trial_YOUR_KEY'

{
  "ok": true,
  "data": {
    "total": 1,
    "count": 1,
    "laws": [
      {
        "lawId": "322AC0000000049",
        "lawNumber": "昭和22年法律第49号",
        "title": "労働基準法",
        "titleKana": "ろうどうきじゅんほう",
        "abbrev": "労基法",
        "promulgationDate": "1947-04-07"
      }
    ],
    "source": "egov-hourei-api"
  }
}

POST /v1/invoice/verify/bulk

Batch-verify up to 300 Japan qualified invoice T-numbers against the NTA public registry (インボイス公表サイト Web-API). Returns registrant name, address, and status per number, plus an aggregate summary. Results are cached 24h per T-number.

Body field	Type	Required	Description
`numbers`	string[]	Yes	Array of T-prefixed 13-digit invoice numbers (max 300)

curl -X POST https://torify.dev/v1/invoice/verify/bulk   -H 'Content-Type: application/json'   -H 'X-Trial-Key: trial_YOUR_KEY'   -d '{"numbers":["T1180301018771","T1010001067912"]}'

{
  "ok": true,
  "data": {
    "total": 2,
    "results": [
      { "number": "T1180301018771", "registered": true, "registrantName": "トヨタ自動車株式会社", "source": "nta-invoice-kohyo" },
      { "number": "T1010001067912", "registered": true, "registrantName": "株式会社NTTドコモ", "source": "cache" }
    ],
    "summary": { "registered_count": 2, "unregistered_count": 0, "invalid_count": 0 }
  }
}

POST /v1/freelance/order/validate

Validate a freelance work order against Japan's Freelance Act (フリーランス・事業者間取引適正化等法, effective 2024-11-01). Checks all 7 mandatory disclosure items and returns violation / warning details.

Body field	Type	Required	Description
`order`	object	Yes	Order object — see fields below
`order.description`	string	Yes	Work description (業務内容)
`order.amount`	number	Yes	Fee amount (報酬の額)
`order.paymentDueDays`	number	Yes	Payment due days from delivery (60 days max recommended)
`order.deliveryDate`	YYYY-MM-DD	Yes	Delivery deadline (納期)
`order.deliveryLocation`	string	Yes	Delivery method / location
`order.paymentMethod`	string	Yes	Payment method (支払方法)

curl -X POST https://torify.dev/v1/freelance/order/validate   -H 'Content-Type: application/json'   -H 'X-Trial-Key: trial_YOUR_KEY'   -d '{"order":{"description":"Webデザイン","amount":500000,"paymentDueDays":30,"deliveryDate":"2026-06-30","deliveryLocation":"メール納品","paymentMethod":"銀行振込"}}'

{
  "ok": true,
  "data": {
    "compliant": true,
    "checks": [{ "item": "業務内容", "status": "ok" }],
    "violations": [],
    "warnings": [],
    "missing": [],
    "summary": "compliant"
  }
}

POST /v1/tax/calculate/bulk

Calculate Japanese consumption tax for up to 1,000 line items in a single POST. Supports 10% (standard) and 8% (reduced) rates, exclusive and inclusive modes. Returns per-item breakdown and totals grouped by rate.

Body field	Type	Required	Description
`items`	object[]	Yes	Array of line items (max 1000)
`items[].amount`	number	Yes	Item amount in JPY
`items[].rate`	8 \| 10	Yes	Tax rate (%)
`items[].type`	exclusive \| inclusive	Yes	Tax-exclusive or tax-inclusive amount

curl -X POST https://torify.dev/v1/tax/calculate/bulk   -H 'Content-Type: application/json'   -H 'X-Trial-Key: trial_YOUR_KEY'   -d '{"items":[{"amount":1000,"rate":10,"type":"exclusive"},{"amount":540,"rate":8,"type":"inclusive"}]}'

{
  "ok": true,
  "data": {
    "total": 2,
    "results": [
      { "amount": 1000, "rate": 10, "type": "exclusive", "tax": 100, "totalWithTax": 1100, "amountExcludingTax": 1000 },
      { "amount": 540, "rate": 8, "type": "inclusive", "tax": 40, "totalWithTax": 540, "amountExcludingTax": 500 }
    ],
    "summary": { "totalAmount": 1540, "totalTax": 140, "totalWithTax": 1640, "totalExcludingTax": 1500, "by_rate": { "10": { "count": 1, "totalAmount": 1000, "totalTax": 100 }, "8": { "count": 1, "totalAmount": 540, "totalTax": 40 } } }
  }
}

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=7000012050002'

{
  "ok": true,
  "data": {
    "number": "7000012050002",
    "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'

GET /v1/company/full-profile Composite

Composite endpoint. One call returns company identity + optional invoice registration status. 13-digit corporate number → name, address, kind, status (NTA 法人番号 API) plus optional T-number invoice check (NTA 適格請求書 API). Use for B2B onboarding, KYC, or AP validation in a single API call instead of calling /v1/houjin/lookup + /v1/invoice/verify separately. Note: government agencies often return invoiceStatus.registered: false — this is correct per Japanese tax law.

Param	Type	Required	Description
`number`	string	Yes	13-digit corporate number (法人番号)
`verify_invoice`	true \| false	No	Also verify T-number invoice registration (default: false)

curl 'https://torify.dev/v1/company/full-profile?number=1180301018771&verify_invoice=true'   -H 'X-Trial-Key: trial_YOUR_KEY'

{
  "ok": true,
  "data": {
    "houjinBangou": "1180301018771",
    "name": "トヨタ自動車株式会社",
    "address": { "full": "愛知県豊田市トヨタ町１番地", "prefecture": "愛知県", "prefectureEn": "Aichi" },
    "status": "active",
    "invoiceStatus": { "registered": true, "registrantName": "トヨタ自動車株式会社", "registrationDate": "2023-10-01" },
    "confidence": 0.99,
    "verified_at": "2026-05-30T00:00:00Z",
    "sources": ["nta-houjin-bangou", "nta-invoice-kohyo"]
  }
}

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": "100-0001",
    "prefecture": "東京都",
    "prefectureKana": "トウキョウト",
    "prefectureEn": "Tokyo",
    "city": "千代田区",
    "cityKana": "チヨダク",
    "cityEn": "Chiyoda",
    "town": "千代田",
    "townKana": "チヨダ",
    "townEn": "Chiyoda",
    "full": "東京都千代田区千代田",
    "source": "zipcloud"
  }
}

GET /v1/address/normalize

Parse and normalize a Japanese address string into structured components: prefecture, city, town, streetNumber, and v0.3.0 new fields: addressType (block / street / rural / other), streetRef (Kyoto street intersection & direction), and addressee (様方 / 気付 / c/o extraction).

Param	Type	Required	Description
`address`	string	Yes	Raw Japanese address string (max 200 chars)

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

{
  "ok": true,
  "data": {
    "original": "東京都千代田区千代田1-1",
    "prefecture": "東京都",
    "prefectureEn": "Tokyo",
    "city": "千代田区",
    "cityEn": "Chiyoda-ku",
    "town": "千代田1-1",
    "normalized": "東京都千代田区千代田1-1",
    "source": "geolonia",
    "streetNumber": "1-1",
    "streetNumberHyphen": "1-1",
    "streetNumberFormal": "1丁目1番地",
    "level": 3,
    "point": null,
    "engine": "geolonia",
    "addressType": "block",
    "streetRef": null,
    "addressee": null
  }
}

v0.3.0 new fields: addressType — classification of the address structure (block: 丁目/番地/号, street: Kyoto 通り名 with 上る/下る/東入/西入, rural: 大字/字, other: unclassified). streetRef — for Kyoto street addresses: { intersection: string, direction: "上る"|"下る"|"東入"|"西入"|null } or null. addressee — extracted name from 様方 / 気付 / c/o patterns, or null.

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'

GET /v1/geo/geocode

Convert a Japanese address string to latitude/longitude coordinates using the 国土地理院 AddressSearch API (PDL 1.0 license, commercial use allowed).

Param	Type	Required	Description
`q`	string (max 200 chars)	Yes	Address string, e.g. 東京都千代田区千代田1-1

curl 'https://torify.dev/v1/geo/geocode?q=%E6%9D%B1%E4%BA%AC%E9%A7%85'   -H 'X-Trial-Key: trial_YOUR_KEY'

{
  "ok": true,
  "data": {
    "lat": 35.681236,
    "lng": 139.767125,
    "title": "東京駅",
    "addressCode": "131010001",
    "source": "gsi-japan"
  },
  "meta": { "cached": false, "source": "gsi-japan" }
}

GET /v1/geo/reverse-geocode

Convert latitude/longitude to municipality name and municipal code using the 国土地理院 reverse-geocoder API. Coordinates must be within Japan (lon: 122–154, lat: 20–46).

Param	Type	Required	Description
`lon`	float	Yes	Longitude in decimal degrees (122–154)
`lat`	float	Yes	Latitude in decimal degrees (20–46)

curl 'https://torify.dev/v1/geo/reverse-geocode?lon=139.767125&lat=35.681236'   -H 'X-Trial-Key: trial_YOUR_KEY'

{
  "ok": true,
  "data": {
    "muniCode": "13101",
    "town": "千代田",
    "source": "gsi-japan"
  },
  "meta": { "cached": false, "source": "gsi-japan" }
}

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 using Cloudflare Workers AI (Llama 3.3 70B inference). No external API key required.

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 (新字体). Supports both GET (query params) and POST (JSON body).

Param / Body field	Type	Required	Description
`text`	string	Yes	Text containing variant kanji (query for GET, body for POST)
`direction`	old-to-new \| new-to-old	No	Conversion direction (default: old-to-new)

curl 'https://torify.dev/v1/kanji/normalize?text=亞&direction=old-to-new'

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

{
  "ok": true,
  "data": {
    "original": "亞",
    "normalized": "亜",
    "changes": [{ "position": 0, "from": "亞", "to": "亜", "type": "kyujitai", "typeEn": "Kyujitai to Shinjitai conversion (old to new character form)" }],
    "changeCount": 1,
    "descriptionEn": "Normalizes kanji characters: removes IVS variation selectors, applies NFC for CJK compatibility ideographs, and optionally converts Kyujitai (old forms) to Shinjitai (new standard forms) or vice versa.",
    "note": "Kyujitai mapping is based on Joyo Kanji table (2010). Not a legally authoritative conversion."
  }
}

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	Yes	3-digit branch code
`accountType`	1 \| 2 \| 4	Yes	Account type: 1=普通(Ordinary), 2=当座(Current), 4=貯蓄(Savings). Aliases: ordinary/futsu/普通, current/toza/当座, savings/chochiku/貯蓄
`accountNumber`	string	Yes	Account number (1-7 digits)

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

{
  "ok": true,
  "data": {
    "valid": true,
    "bankCode": "0001",
    "branchCode": "001",
    "accountType": "1",
    "accountTypeName": "普通",
    "accountTypeNameEn": "Ordinary (Futsu)",
    "accountNumber": "1234567",
    "isYucho": false,
    "disclaimer": "形式検証のみ。口座の実在性・名義は確認していません。振込前に人間が必ず最終確認すること。",
    "disclaimerEn": "Format validation only. Account existence and ownership are NOT verified. Human verification required before transfer."
  }
}

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'

{
  "ok": true,
  "data": {
    "binPrefix": "411111",
    "cardBrand": "Visa",
    "mcc": "5411",
    "mccName": "食料品店",
    "requiresThreeDS2": false,
    "note": "Compliance assessment based on MCC category. Consult your acquirer for actual requirements."
  }
}

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/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"
  }
}

GET /v1/school-code/validate

Validate and decompose a 13-character Japanese school code (文部科学省学校コード) as defined by MEXT. Checks format, school type, establishment type, prefecture, and Luhn-style check digit.

Param	Type	Required	Description
`code`	string (13 chars)	Yes	School code, e.g. B213123456800. Full-width characters are auto-normalized.

curl 'https://torify.dev/v1/school-code/validate?code=B213123456800'   -H 'X-Trial-Key: trial_YOUR_KEY'

{
  "ok": true,
  "data": {
    "code": "B213123456800",
    "valid": true,
    "schoolType": "elementary",
    "schoolTypeJa": "小学校",
    "schoolTypeEn": "Elementary School",
    "establishment": "public_municipal",
    "establishmentJa": "市町村立",
    "establishmentEn": "Municipal Public",
    "prefectureCode": "13",
    "prefectureJa": "東京都",
    "schoolNumber": "123456",
    "checkDigit": "8",
    "checkDigitValid": true,
    "serialNumber": "00"
  }
}

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, 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 Pro / Enterprise plans for higher 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

Try in Swagger Editor (live OpenAPI test)

Listed on

x402scan · Smithery · MCP.so · Anthropic MCP Registry