tx402

tx402

x402 on Algorand を利用した、従量課金 API として提供される Algorand トランザクションの平易な解説です。

ライブサービス：

https://tx402-production.up.railway.app

1 件のトランザクション、アトミックグループの各トランザクション、複数 ID の一括処理、またはアカウントの最近のアクティビティを解説します。レスポンスには、換算済みの金額、内部トランザクション、アセット名、手数料、タイムスタンプ、取引相手、ソースで検証されたプロトコルラベルが含まれます。

ウォレットなしで、無料の固定トランザクションデモをお試しください：

https://tx402-production.up.railway.app/demo?example=algo

GET /explain?txid=YRSG7IKDPCK4XMKFFTFFFYMIHF6SJOMHUOIE4FFUWNLEQ4WG2ZOQ

支払い後のレスポンス例：

{
  "txid": "YRSG7IKDPCK4XMKFFTFFFYMIHF6SJOMHUOIE4FFUWNLEQ4WG2ZOQ",
  "network": "mainnet",
  "summary": "On June 16, 2019, wallet VCINCV...JPMIPM sent 1 ALGO to CRBMB5...QLXZOY. Paid 0.001 ALGO in fees.",
  "details": {
    "type": "pay",
    "sender": "VCINCVUX2DBKQ6WP63NOGPEAQAYGHGSGQX7TSH4M5LI5NBPVAGIHJPMIPM",
    "transfer": {
      "amount": "1",
      "assetId": 0,
      "unit": "ALGO"
    }
  }
}

生の Algorand インデクサー JSON は、帳簿処理を行う機械向けに最適化されています。金額は基本単位で、アセットは数値 ID、メモは base64 形式です。tx402 は、トランザクションを人に説明する必要があるエージェントやアプリケーション向けの翻訳レイヤーです。

API

公開ルート：

• GET / - サービスメタデータへのリンクを含むランディングページ
• GET /health - プロセスの稼働状況
• GET /health?deep=1&network=mainnet - 上流サービスのレディネスチェック
• GET /discovery - 機械可読なサービス説明と料金メタデータ
• GET /openapi.json - OpenAPI 3.1 仕様
• GET /.well-known/agent.json - エージェントマーケットプレイスのマニフェスト
• GET /.well-known/x402 - x402 リソースマニフェスト
• GET /llms.txt - エージェントが読み取れるドキュメント
• GET /demo?example=algo|usdc - 無料の許可リスト登録済み Mainnet サンプル
• GET /explain?txid=...&network=mainnet - 有料のトランザクション解説
• GET /group?txid=...&network=mainnet - 有料のアトミックグループ解説
• POST /batch - 1～10 件のトランザクション ID の有料一括処理
• GET /account/activity?address=...&limit=25 - 有料のアクティビティ概要
• GET /analytics - 無料の集計済み導入状況カウンター

デフォルト料金は、/explain が $0.005、/group が $0.01、/batch が $0.02、/account/activity が $0.01 です。本番環境では Mainnet USDC を受け付けます：

• network: algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=
• asset: 31566704
• receiver: 6RK3U3OF2B4Q773L4KC7OVFHQGU5I74NHRZ36QN6CVF527CKXAL62YR754

アーキテクチャ

tx402 は、小規模で決定論的なコアと薄いサービス提供シェルで構成されています。

コア：

• src/decoder.js は、生の Algorand インデクサー JSON を正規化されたトランザクションオブジェクトに変換します。
• src/narrator.js は、正規化されたオブジェクトを読みやすい 1 文に変換します。
• src/insights.js は、グループおよびアカウントレベルの概要を作成します。
• src/explainer.js は、アセットを解決し、単一、グループ、一括、アカウント向けの各機能を統括します。
• src/knownApps.js は、既知のアプリ ID とアセット ID を人にわかりやすいラベルに対応付け、説明されるプロトコルに関する主張ごとに検証ソースを示します。

サービス提供シェル：

• src/index.js は、HTTP ルート、ミドルウェアの順序、ロギング、レート制限、ヘルスチェック、グレースフルシャットダウンを管理します。
• src/indexer.js は、AlgoNode の公開インデクサーと通信する唯一のモジュールです。
• src/payments.js は、x402 の料金と受取先を宣言し、検証と決済をホスト型の GoPlausible ファシリテーターに委任します。
• src/rateLimit.js は、メモリ内の IP 単位のレートリミッターを提供します。
• src/analytics.js は、Cookie、生のウォレットアドレス、クエリ文字列、IP 履歴を保持せずに、プロセス内の集計済み導入状況カウンターを保持します。

