new-x402-listings-feed

新着 x402 リスティングフィード

呼び出し元が指定した期間内に402index.ioへ新たに登録されたx402/L402サービスのフィードです。NEXUS 候補#8――手動ビルドであり、FORGEによる生成ではありません。候補#3 （agent-verification-api）、#4（url-metadata-api）、#6（document-conversion-api）と同じ、手動でCloud Runアセットを作成するパターンです。

• POST /new-x402-listings {"window_hours": 24, "protocol": null, "category": null, "payment_network": null} -- 期間内（1～168時間、デフォルトは24時間）に402index.ioへ登録されたサービスです。1回あたり$0.01です。
• /mcpのMCPツールget_new_x402_listings。同じパラメーターを使用します――現在は無料です。「既知の制限事項」を参照してください。
• GET /health、GET /.well-known/agent-card.json、GET /openapi.json（x-payment-infoを含みます）、 GET /.well-known/402index-verify.txt（402indexのクレーム検証ファイル）。

メインネットへの切り替え（2026-09-03）

当初はBase Sepoliaテストネット上で構築・測定しました。Baseメインネットへ切り替えました。x402の決済処理はCDPファシリテーターに移行しました（create_facilitator_config()。ws／live-entity-verification／erc8004-agent-liveness／onchain-activity-index／x402-receipt-verifierにすでに適用済みのものと同じ切り替えです）。 また、支払い先ウォレットをNEXUS_X402_PAYTO_ADDRESSに移行しました（フェイルファストの環境変数で、プレースホルダーのデフォルト値はありません。X402_WALLET_ADDRESSから名称を変更しました）。デプロイ前に、Cloud RunでCDP_API_KEY_ID／CDP_API_KEY_SECRETと NEXUS_X402_PAYTO_ADDRESSを設定する必要があります。

これは何か（何ではないか）

これは独自のデータではありません。 このアセットの基盤となる登録データは、402index.ioが提供する無料の公開ディレクトリです（https://402index.io/api-docs。認証不要、無料枠は100リクエスト／分）。誰でも無料で直接問い合わせできます。このアセットの価値はすべて、データのパッケージ化にあります。つまり、約96,000件以上のカタログをポーリングしてページネーションし、購入者がその作業をしなくて済むようにすること、鮮度を保つために402index独自の最新情報フィードを統合すること、重複を除去すること、そして呼び出し元が指定した期間／プロトコル／カテゴリ／決済ネットワークで絞り込むことです。この開示はREADMEだけに記載されているのではありません。製品自体にも組み込まれており、すべての応答に内容を明記したnoteフィールドが含まれ、エージェントカードのprotocol_noteでも同じことを繰り返しているため、購入者がわざわざ調べる必要はありません。

実現可能性の調査（2026-08-23、コード記述前）

タスク概要の前提では、前回のセッションで確認された402index.ioのサービス総数は「約7,595件」とされていました。このセッションの開始時に実行した実際の curl https://402index.io/api/v1/services?limit=5では、"total": 96093と表示されました。カタログはその確認以降、およそ12倍に増加しています。サンプルしたすべてのエントリーで、registered_atが実在し、値が設定されていることを確認しました。2つの上流の仕組みを実際に稼働中の状態で検証しました。それぞれに、タスク概要でも402indexのドキュメントでも十分に明らかにされていなかった、実際の制限があります。

