io.github.KojimaHyui01/ja-normalize

x402-ja-api

日本語テキストを「構造化」して返すAPI群。AIエージェントが x402 プロトコルで1コールごとにUSDCを払って使う。

Endpoint	価格	何をするか
GET /v1/holidays?country=DE&year=2026&region=BY	$0.005	200カ国以上の祝日（州・地域別、英語名＋現地名、振替フラグ）。date-holidays データ
GET /v1/business-day?country=SA&date=&add=	$0.005	任意の国の営業日計算（その国の週末＝金土/金/土 も考慮）
GET /v1/holidays/countries[?country=US]	無料	対応国一覧／地域コード一覧
GET /v1/jp/crypto/ticker?symbol=BTC	$0.005	bitFlyer/Coincheck/GMO/bitbank のJPY価格、中央値・乖離、USD参照、USD/JPY、円プレミアム（対USD乖離率）。10秒キャッシュ
GET /v1/jp/holidays?year=2026	$0.005	国民の祝日一覧（振替休日・国民の休日込み、内閣府公式CSV、1955〜）
GET /v1/jp/business-day?date=&add=&calendar=	$0.005	営業日判定・N営業日後・月末営業日（calendar=bank で12/31〜1/3も休業扱い）
GET /v1/jp/bank/resolve?bank=&branch=	$0.02	銀行名・支店名の揺れ→金融機関コード・支店コード（候補＋確信度、全銀用半角カナ付き。zengin-code 1,146機関/29,000支店）
GET /v1/jp/bank/lookup?bankCode=&branchCode=	$0.005	コード→正式名・カナ・半角カナ・種別
GET /v1/jp/name/parse?name=&kana=	$0.02	姓名分割（辞書12k姓/76k名、分割99.7%）＋読み候補（確信度付き）＋パスポート式ローマ字。kana を渡せば決定的
GET /v1/jp/name/romaji?kana=	$0.005	かな→ヘボン式（外務省パスポート規則：長音省略・ン→M・促音・CH前T）＋OH式・マクロン・厳密表記
POST /v1/address/normalize	$0.02	住所の表記揺れを吸収し pref/city/town/addr + 緯度経度を返す（デジタル庁アドレス・ベース・レジストリ / Geolonia）
POST /v1/text/normalize	$0.01	全角→半角、和暦→ISO日付、電話番号(E.164)/郵便番号/メール抽出
POST /v1/company/resolve	$0.03	社名の揺れ→法人番号・正式商号・本店所在地・インボイス番号形式（国税庁 法人番号Web-API）

無料で読めるもの: GET / GET /health GET /openapi.json GET /.well-known/x402 GET /llms.txt GET /v1/holidays/countries

売上ダッシュボード（運営者専用 / STATS_TOKEN 必須）: https://x402-ja-api.onrender.com/stats — 累計受取USDC・件数・支払元数・日別・直近入金（オンチェーン、Blockscout）＋起動後のエンドポイント別 paid/free/402 カウンタ。?format=json で機械向け。

動かす

cp .env.example .env      # PAY_TO_ADDRESS を自分のウォレットに
npm install
npm run dev               # http://localhost:4021
npm run doctor            # 発見用ドキュメントと402応答の自己診断
npm run check             # 型チェック + テスト

未払いで叩くと 402 と PAYMENT-REQUIRED ヘッダ（base64 JSON）が返る:

curl -i -X POST localhost:4021/v1/text/normalize \
  -H 'Content-Type: application/json' \
  -d '{"text":"令和５年４月１日 ＴＥＬ ０３－１２３４－５６７８"}'

支払いを含むE2E（テストネット・買い手用の別ウォレットが必要）:

# Base Sepolia の USDC を https://faucet.circle.com で受け取っておく
BUYER_PRIVATE_KEY=0x... npm run probe -- http://localhost:4021 /v1/text/normalize

本番に出す手順

