AgentData - Executable Liquidity / Exit-Cost

AgentData — 実行可能な流動性（エンドポイント #1）

AI エージェント向けの従量課金データエンドポイントです。Base 上のトークンについて、サイズを考慮した売却コスト、デペッグリスク、流動性の脆弱性を提供します。生の価格ではなく、エージェントが行動する前に必要とする、算出・正規化済みの意思決定に役立つ情報です。x402（Phase 2）経由で USDC で決済します。オンチェーンのデータを取得元としているため、派生データは自由に再配布できます。

戦略、価値観、ロードマップは CLAUDE.md に記載されています。決定事項は decisions/DECISION_LOG.md と decisions/adr/ に記録されています。

回答できること

「今このポジションを売却しようとした場合、実際のコストはいくらですか？スリッページが X bps を超える前に、どれだけの量を動かせますか？また、その流動性はどの程度脆弱ですか？」

3 つの有料ティア（唯一の情報源は agentdata/api/pricing.py）：

ティア	内容	メインネット価格
quote	1 つのサイズに対する最良ルートの売却コスト	$0.008
risk	売却コスト + 脆弱性（ペッグ資産の場合はデペッグも）— デフォルト	$0.02
deep	risk + 複数サイズの売却コスト曲線 + コスト別の最大サイズ一覧	$0.04

テストネットでは、すべての価格が $0 になります（402 のフローは引き続きエンドツーエンドで実行されます）。

ディレクトリ構成

src/agentdata/
  config.py            # env-driven; NETWORK_MODE testnet|mainnet (testnet default)
  compute/             # the value-add: pure, deterministic, unit-tested math
    amm.py             #   constant-product + Solidly stable curve, exit cost
    routing.py         #   cheapest-venue selection
    depeg.py           #   depeg deviation / dispersion / score
    fragility.py       #   depth + concentration + convexity -> fragility score
    tiers.py           #   quote / risk / deep orchestration
  chain/               # on-chain Base reads (Aerodrome / Uniswap), web3 lazy
    provider.py        #   FixturePoolProvider (default) + factory
    onchain.py         #   OnChainPoolProvider (env-gated, no guessed addresses)
  api/                 # FastAPI JSON layer + pricing + stable schema
  monitoring/          # uptime, latency p50/p95, error rate, calls per tier
tests/                 # unittest (stdlib for compute; fastapi for api)

実行方法（ローカル、資金不要、ネットワーク不要）

pip install -e .            # or: pip install fastapi pydantic 'uvicorn[standard]'
uvicorn agentdata.api.app:app --reload
# then:
curl 'http://127.0.0.1:8000/v1/liquidity/exit-cost?token=WETH&size=10&tier=risk'
curl 'http://127.0.0.1:8000/pricing'
curl 'http://127.0.0.1:8000/metrics'

デフォルト：NETWORK_MODE=testnet、POOL_SOURCE=fixture（決定論的なデモ用プール WETH、THIN、USDX）。.env.example を参照してください。

テスト

# compute core needs no dependencies:
PYTHONPATH=src python -m unittest discover -s tests

ステータス

• Phase 1（ローカルエンドポイント）：完了。 計算 + チェーンとの接続部分 + API + モニタリング。テスト 42 件がすべて成功しています。
• Phase 2（x402 テストネット）：次の段階。 API の前段に決済ミドルウェアを配置し、Base Sepolia 上の無料テストネットファシリテーターを使用します。実際の USDC は使用しません。メインネットへの移行には、人によるエスカレーション判断が必要です（CLAUDE.md §0/§14）。
• オンチェーンモードを使用するには、事前に検証済みのプールレジストリが必要です（ADR-001）。このコードは、データを偽造するのではなく、推測したコントラクトアドレスでの実行を拒否します。