io.github.0xSoftBoi/suwappu

suwappu.bot — products, research, and developer entry points.

terminal.suwappu.bot — markets, charts, swaps, orders, and portfolio.

---

What can I build?

Goal	Start here
Add trading to an app	@suwappu/sdk · Agent REST
Give an AI agent market tools	Hosted MCP · A2A
Let a browser agent trade with a human in the loop	WebMCP Agent Desk · /agent-terminal
Build a self-custody flow	Execution ladder · custody semantics
Build managed execution	Agent REST · security baseline
Trade directly	Terminal · Telegram
Understand the system	Architecture · ADRs
Operate production	Production inventory · monitoring

---

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.

Level	Capability	Moves funds?	Typical surfaces
0 — Discover	Chains, tokens, prices, portfolio, market metadata	No	REST · MCP · SDK · A2A
1 — Quote	Price an intent and compare eligible routes	No	REST · MCP · SDK · A2A
2 — Simulate	Evaluate a proposed swap before signing/execution	No	REST · MCP
3 — Prepare	Build an unsigned self-custody transaction	No	REST · MCP · SDK
4 — Execute	Managed server-side execution	Yes	Explicit Agent REST / managed SDK path

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.

Area	Status	Meaning
Terminal / web / Telegram / core APIs	Production	User- or application-facing runtime surfaces
Hosted MCP / Agent REST / A2A	Hosted	Live programmatic interfaces; capabilities differ by surface
TypeScript SDK	Published + source	npm package plus monorepo source; source may be ahead
Python SDK	Source-only	Use a pinned repository revision for production integration
execution_sync*	Shadow	Read-only calibration/replay evidence; not routing authority
contracts/primitives/	Experimental / readiness-gated	Presence in repo does not imply deployment or production dependency

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:

Contract	Source of truth for
stats.generated.json	Public chain/router counts
.env.schema	Environment-variable contract
capabilities.yaml	Optional capability/provider manifest
ARCHITECTURE.md	Normative system boundaries
docs/adr/	Architecture decisions
docs/deployment/production-inventory.md	Current production service catalog snapshot
docs/product-status.md	Maturity and publication semantics

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

Resource	Use it for
Quickstart	First successful user/agent/app integration
Agent clients	MCP, SDK, REST, A2A, auth and custody semantics
Product status	Production vs hosted vs source-only vs shadow vs experimental
Feature guides	User-facing capability workflows
Architecture	Runtime boundaries and request/data flows
Production inventory	Railway service-catalog snapshot
ADRs · Decisions	Why important choices exist
Onboarding · Contributing	Work on the monorepo
Security · Support	Vulnerabilities and help

License

Apache-2.0. See LICENSE.