1. GET /api/v1/services（ページネーション対応。limit／offsetを指定、1ページあたり最大200件）には、日付によるソートや日付範囲のフィルターがありません。sortで指定できるのはname／price／latency／uptime／reliabilityのみです（/api-docsで直接確認済み）。 期間指定のクエリーに応えるには、カタログ全体を走査してクライアント側でフィルタリングするしかありません。サーバー側でより効率的に処理する方法はありません。実際の現在の規模では約481ページに及び、「約7,595件」という数字から想定される約40ページではありません。
2. **GET /feed.xml?type=new**は実在し、RSS 2.0形式で、すでにpubDate順に並んでいます。また、402indexが自ら公開しているレート制限の対象外リストにも含まれています。ただし、件数は固定上限に制限されています。このセッション中に実際に取得したところ、ちょうど90件が返され、対象期間は約3時間分でした。ドキュメントにはtype=newが「過去7日間に追加されたサービス」と記載されています。現在の登録ペースでは、このフィードだけで7日間（またはピーク時には24時間）の期間を網羅することはできません。

どちらの情報源も、単独では製品が掲げる期間範囲を誠実に満たせません。判断：両方を使って進めます。 組み合わせ方については、main.pyのモジュールのdocstringと、以下の「アーキテクチャ」を参照してください。これは、CLAUDE.md SS3が求める、現行データにおける実際の不一致を黙って見過ごして実装を進めるのではなく、明らかにするためのものです。そのため、この記録はチャットの記録だけでなく、ここにも残しています。

アーキテクチャ

• バックグラウンドの asyncio タスクが（起動をブロックせず、FastAPI の lifespan で開始され）、NEXUS_CATALOG_REFRESH_SECONDS ごと（デフォルトは 600 秒／10 分）に /api/v1/services カタログ全体を走査します。リクエスト間隔は 0.65 秒で、持続的なリクエスト数は約 92 件／分です（402index の無料プラン上限である 100 件／分を下回る安全マージンを確保）。結果はサービス ID をキーとしてメモリ内（_catalog_cache）にキャッシュされます。現在のカタログ規模では、全体の走査に約 481 ページ／約 5.2 分かかりますが、これはすべてバックグラウンドタスクのコストであり、購入者のリクエスト内で実行されることはありません。
• 購入者からのリクエストごとに、さらに /feed.xml?type=new をリアルタイムで取得します（レート制限の対象外で、約 1 リクエストと低コスト）。これをバックグラウンド走査でキャッシュされた内容にマージし、直近の走査完了後に登録されたデータも取り込みます。ID が競合した場合はキャッシュのエントリーを優先し（より多くのフィールドを含むため）、フィードのエントリーは不足分の補完にのみ使用します。
• マージしたデータからレスポンスをフィルタリング、重複排除、並べ替え（新しい順）し、最大 500 件に制限します。

単純な TTL キャッシュを採用しなかった理由（タスク概要で提案されていた形式からの変更）

タスク概要では「短期間のインメモリキャッシュ（TTL は 5～10 分）」が提案されていました。代わりに、10 分ごとにカタログを再走査してキャッシュを置き換えるバックグラウンドループを継続的に実行し、購入者からのリクエストは常に現在キャッシュされているデータを読み取るように実装しました（リクエスト自体が走査を開始することはありません）。有効期限が切れたときにリクエストに応じて取得する単純な TTL 方式では、期限切れ直後にたまたま届いた購入者のリクエストが $0.01 を負担し、最新の 481 ページ分の走査が終わるまで最大約 5 分間待たされます。これは設計時に許容できない購入者体験だと判断したものであり、後から見つかった問題ではありません。バックグラウンドループ方式なら、支払いを行う呼び出し元を走査完了まで待たせることなく、「402index.io への過剰なアクセスを避ける」という同じ目標を達成できます。

コールドスタート（Cloud Run のスケールゼロ）

min-instances=0 のため、新しいコンテナは空のキャッシュで起動します。一定期間アイドル状態だった後の最初のリクエストでは、catalog_walk.status: "cold_fallback_feed_only" が返されるため、結果は現在 /feed.xml?type=new に含まれるデータ（最近確認した範囲では数時間分のみ）に限られ、リクエストされた期間全体は網羅されません。この点は隠さず、レスポンス自体の note フィールドで開示します。バックグラウンドタスクの最初の走査が完了すると（コンテナ起動から約 5 分後）、以降のリクエストにはカタログ全体の走査結果を含む status: "warm" が返されます。完全な解決ではなく、実質的な緩和です。詳しくは「既知の制限事項」を参照してください。