サーバーが秘密鍵を保存することはありません。購入者の署名はクライアント側で行われます。リソースサーバーは料金を提示して支払いを検証し、プロダクトルートからのレスポンスが成功した後にのみ、ファシリテーターを通じて決済します。

ローカルでの実行

npm install
npm start
npm test

ローカルのエンドポイント：

curl "http://localhost:4021/health"
curl "http://localhost:4021/discovery"
curl "http://localhost:4021/explain?txid=SOME_REAL_MAINNET_TXID"
curl "http://localhost:4021/group?txid=SOME_REAL_MAINNET_TXID"

アプリは .env が存在する場合、それを読み込みます。標準以外のアセットが必要な場合を除き、USDC_ASSET_ID は設定しないでください。コードは NETWORK から正規の USDC アセットを導出します。

クライアントの例

読み取り専用のクライアント例：

npm run example:client
npm run example:catalog

デフォルトのクライアントは、資金を使わずに検出メタデータと x402 の支払い要求を表示します。支払いを行うには、資金を入金した購入者ウォレットを設定し、TX402_EXAMPLE_PAY=1 と CONFIRM_MAINNET_PAYMENT=1 を設定してください。

OpenAPI：

• openapi.json
• https://tx402-production.up.railway.app/openapi.json

エージェントマーケットプレイスのメタデータ：

• https://tx402-production.up.railway.app/.well-known/agent.json
• https://tx402-production.up.railway.app/.well-known/x402
• https://tx402-production.up.railway.app/llms.txt

コピーして貼り付けるだけで使えるインテグレーションと配布用アセット：

• インテグレーションガイド
• 配布チェックリスト
• GoPlausible MCP の提案
• アウトリーチキット

有料ルートでは、入力／出力スキーマ、サービスメタデータ、リクエスト例を含む標準の x402 Bazaar 拡張も宣言します。ファシリテーターは、決済が正常に完了した後にこのメタデータをインデックス化できます。

MCP ラッパー：

npm run mcp

公開 npm パッケージの公開後は、エージェントはこのリポジトリをクローンせずにインストールできます。

npx tx402-mcp

デフォルトでは、MCP ラッパーは読み取り専用で、有料呼び出しに対して x402 の支払い要件を返します。ローカルウォレットから支払えるようにするには、TX402_MCP_ENABLE_PAYMENTS=1 と CONFIRM_MAINNET_PAYMENT=1 を設定してください。

6 段階の導入ロードマップは、PLAN.md で管理されています。

提出用アセット

• ピッチデック
• デモ動画のスクリプト

セキュリティに関する注意事項

• 出力文字列には、アセット名やメモなど、信頼できないオンチェーンデータが含まれることがあります。JSON 出力は JSON として安全ですが、HTML をレンダリングするコンシューマーはエスケープする必要があります。
• 無効な txid 入力は、インデクサーへのアクセスおよび支払いの前に拒否されます。
• 支払いは、応答が成功した後にのみ確定します。
• すべての製品ルート、/analytics、/discovery、および詳細なヘルスチェックにはレート制限が適用されます。
• プロトコル名／アプリ名は、verified: true とマークされている場合にのみ、事実として示されます。
• アプリケーションログには、クエリー文字列とクライアント IP アドレスは含まれません。

ステータス

• フェーズ 1 - コア解説、無料、ローカル
• フェーズ 2 - Testnet での x402 支払いミドルウェア、エンドツーエンドで検証済み
• フェーズ 3 - HTTPS での一般公開
• フェーズ 4 - Mainnet の支払い設定
• フェーズ 5 - 初回の実 Mainnet 決済
• フェーズ 6 - クライアント例、OpenAPI 仕様、オプションの MCP ラッパー

初回の Mainnet 決済：

• txid：XA7HMRPUV4X2GWI4AAGUT5FKAVTNCQJ5ZMUNTVTBKG3GZMES27LA
• 金額：0.005000 USDC

メンテナー向けメモ

実装手順書、デプロイコマンド、各フェーズの証跡、運用上の注意事項は CLAUDE.md に記載されています。