Suwappu

The execution layer for onchain apps and agents.
Route across chains, simulate before money moves, and choose self-custody or managed execution from the same platform.

Quickstart  ·  Terminal  ·  Telegram  ·  Developer Docs  ·  Product Status  ·  Security

---

What can I build?

---

Why Suwappu

One control plane, not one venue

Suwappu normalizes an execution intent, discovers only the routes that can actually serve it, and compares eligible providers instead of hard-coding one exchange or bridge. The generated topology currently reports 45 platform chains, 18 Agent API chains, and 21 chain-gated routing integrations. Those are platform totals—not a claim that every route races every provider.

Human and agent surfaces share the same execution layer

Telegram, web/terminal clients, SDKs, REST, MCP, and A2A are different entry points into the same platform boundaries. Builders do not need a separate “agent DEX” and “human DEX” architecture.

Custody is explicit

Suwappu does not collapse “get a quote,” “prepare a transaction,” and “move funds” into one ambiguous action. Self-custody preparation and managed execution are separate capabilities with separate security consequences.

Execution is observable

The system records route candidates, selected routes, execution/status data, and settlement evidence. New execution-synchronization work adds normalized receipts, provider calibration, and historical/walk-forward replay—but remains shadow-only until evidence supports a controlled promotion.

The platform extends beyond swaps

The same API/control plane also exposes workflows for perps, prediction markets, lending, BTC bridging, orders, portfolio data, and wallet policy where supported by the relevant surface.

See Product Status for what is production, hosted, source-only, shadow, or experimental.

---

The execution ladder

Start with the least-privileged capability your product needs and move downward only when your policy requires it.

Important naming boundary: MCP execute_swap currently belongs to Level 3: it prepares an unsigned self-custody transaction. It does not invoke managed execution. A2A currently stops at discovery/quote semantics and has no fund-moving method.

For an AI system, begin at Levels 0–2 with an application-owned allowlist. Add Level 3 or 4 only with explicit policy, limits, and approval appropriate to the value at risk.

---

First useful integration

1. Register an agent credential

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

Store the returned suwappu_sk_... as SUWAPPU_API_KEY. Do not commit it.

2. Discover supported chains

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

Do this at runtime instead of embedding a chain count in application code.

3. Request a quote with the 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);

Install the SDK with:

npm install @suwappu/sdk

Repository source can move ahead of the published package. Check the SDK README and Product Status when version boundaries matter.

Or connect an MCP client

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

Discover tools/resources/prompts at runtime rather than copying a static registry from documentation.

Continue with the full quickstart or MCP / SDK / REST / A2A guide.

---

Execution model

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

Routing is capability- and chain-gated. The canonical generated counts live in showcase/src/data/stats.generated.json; application code should use runtime discovery APIs.

Major capability areas

• Execution: same-chain/cross-chain swaps, limit orders, DCA, MEV-aware routes.
• Markets: HyperLiquid perps, predictions, market discovery.
• Capital: lending/savings and BTC bridge workflows.
• Automation: alerts, copy trading, sniping, transaction/portfolio workflows.
• Policy: simulation, spending limits, 2FA, withdrawal allowlists, token safety checks.
• Agents: REST, hosted MCP, A2A, TypeScript/Python SDKs, framework examples.

Feature availability varies by client and chain. Use Feature Guides and Product Status instead of assuming monorepo presence means universal availability.

---

Architecture

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

The production runtime includes request-serving services, dedicated workers, bridge/relayer services, signal/on-chain ingestion, Postgres, and Redis. Do not infer deployment topology from source directories; use the production inventory.

For system boundaries, data flows, key handling, and background services, read the Architecture Overview.

---

Production vs research

Suwappu intentionally keeps experimental work visible without presenting it as live money-path behavior.

The canonical definitions and version caveats are in Product Status.

---

Security model for builders

Suwappu moves money, so the security boundary belongs next to the integration flow—not at the bottom of the docs.

• Keep credentials out of source and logs.
• Prefer runtime discovery plus an application-owned allowlist of tools/capabilities.
• Treat model output and third-party text as untrusted input to execution policy.
• Simulate unfamiliar routes before enabling execution.
• Keep self-custody signing separate from managed execution.
• Add explicit spend/value/destination policies before granting an agent Level 3 or 4 capability.
• Treat signing, custody, routing, withdrawals, fee collection, and authorization changes as MONEY-PATH code requiring adversarial review.

Read SECURITY.md and the agent security baseline. The checked-in CycloneDX SBOM, CodeQL, and OpenSSF tooling are security evidence—not an audit or compliance certification.

---

Engineering contracts

Fast-moving infrastructure becomes unreliable when docs, config, and deployment state each invent their own truth. Suwappu keeps important facts in versioned contracts:

Docs-only changes can be checked with:

./scripts/verify.sh docs

For local setup and component-specific test lanes, use ONBOARDING.md.

---

Repository map

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

---

Documentation

License

Apache-2.0. See LICENSE.