料金：1 回あたり $0.01（低価格ティア）

プロダクトオーナーの明確な指示に基づくニッチな領域での推定であり、データに基づく結論ではありません。url-metadata-api／document-conversion-api と同じ低価格ティアの $0.01～$0.02 であり、agent-verification-api のシグナルティアの $0.35 ではありません。有料のサードパーティ API コストはなく、純粋に CPU／メモリのコストと、呼び出しごとの無料の上流フェッチ 1 回のみです。

デプロイ前の品質ゲート（2026-08-23、事後的ではなく設計時に実施）

初回デプロイ前に4つの観点からレビューし、各ステップでモックではなく実際に稼働中の402index.io APIに対してテストしました。実際に見つかった問題と修正内容：

• セキュリティ：呼び出し元の入力（window_hours／protocol／category／payment_network）が、上流の402index.ioリクエストに埋め込まれることはありません。カタログの走査とフィードの取得では、固定のハードコードされたクエリパラメーター（それぞれlimit／offset／sort／order、およびtype=new）のみを使用します。呼び出し元のフィルターは、取得・正規化済みのメモリー内の結果に対してのみ適用されます。上流のJSON/XMLを無条件に信頼していないことも確認しました。読み取るすべてのフィールドで型チェック付きの.get()を使用し（_normalize_catalog_itemは不正なエントリーに対して例外を発生させずNoneを返します）、/feed.xmlの不正なXMLはリクエストをクラッシュさせずに捕捉し（ET.ParseError）、フィード内の不正な<item>が1件あっても残りの項目は破棄されません。これらすべてを、今回の作業中に実際の不正入力（None、IDの欠落、不正な型、不正なタイムスタンプ、途中で切れたXML）を使ったテストで確認しました。正しいと判断して読み流しただけではありません。
• 機能の正確性（実際の問題を修正）：当初の設計では内部的にcomplete: boolをキャッシュしていましたが、レスポンスには反映していませんでした。そのため呼び出し元は、バックグラウンドの走査が_WALK_MAX_WALL_SECONDSの実時間上限に達して部分的な結果で終了したのか、正常に完了したのかを区別できませんでした。どちらもstatus: "warm"を返していたためです。これを修正し、レスポンスにcatalog_walk.walk_completeを追加しました。ページネーション（offsetの加算、総数に達した時点での停止、実時間上限による終了）は、実際に稼働中のAPIに対して上限を設けたテスト走査で検証しました（実際の8ページを取得し、offsetが正しく進み、ログに記録されたうえで正常に終了）。無言のままデータが途切れることも、無限ループもありません。
• コード品質：レビューではデッドコードや未使用のインポートは見つかりませんでした。手作業で移植した兄弟アセットの構成（Supabaseのテレメトリーヘルパー、x402の接続、ディスカバリールート）に沿っており、document-conversion-api／url-metadata-apiと一貫した実装です。
• 購入者体験（「生データは他でも無料で入手できる」という開示の観点）：402index.ioのデータ自体は無料であるという事実が、READMEだけでなく3か所に記載されていることを確認しました。agent-cardのprotocol_noteに加えて、より直接的に、購入者がagent-cardを取得しなくても済むよう、すべてのAPIレスポンス自体のnoteフィールドにも記載しています。キャッシュがない場合にカバレッジが低下するケース（cold_fallback_feed_only）についても、呼び出し元が意味を解釈する必要があるステータス列挙値だけでなく、リクエストされた期間にどのような影響があるのかを平易な表現で同じnoteフィールドに明記しています。

既知の制限事項（黙って変更せず、文書化されたトレードオフとして扱います）

