suwappu

Suwappu

オンチェーンアプリとエージェントのための実行レイヤー。
チェーンをまたいでルーティングし、資金が動く前にシミュレーションを行い、同じプラットフォームからセルフカストディまたはマネージド実行を選択できます。

クイックスタート  ·  ターミナル  ·  Telegram  ·  開発者向けドキュメント  ·  プロダクトの状況  ·  セキュリティ

suwappu.bot — プロダクト、リサーチ、開発者向けの各種エントリーポイント。

terminal.suwappu.bot — マーケット、チャート、スワップ、注文、ポートフォリオ。

---

ETHGlobal Tokyo 2026 — Agent Swap Passport

ライブデモ → suwappu.bot/passport

1つのウォレットをライブで検証します。未検証のままスワップを試すと、Uniswap v4 beforeSwap フック (0xc72ab4dF…c080) がガス代ゼロでリバートします。World IDをスキャンすると、サーバーがSepolia上で suwappu-agents.eth 配下の実際のENSv2サブネームをウォレットに発行し、同じフックの許可リストに追加します。もう一度スワップすると、同じプールを通じて実行されます。1回の検証で3つのスポンサー連携を実現し、ウォレットごとの1回の記録済み実行ですべてを実証します。各主張はモックではなく、実際のSepoliaトランザクションによって裏付けられています。正確な file:line の参照先、トランザクションハッシュ、スポンサー別トラック（World ID/IDKit、ENSv2、Uniswap v4）の2分間のセルフ検証手順については、 docs/ethglobal-tokyo2026/SUBMISSION.mdをご覧ください。Interceptaも検討しましたが、この提出物の対象範囲外であることを明示しています。デモはなく、ライブAPIキーも設定していません。

---

構築できるもの

目標	こちらから始める
アプリに取引機能を追加する	@suwappu/sdk · Agent REST
AI エージェントに市場ツールを提供する	Hosted MCP · A2A
ブラウザーエージェントが人間の確認を挟んで取引できるようにする	WebMCP Agent Desk · /agent-terminal
セルフカストディのフローを構築する	Execution ladder · custody semantics
マネージド実行を構築する	Agent REST · security baseline
直接取引する	Terminal · Telegram
システムを理解する	Architecture · ADRs
本番環境を運用する	Production inventory · 監視

---

Suwappu の特長

1 つの制御プレーンで、特定の取引所に依存しない

Suwappu は実行インテントを標準化し、実際にそのインテントを処理できるルートだけを検出して、特定の取引所やブリッジにハードコードするのではなく、利用可能なプロバイダーを比較します。現在、生成されたトポロジーには、45 のプラットフォームチェーン、18 の Agent API チェーン、21 のチェーン対応ルーティング統合が報告されています。これらはプラットフォーム全体の数であり、すべてのルートがすべてのプロバイダーと競合するという意味ではありません。

人間向けとエージェント向けのインターフェースで同じ実行レイヤーを共有

Telegram、Web／ターミナルクライアント、SDK、REST、MCP、A2A は、同じプラットフォーム境界への異なるエントリーポイントです。開発者が「エージェント向けDEX」と「人間向けDEX」を別々のアーキテクチャにする必要はありません。

カストディを明確化

Suwappu は、「見積もりを取得する」「トランザクションを準備する」「資金を移動する」を、曖昧な 1 つのアクションにまとめません。セルフカストディでの準備とマネージド実行は別々の機能であり、それぞれセキュリティ上の影響も異なります。

実行状況を可視化

システムはルート候補、選択されたルート、実行／ステータスデータ、決済の証跡を記録します。新たな実行同期機能では、標準化されたレシート、プロバイダーの較正、過去データ／ウォークフォワード再生が追加されますが、証拠に基づいて管理された昇格が可能になるまでは、シャドー専用のままです。

スワップにとどまらないプラットフォーム

関連するインターフェースでサポートされている場合、同じ API／制御プレーンから、パープ、予測市場、レンディング、BTC ブリッジ、注文、ポートフォリオデータ、ウォレットポリシーのワークフローも利用できます。

本番、ホスト型、ソースのみ、シャドー、実験的機能の詳細は、Product Status をご覧ください。

---

実行レベル

製品に必要な機能のうち、最も権限の低いものから始め、ポリシー上必要な場合にのみ下位のレベルへ進んでください。

レベル	機能	資金を移動しますか？	一般的なインターフェース
0 — 検出	チェーン、トークン、価格、ポートフォリオ、市場メタデータ	いいえ	REST · MCP · SDK · A2A
1 — 見積もり	インテントの価格を算出し、利用可能なルートを比較する	いいえ	REST · MCP · SDK · A2A
2 — シミュレーション	提案されたスワップを署名／実行の前に評価する	いいえ	REST · MCP
3 — 準備	署名前のセルフカストディトランザクションを構築する	いいえ	REST · MCP · SDK
4 — 実行	サーバー側のマネージド実行	はい	明示的な Agent REST／マネージド SDK の経路