1. ウォレット: 受取専用のEVMアドレスを新規作成し PAY_TO_ADDRESS に設定（秘密鍵はサーバーに置かない。受け取るだけなので不要）
2. Coinbase CDP: https://portal.cdp.coinbase.com でAPIキーを発行 → CDP_API_KEY_ID / CDP_API_KEY_SECRET、X402_NETWORK=base （facilitator手数料: 1,000件まで無料、以降 $0.001/件。ガス代はfacilitator負担）
3. 法人番号API: https://www.houjin-bangou.nta.go.jp/webapi/ でアプリケーションIDを申請 → HOJIN_APP_ID 発行まで2〜4週間。届くまで /v1/company/resolve は 503 を返す
4. デプロイ: 恒久的なドメインが必須（x402scanはngrok等のトンネルを拒否）。Render / Fly.io / Railway の無料〜最小プランで十分。PUBLIC_BASE_URL を実URLに
5. 自己診断: npm run doctor -- https://your-domain
6. 登録（発見されるため）
   • x402scan: POST https://www.x402scan.com/api/x402/registry/register-origin {"origin":"https://your-domain"} または UI から
   • CDP Bazaar: 最初の決済が通ると自動索引（declareDiscoveryExtension 済み）
   • Circle Agent Marketplace: https://agents.circle.com/services の申請フォーム
   • x402Relay（日本）: https://x402relay.jp 系のカタログに申請

構成

src/
  config.ts            環境変数の検証（zod）。base 指定時は CDP キー必須
  lib/text.ts          純関数: 半角化 / 和暦 / 電話 / 郵便番号 / メール
  lib/address.ts       Geolonia 住所正規化のラッパー
  lib/csv.ts, hojin.ts 国税庁 Web-API v4 クライアント + CSV パーサ + チェックデジット
  lib/company.ts       名寄せ・ランキング
  lib/calendar.ts      日本の祝日・営業日計算（data/holidays.json を読む）
  lib/world-calendar.ts 世界の祝日・営業日（date-holidays、国別週末テーブル）
  lib/jpy-crypto.ts    国内取引所のJPY価格集約＋円プレミアム（公開API、部分失敗許容）
  lib/bank.ts          銀行・支店コード解決（zengin-code、表記揺れ・カナ・半角カナ）
  lib/romaji.ts        かな→ヘボン式ローマ字（パスポート規則）
  lib/name.ts          姓名分割・読み候補（data/names/dict.json）
  x402/catalog.ts      売り物の定義（価格・説明・スキーマ）= 唯一の正
  x402/server.ts       facilitator 選択・ルート設定・Bazaar 拡張
  routes/api.ts        有料ハンドラ（zod で入力検証）
  routes/discovery.ts  /openapi.json, /.well-known/x402, /health
  app.ts               Express 組み立て（テストは paywall:false / facilitator スタブ）
scripts/
  update-holidays.ts   内閣府CSV → data/holidays.json（年1回、翌年分が出る2月頃に実行）
  build-name-dict.ts   mecab-ipadic 人名 + MITデータセット → data/names/dict.json
  doctor.ts            デプロイ後の自己診断
  probe.ts             実際に払うクライアント

注意（法務・税務）

• USDC の受取自体に登録は不要。受け取った対価は円換算で雑所得、保有中の為替差損益も雑所得
• 法人番号データ利用時は「このサービスは国税庁法人番号システムWeb-API機能を利用して取得した情報をもとに作成しているが、サービスの内容は国税庁によって保証されたものではない」旨の表示が必要（/ のレスポンスに追加予定）
• 住所データは Geolonia（アドレス・ベース・レジストリ由来）。ライブラリの利用条件に従う
• 祝日データは内閣府「国民の祝日」CSV（政府標準利用規約 v2.0、出典明記）
• 世界の祝日は date-holidays（コードISC、データCC-BY-3.0、出典明記）
• 銀行・支店データは zengin-code（MIT、公開情報から自動収集）。npm update zengin-code で追従
• 人名辞書は mecab-ipadic（NAISTライセンス、data/names/IPADIC-COPYING.txt）と japanese-personal-name-dataset（MIT）由来

次にやること

• PAY_TO_ADDRESS を本物のウォレットに
• 法人番号 Web-API のアプリケーションID申請（リードタイムが一番長いので最初に）
• Render/Fly にデプロイ、doctor 通す
• x402scan / Circle / x402Relay に登録
• 死活監視（落ちたら通知）— 登録済みルートの79%が死んでいる市場なので、生きているだけで上位
• インボイス登録番号の有効性検証（国税庁 適格請求書発行事業者公表システム Web-API、別途ID申請）