• MCP ツール呼び出しには課金されません。 関連する手動アセットと同じ、インプロセス呼び出しのパターンです。
• 呼び出し元ごとのレート制限はありません。 7日間の使い捨て測定期間であれば問題ありません。
• コールドキャッシュ期間のカバレッジ不足は緩和されていますが、解消されていません。 Cloud Run のコールドスタート後、最初の約5分間にリクエストが到着すると、同じ $0.01 が課金されるにもかかわらず、リクエストされた期間全体ではなくフィードのみが対象になります（現在の402indexの速度で90件のフィードの場合、最近確認された対象期間は約3時間です）。この点はレスポンス内で明示されますが、コールドスタート直後に一度だけ呼び出し、catalog_walk.status／note を読まない購入者が、短い結果リストを「キャッシュがまだウォームアップ中」ではなく「新着なし」と合理的に受け取ってしまう可能性があります。将来的な対策として、min-instances=1 を維持してコールドスタートを完全になくす方法がありますが、Cloud Run の常時稼働コストが実際に発生するため、7日間の試験候補では実施していません。
• registered_at は UTC と仮定しています。 402index の /api/v1/services はタイムゾーン情報のないタイムスタンプ（"2026-08-22 22:13:15"）を返します。今回のセッション中に実際に確認した last_checked の値との整合性を根拠に UTC として扱っていますが、402index.io 自体が保証を文書化しているわけではありません。
• カタログ全体を走査するペース設定は、現在のカタログサイズを前提としています。 約96k件の場合、全件走査は約481ページ／約5.2分で、10分の更新間隔内に十分収まります。今回のセッションで確認された前回チェック時からの約12倍というペースで402indexのカタログが増え続けると、将来の走査が10分の更新間隔に近づく、または超える可能性があります（その場合は表示される「last_full_walk_at」の更新間隔が長くなるだけで、機能が壊れるわけではありません。_WALK_MAX_WALL_SECONDS により1サイクルは900秒で終了し、walk_complete はその状態を正確に報告します）。CLAUDE.md SS3 に従い、必要性を示す根拠がまだないため、先回りして再設計はしていません。

NEXUS_X402_FREE_MODE

デフォルトは false（初日から課金し、フリーミアム期間なし）です。document-conversion-api と同じ方針です。 実際のファシリテーターとの往復通信なしでテストする場合は、ローカルで true に設定します。

デプロイ先：Railway ではなく Cloud Run

候補 #3／#4／#6 と同じパイプラインです。skills/infra-deploy-ops を参照してください。ここでは PDF／Office の解析を行わないため、共有スクリプトのデフォルトである512Miを使用します（document-conversion-api のように1Giへ引き上げません）。

# 1. First deploy -- PUBLIC_DOMAIN not known yet, every real request 421s until step 2.
./scripts/deploy_cloud_run.sh new-x402-listings-feed manual_assets/new-x402-listings-feed \
    manual_assets/new-x402-listings-feed/env-vars.deploy.yaml

# 2. Grab the printed *.run.app URL, then:
gcloud run services update new-x402-listings-feed --region us-central1 --project nexus-505016 \
    --update-env-vars PUBLIC_DOMAIN=<the-real-domain>

測定（候補 #8、7日間）

最初の実デプロイ（2026-08-23）から7日間（判断日は2026-08-30）です。信頼できる唯一の情報源は Cloud Run のログではなく、traffic_events／revenue_events／mcp_call_events テーブル（asset_name = 'new-x402-listings-feed'）です。7日目に、クローラーを除外した実トラフィックがゼロなら、候補 #3／#4／#6 と同じ判断基準で Cloud Run サービスを一時停止／削除します。これは4つの手動候補の中で最も推測的なものだと明示されています（プロダクトオーナー自身の表現）。実証済みの継続需要があるドキュメント変換やリンクプレビューのような形ではなく、まだ初期段階にある x402 エコシステム向けのニッチな発見フィードです。