重要な命名上の境界： MCP の execute_swap は現在、レベル 3 に該当し、署名前のセルフカストディトランザクションを準備します。マネージド実行は呼び出しません。A2A は現在、検出／見積もりのセマンティクスまでで、資金を移動するメソッドはありません。

AI システムでは、アプリケーション側で管理する許可リストを用意し、レベル 0～2 から始めてください。レベル 3 または 4 を追加するのは、リスクにさらされる価値に応じた明示的なポリシー、上限、承認を設けた場合に限ります。

---

最初の実用的な統合

1. エージェント認証情報を登録する

curl -X POST https://api.suwappu.bot/v1/agent/register \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-agent"}'

返された suwappu_sk_... を SUWAPPU_API_KEY として保存してください。コミットしないでください。

2. 対応チェーンを検出する

curl https://api.suwappu.bot/v1/agent/chains \
  -H "Authorization: Bearer $SUWAPPU_API_KEY"

アプリケーションコードにチェーン数を埋め込むのではなく、実行時に検出してください。

3. TypeScript SDK で見積もりをリクエストする

import { Suwappu } from "@suwappu/sdk";

const suwappu = new Suwappu({
  apiKey: process.env.SUWAPPU_API_KEY,
});

const quote = await suwappu.getQuote({
  from: "USDC",
  to: "ETH",
  chain: "base",
  amount: "100",
});

console.log(quote.toAmount);

次のコマンドで SDK をインストールします。

npm install @suwappu/sdk

リポジトリのソースは公開済みパッケージより先行している場合があります。バージョンの境界が重要な場合は、SDK README と Product Status を確認してください。

または MCP クライアントに接続する

{
  "mcpServers": {
    "suwappu": {
      "url": "https://api.suwappu.bot/mcp",
      "headers": {
        "Authorization": "Bearer suwappu_sk_..."
      }
    }
  }
}

ドキュメントから静的なレジストリをコピーするのではなく、実行時にツール／リソース／プロンプトを検出してください。

クイックスタート全文 または MCP / SDK / REST / A2A ガイドに進んでください。

---

実行モデル

Intent
  │
  ├─ identity / auth / wallet policy
  ├─ route eligibility
  ├─ parallel quote discovery
  ├─ safety + simulation + limits
  │
  ├─ self-custody ──> unsigned transaction ──> caller signs/broadcasts
  │
  └─ managed ───────> explicit execution path ──> status / settlement evidence
                                      │
                                      └─> receipts / scoring / replay evidence

ルーティングは、機能とチェーンの両方によって制御されます。正規の生成済み件数は showcase/src/data/stats.generated.json にあります。アプリケーションコードでは、実行時の検出 API を使用してください。

主な機能領域

• 実行： 同一チェーン／クロスチェーンのスワップ、指値注文、DCA、MEV を考慮したルート。
• マーケット： HyperLiquid パーペチュアル、予測市場、マーケットの検出。
• 資本： 貸付／貯蓄、BTC ブリッジのワークフロー。
• 自動化： アラート、コピー取引、スナイピング、トランザクション／ポートフォリオのワークフロー。
• ポリシー： シミュレーション、支出上限、2FA、出金許可リスト、トークンの安全性チェック。
• エージェント： REST、ホスト型 MCP、A2A、TypeScript／Python SDK、フレームワークの例。

機能の提供状況は、クライアントやチェーンによって異なります。モノレポに存在することがすべての環境で利用できることを意味すると想定せず、機能ガイドと Product Statusを参照してください。

---

アーキテクチャ

flowchart LR
    subgraph Clients["Entry points"]
        Human["Telegram · Web · Terminal · Mobile"]
        Apps["TypeScript/Python SDK · REST"]
        Agents["MCP · A2A"]
    end

    subgraph Platform["Suwappu"]
        API["API + control plane"]
        Policy["Auth · simulation · safety · wallet policy"]
        Router["Eligibility · quote race · execution"]
        Evidence["Status · receipts · execution evidence"]
    end

    subgraph Settlement["External execution + settlement"]
        Providers["Chain-gated routers / venues"]
        Chains["EVM · Solana · TRON · Starknet · others"]
    end

    Human --> API
    Apps --> API
    Agents --> API
    API --> Policy --> Router --> Providers --> Chains
    Router --> Evidence

本番ランタイムには、リクエスト処理サービス、専用ワーカー、ブリッジ／リレイヤーサービス、シグナル／オンチェーンデータの取り込み、Postgres、Redis が含まれます。ソースディレクトリからデプロイ構成を推測しないでください。本番環境のインベントリを参照してください。

