ja-normalize

x402-ja-api

将日语文本“结构化”并返回的 API 集合。AI Agent 通过 x402 协议按次支付 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 的日元价格、中位数・偏差、美元参考价、USD/JPY、日元溢价（相对美元的偏差率）。缓存 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":"令和５年４月１日 ＴＥＬ ０３－１２３４－５６７８"}'

包含付款的端到端测试（需要测试网和单独的买家钱包）：

# 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。Gas 费由 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）