suwappu

Suwappu

链上应用与 Agent 的执行层。
跨链路由，在资金转移前进行模拟，并在同一平台选择自主托管或托管式执行。

快速入门  ·  终端  ·  Telegram  ·  开发者文档  ·  产品状态  ·  安全

suwappu.bot — 产品、研究与开发者入口。

terminal.suwappu.bot — 市场、图表、兑换、订单与投资组合。

---

ETHGlobal Tokyo 2026 — Agent 兑换护照

在线演示 → suwappu.bot/passport

同一个钱包，实时验证：尝试兑换但未通过验证时，Uniswap v4 beforeSwap hook (0xc72ab4dF…c080) 会在消耗零 gas 的情况下回滚。扫描 World ID 后，服务端会在 Sepolia 上为该钱包铸造一个真实的 ENSv2 子名称，挂在 suwappu-agents.eth 下，并将其加入同一个 hook 的允许名单。再次兑换——交易便会通过 同一个池执行。一次验证，三项赞助商集成，全部由一次按钱包记录的运行证明。每项声明都有真实的 Sepolia 交易作为依据，并非模拟——请参阅 docs/ethglobal-tokyo2026/SUBMISSION.md，了解准确的 file:line 指引、交易哈希，以及每个赞助商赛道（World ID/IDKit、ENSv2、Uniswap v4）的 2 分钟自行验证流程。此次提交曾探索 Intercepta，但明确不在范围内——未进行演示，也未配置有效的 API 密钥。

---

我可以构建什么？

目标	从这里开始
为应用添加交易功能	@suwappu/sdk · Agent REST
为 AI Agent 提供市场工具	托管 MCP · A2A
让浏览器 Agent 在人工参与下进行交易	WebMCP Agent Desk · /agent-terminal
构建自托管资金流程	执行阶梯 · 托管语义
构建托管执行功能	Agent REST · 安全基线
直接交易	终端 · Telegram
了解系统	架构 · ADR
运维生产环境	生产环境清单 · 监控

---

为什么选择 Suwappu

一个控制平面，而非单一交易场所

Suwappu 会规范化执行意图，只发现实际能够处理该意图的路由，并比较符合条件的服务提供方，而不是将某个交易所或桥接服务写死在系统中。目前生成的拓扑报告显示：45 条平台链、18 条 Agent API 链和 21 个按链启用的路由集成。这些是平台总数，并不表示每条路由都会与所有服务提供方竞速。

人类和 Agent 使用相同的执行层

Telegram、Web/终端客户端、SDK、REST、MCP 和 A2A 是进入同一平台边界的不同入口。开发者无需分别构建“Agent DEX”和“人类 DEX”架构。

托管方式明确

Suwappu 不会把“获取报价”“准备交易”和“转移资金”混为一个含义模糊的操作。自托管准备和托管执行是彼此独立的能力，带来的安全影响也各不相同。

执行过程可观测

系统会记录候选路由、选定路由、执行和状态数据，以及结算凭证。新增的执行同步工作会加入规范化回执、服务提供方校准和历史／滚动前向回放，但在证据支持受控升级之前，仍仅处于影子模式。

平台功能不止于兑换

在相关界面支持的情况下，同一 API／控制平面还会提供永续合约、预测市场、借贷、BTC 跨链桥接、订单、投资组合数据和钱包策略等工作流。

关于哪些功能处于生产、托管、仅提供源代码、影子模式或实验阶段，请参阅产品状态。

---

执行阶梯

从产品所需的权限最低的能力开始，只有在策略要求时才向下扩展。

级别	能力	会转移资金吗？	常见界面
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. 注册 Agent 凭证

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 桥接工作流。
• 自动化： 警报、跟单交易、抢先交易、交易／投资组合工作流。
• 策略： 模拟、支出限额、双重身份验证、提款白名单、代币安全检查。
• Agent： REST、托管 MCP、A2A、TypeScript／Python SDK、框架示例。

功能可用性因客户端和链而异。请参阅功能指南和 Product Status，不要假定存在于 monorepo 中就意味着普遍可用。

---

架构

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 有意保留实验性工作，以便查看，但不会将其描述为实时资金路径行为。

领域	状态	含义
Terminal／web／Telegram／核心 API	生产环境	面向用户或应用的运行时界面
托管 MCP／Agent REST／A2A	托管	实时程序化接口；各界面的能力有所不同
TypeScript SDK	已发布 + 源代码	npm 软件包及 monorepo 源代码；源代码可能领先
Python SDK	仅源代码	生产集成请使用固定的仓库修订版本
execution_sync*	影子模式	只读校准／重放证据；不作为路由依据
contracts/primitives/	实验性／受就绪状态限制	仓库中存在并不意味着已部署或依赖于生产环境

规范定义和版本注意事项见 Product Status。

---

面向构建者的安全模型

Suwappu 会转移资金，因此安全边界应紧邻集成流程，而不是放在文档末尾。

• 不要将凭据放在源代码和日志中。
• 优先采用运行时发现，并使用由应用负责维护的工具／能力允许列表。
• 将模型输出和第三方文本视为执行策略的不可信输入。
• 启用执行前，先模拟不熟悉的路由。
• 将自托管签名与托管执行分开。
• 授予 Agent 3 级或 4 级能力前，先添加明确的支出／价值／目标策略。
• 将签名、托管、路由、提款、费用收取和授权变更视为需要对抗性审查的资金路径代码。

请阅读 SECURITY.md 和 Agent 安全基线。已提交的 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

---

文档

资源	用途
快速入门	首次成功集成用户／Agent／应用
Agent 客户端	MCP、SDK、REST、A2A、身份验证和托管语义
产品状态	生产环境、托管、仅源代码、影子和实验性状态
功能指南	面向用户的能力工作流
架构	运行时边界和请求／数据流
生产清单	Railway 服务目录快照
ADR · 决策	重要决策的缘由
入门指南 · 贡献指南	在 monorepo 中开展工作
安全 · 支持	漏洞与帮助

许可证

Apache-2.0。详见 LICENSE。