システム境界、データフロー、鍵の取り扱い、バックグラウンドサービスについては、アーキテクチャの概要をお読みください。

---

本番環境と研究開発

Suwappu では、実験的な取り組みを公開しながらも、それらを実際の資金移動に関わる挙動として提示しないようにしています。

領域	ステータス	意味
ターミナル／ウェブ／Telegram／コア API	本番環境	ユーザーまたはアプリケーション向けのランタイム機能
ホスト型 MCP／Agent REST／A2A	ホスト型	稼働中のプログラム用インターフェース。機能はインターフェースごとに異なります
TypeScript SDK	公開済み＋ソース	npm パッケージとモノレポのソース。ソースが先行している場合があります
Python SDK	ソースのみ	本番環境との統合には、リポジトリのリビジョンを固定して使用してください
execution_sync*	シャドウ	読み取り専用の較正／リプレイの証跡。ルーティングの決定権はありません
contracts/primitives/	実験的／準備状況による制限あり	リポジトリに存在しても、デプロイ済みまたは本番環境の依存関係であることを意味しません

正規の定義とバージョンに関する注意事項は、Product Statusに記載されています。

---

ビルダー向けセキュリティモデル

Suwappu は資金を扱うため、セキュリティ境界はドキュメントの末尾ではなく、統合フローのすぐそばに設ける必要があります。

• 認証情報をソースコードやログに含めないでください。
• 実行時の検出と、アプリケーションが管理するツール／機能の許可リストを優先してください。
• モデルの出力やサードパーティのテキストは、実行ポリシーに対する信頼できない入力として扱ってください。
• 不慣れなルートは、実行を有効にする前にシミュレーションしてください。
• セルフカストディの署名は、管理型の実行とは分離してください。
• エージェントにレベル 3 または 4 の機能を付与する前に、支出額／価値／送金先に関する明示的なポリシーを追加してください。
• 署名、カストディ、ルーティング、出金、手数料の徴収、認可の変更は、敵対的レビューが必要な資金移動関連コードとして扱ってください。

SECURITY.md とエージェント向けセキュリティの基本要件をお読みください。リポジトリに含まれている CycloneDX SBOM、CodeQL、OpenSSF ツールはセキュリティ上の証跡であり、監査やコンプライアンス認証ではありません。

---

エンジニアリング契約

変化の速いインフラでは、ドキュメント、設定、デプロイ状態がそれぞれ独自の正解を作り出すと、信頼性が損なわれます。Suwappu は重要な情報をバージョン管理された契約で管理します。

契約	正式な情報源
stats.generated.json	公開されているチェーン／ルーターの数
.env.schema	環境変数の契約
capabilities.yaml	オプションの機能／プロバイダーマニフェスト
ARCHITECTURE.md	規範となるシステム境界
docs/adr/	アーキテクチャ上の決定
docs/deployment/production-inventory.md	現在の本番サービスカタログのスナップショット
docs/product-status.md	成熟度と公開に関する意味

ドキュメントのみの変更は、次のコマンドで確認できます。

./scripts/verify.sh docs

ローカル環境のセットアップとコンポーネントごとのテスト手順については、ONBOARDING.mdを参照してください。

---

リポジトリの構成

suwappubot/
├── api-ts/             # Agent REST, MCP, A2A, webapp and execution routes
├── api/                # Python FastAPI entry points
├── bot/                # Bot, execution engine, services, workers, models
├── webapp/             # React/Vite application
├── terminal/           # Trading terminal / Mini App
├── mobile/             # Expo iOS client
├── extension/          # Browser wallet extension
├── showcase/           # Public website, products, research, generated stats
├── contracts/          # Solidity contracts and protocol primitives
├── packages/           # SDKs, MCP bridge, OpenClaw, design tokens
├── docs/               # Product, architecture, security, operations, research
├── database/           # Schema/bootstrap and runtime migrations
├── scripts/            # Verification, replay, maintenance, ops tooling
├── monitoring/         # Health/monitoring manifests
├── sbom/               # CycloneDX software bill of materials
└── .github/workflows/  # CI, security and deployment workflows

---

ドキュメント

リソース	用途
クイックスタート	ユーザー／エージェント／アプリとの初回連携を成功させる
エージェントクライアント	MCP、SDK、REST、A2A、認証、カストディの仕様
プロダクトのステータス	本番、ホスト型、ソースのみ、シャドー、実験的の区別
機能ガイド	ユーザー向け機能のワークフロー
アーキテクチャ	ランタイムの境界とリクエスト／データのフロー
本番インベントリ	Railway サービスカタログのスナップショット
ADR · 決定事項	重要な選択がなされた理由
オンボーディング · コントリビューション	モノレポでの作業
セキュリティ · サポート	脆弱性とサポート

ライセンス

Apache-2.0。詳細はLICENSEを参照してください。