{ "markdown": "
\n \n \"Suwappu\"\n \n
\n\n

Suwappu

\n\n

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

\n\n
\n\n[![Live](https://img.shields.io/badge/status-live-brightgreen)](https://www.suwappu.bot)\n[![CI](https://img.shields.io/github/actions/workflow/status/0xSoftBoi/suwappubot/test.yml?branch=main&label=CI)](.github/workflows/test.yml)\n[![CodeQL](https://img.shields.io/github/actions/workflow/status/0xSoftBoi/suwappubot/codeql.yml?branch=main&label=CodeQL)](.github/workflows/codeql.yml)\n[![OpenSSF Scorecard](https://img.shields.io/github/actions/workflow/status/0xSoftBoi/suwappubot/scorecard.yml?branch=main&label=OpenSSF)](.github/workflows/scorecard.yml)\n[![npm @suwappu/sdk](https://img.shields.io/npm/v/@suwappu/sdk?label=%40suwappu%2Fsdk)](https://www.npmjs.com/package/@suwappu/sdk)\n[![npm downloads](https://img.shields.io/npm/dm/@suwappu/sdk?label=SDK%20downloads)](https://www.npmjs.com/package/@suwappu/sdk)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n\n[![Platform chains](https://img.shields.io/badge/Platform_chains-45-green)](showcase/src/data/stats.generated.json)\n[![Agent API chains](https://img.shields.io/badge/Agent_API_chains-18-0f766e)](showcase/src/data/stats.generated.json)\n[![Routers](https://img.shields.io/badge/Routers-21-orange)](showcase/src/data/stats.generated.json)\n\n
\n\n

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

\n\n\n\n\n\n\n
\n\n\"Suwappu\"\n\n**[suwappu.bot](https://www.suwappu.bot)** — products, research, and developer entry points.\n\n\n\n\"Suwappu\n\n**[terminal.suwappu.bot](https://terminal.suwappu.bot)** — markets, charts, swaps, orders, and portfolio.\n\n
\n\n---\n\n## What can I build?\n\n| Goal | Start here |\n|---|---|\n| **Add trading to an app** | [`@suwappu/sdk`](packages/sdk/README.md) · [Agent REST](docs/agent-clients.md) |\n| **Give an AI agent market tools** | [Hosted MCP](docs/quickstart.md#build-an-agent) · [A2A](docs/agent-clients.md) |\n| **Let a browser agent trade with a human in the loop** | [WebMCP Agent Desk](docs/webmcp.md) · [`/agent-terminal`](https://suwappu.bot/agent-terminal) |\n| **Build a self-custody flow** | [Execution ladder](#the-execution-ladder) · [custody semantics](docs/agent-clients.md) |\n| **Build managed execution** | [Agent REST](docs/agent-clients.md) · [security baseline](docs/agent-clients.md#security-baseline-for-builders) |\n| **Trade directly** | [Terminal](https://terminal.suwappu.bot) · [Telegram](https://t.me/SuwappuBot) |\n| **Understand the system** | [Architecture](docs/architecture/OVERVIEW.md) · [ADRs](docs/adr/README.md) |\n| **Operate production** | [Production inventory](docs/deployment/production-inventory.md) · [monitoring](docs/deployment/monitoring.md) |\n\n---\n\n## Why Suwappu\n\n### One control plane, not one venue\n\nSuwappu 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.\n\n### Human and agent surfaces share the same execution layer\n\nTelegram, 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.\n\n### Custody is explicit\n\nSuwappu 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.\n\n### Execution is observable\n\nThe 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.\n\n### The platform extends beyond swaps\n\nThe 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.\n\nSee [Product Status](docs/product-status.md) for what is production, hosted, source-only, shadow, or experimental.\n\n---\n\n## The execution ladder\n\nStart with the least-privileged capability your product needs and move downward only when your policy requires it.\n\n| Level | Capability | Moves funds? | Typical surfaces |\n|---|---|---:|---|\n| **0 — Discover** | Chains, tokens, prices, portfolio, market metadata | No | REST · MCP · SDK · A2A |\n| **1 — Quote** | Price an intent and compare eligible routes | No | REST · MCP · SDK · A2A |\n| **2 — Simulate** | Evaluate a proposed swap before signing/execution | No | REST · MCP |\n| **3 — Prepare** | Build an **unsigned self-custody transaction** | No | REST · MCP · SDK |\n| **4 — Execute** | Managed server-side execution | **Yes** | Explicit Agent REST / managed SDK path |\n\n**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.\n\nFor 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.\n\n---\n\n## First useful integration\n\n### 1. Register an agent credential\n\n```bash\ncurl -X POST https://api.suwappu.bot/v1/agent/register \\\n -H 'Content-Type: application/json' \\\n -d '{\"name\":\"my-agent\"}'\n```\n\nStore the returned `suwappu_sk_...` as `SUWAPPU_API_KEY`. Do not commit it.\n\n### 2. Discover supported chains\n\n```bash\ncurl https://api.suwappu.bot/v1/agent/chains \\\n -H \"Authorization: Bearer $SUWAPPU_API_KEY\"\n```\n\nDo this at runtime instead of embedding a chain count in application code.\n\n### 3. Request a quote with the TypeScript SDK\n\n```ts\nimport { Suwappu } from \"@suwappu/sdk\";\n\nconst suwappu = new Suwappu({\n apiKey: process.env.SUWAPPU_API_KEY,\n});\n\nconst quote = await suwappu.getQuote({\n from: \"USDC\",\n to: \"ETH\",\n chain: \"base\",\n amount: \"100\",\n});\n\nconsole.log(quote.toAmount);\n```\n\nInstall the SDK with:\n\n```bash\nnpm install @suwappu/sdk\n```\n\nRepository source can move ahead of the published package. Check the [SDK README](packages/sdk/README.md) and [Product Status](docs/product-status.md) when version boundaries matter.\n\n### Or connect an MCP client\n\n```json\n{\n \"mcpServers\": {\n \"suwappu\": {\n \"url\": \"https://api.suwappu.bot/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer suwappu_sk_...\"\n }\n }\n }\n}\n```\n\nDiscover tools/resources/prompts at runtime rather than copying a static registry from documentation.\n\nContinue with the [full quickstart](docs/quickstart.md) or [MCP / SDK / REST / A2A guide](docs/agent-clients.md).\n\n---\n\n## Execution model\n\n```text\nIntent\n │\n ├─ identity / auth / wallet policy\n ├─ route eligibility\n ├─ parallel quote discovery\n ├─ safety + simulation + limits\n │\n ├─ self-custody ──> unsigned transaction ──> caller signs/broadcasts\n │\n └─ managed ───────> explicit execution path ──> status / settlement evidence\n │\n └─> receipts / scoring / replay evidence\n```\n\nRouting is capability- and chain-gated. The canonical generated counts live in [`showcase/src/data/stats.generated.json`](showcase/src/data/stats.generated.json); application code should use runtime discovery APIs.\n\n### Major capability areas\n\n- **Execution:** same-chain/cross-chain swaps, limit orders, DCA, MEV-aware routes.\n- **Markets:** HyperLiquid perps, predictions, market discovery.\n- **Capital:** lending/savings and BTC bridge workflows.\n- **Automation:** alerts, copy trading, sniping, transaction/portfolio workflows.\n- **Policy:** simulation, spending limits, 2FA, withdrawal allowlists, token safety checks.\n- **Agents:** REST, hosted MCP, A2A, TypeScript/Python SDKs, framework examples.\n\nFeature availability varies by client and chain. Use [Feature Guides](docs/features/README.md) and [Product Status](docs/product-status.md) instead of assuming monorepo presence means universal availability.\n\n---\n\n## Architecture\n\n```mermaid\nflowchart LR\n subgraph Clients[\"Entry points\"]\n Human[\"Telegram · Web · Terminal · Mobile\"]\n Apps[\"TypeScript/Python SDK · REST\"]\n Agents[\"MCP · A2A\"]\n end\n\n subgraph Platform[\"Suwappu\"]\n API[\"API + control plane\"]\n Policy[\"Auth · simulation · safety · wallet policy\"]\n Router[\"Eligibility · quote race · execution\"]\n Evidence[\"Status · receipts · execution evidence\"]\n end\n\n subgraph Settlement[\"External execution + settlement\"]\n Providers[\"Chain-gated routers / venues\"]\n Chains[\"EVM · Solana · TRON · Starknet · others\"]\n end\n\n Human --> API\n Apps --> API\n Agents --> API\n API --> Policy --> Router --> Providers --> Chains\n Router --> Evidence\n```\n\nThe 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](docs/deployment/production-inventory.md).\n\nFor system boundaries, data flows, key handling, and background services, read the [Architecture Overview](docs/architecture/OVERVIEW.md).\n\n---\n\n## Production vs research\n\nSuwappu intentionally keeps experimental work visible without presenting it as live money-path behavior.\n\n| Area | Status | Meaning |\n|---|---|---|\n| Terminal / web / Telegram / core APIs | **Production** | User- or application-facing runtime surfaces |\n| Hosted MCP / Agent REST / A2A | **Hosted** | Live programmatic interfaces; capabilities differ by surface |\n| TypeScript SDK | **Published + source** | npm package plus monorepo source; source may be ahead |\n| Python SDK | **Source-only** | Use a pinned repository revision for production integration |\n| `execution_sync*` | **Shadow** | Read-only calibration/replay evidence; not routing authority |\n| `contracts/primitives/` | **Experimental / readiness-gated** | Presence in repo does not imply deployment or production dependency |\n\nThe canonical definitions and version caveats are in [Product Status](docs/product-status.md).\n\n---\n\n## Security model for builders\n\nSuwappu moves money, so the security boundary belongs next to the integration flow—not at the bottom of the docs.\n\n- Keep credentials out of source and logs.\n- Prefer runtime discovery plus an **application-owned allowlist** of tools/capabilities.\n- Treat model output and third-party text as untrusted input to execution policy.\n- Simulate unfamiliar routes before enabling execution.\n- Keep self-custody signing separate from managed execution.\n- Add explicit spend/value/destination policies before granting an agent Level 3 or 4 capability.\n- Treat signing, custody, routing, withdrawals, fee collection, and authorization changes as MONEY-PATH code requiring adversarial review.\n\nRead [SECURITY.md](SECURITY.md) and the [agent security baseline](docs/agent-clients.md#security-baseline-for-builders). The checked-in [CycloneDX SBOM](sbom/suwappubot.cdx.json), CodeQL, and OpenSSF tooling are security evidence—not an audit or compliance certification.\n\n---\n\n## Engineering contracts\n\nFast-moving infrastructure becomes unreliable when docs, config, and deployment state each invent their own truth. Suwappu keeps important facts in versioned contracts:\n\n| Contract | Source of truth for |\n|---|---|\n| [`stats.generated.json`](showcase/src/data/stats.generated.json) | Public chain/router counts |\n| [`.env.schema`](.env.schema) | Environment-variable contract |\n| [`capabilities.yaml`](capabilities.yaml) | Optional capability/provider manifest |\n| [`ARCHITECTURE.md`](ARCHITECTURE.md) | Normative system boundaries |\n| [`docs/adr/`](docs/adr/README.md) | Architecture decisions |\n| [`docs/deployment/production-inventory.md`](docs/deployment/production-inventory.md) | Current production service catalog snapshot |\n| [`docs/product-status.md`](docs/product-status.md) | Maturity and publication semantics |\n\nDocs-only changes can be checked with:\n\n```bash\n./scripts/verify.sh docs\n```\n\nFor local setup and component-specific test lanes, use [ONBOARDING.md](docs/ONBOARDING.md).\n\n---\n\n## Repository map\n\n```text\nsuwappubot/\n├── api-ts/ # Agent REST, MCP, A2A, webapp and execution routes\n├── api/ # Python FastAPI entry points\n├── bot/ # Bot, execution engine, services, workers, models\n├── webapp/ # React/Vite application\n├── terminal/ # Trading terminal / Mini App\n├── mobile/ # Expo iOS client\n├── extension/ # Browser wallet extension\n├── showcase/ # Public website, products, research, generated stats\n├── contracts/ # Solidity contracts and protocol primitives\n├── packages/ # SDKs, MCP bridge, OpenClaw, design tokens\n├── docs/ # Product, architecture, security, operations, research\n├── database/ # Schema/bootstrap and runtime migrations\n├── scripts/ # Verification, replay, maintenance, ops tooling\n├── monitoring/ # Health/monitoring manifests\n├── sbom/ # CycloneDX software bill of materials\n└── .github/workflows/ # CI, security and deployment workflows\n```\n\n---\n\n## Documentation\n\n| Resource | Use it for |\n|---|---|\n| [Quickstart](docs/quickstart.md) | First successful user/agent/app integration |\n| [Agent clients](docs/agent-clients.md) | MCP, SDK, REST, A2A, auth and custody semantics |\n| [Product status](docs/product-status.md) | Production vs hosted vs source-only vs shadow vs experimental |\n| [Feature guides](docs/features/README.md) | User-facing capability workflows |\n| [Architecture](docs/architecture/OVERVIEW.md) | Runtime boundaries and request/data flows |\n| [Production inventory](docs/deployment/production-inventory.md) | Railway service-catalog snapshot |\n| [ADRs](docs/adr/README.md) · [Decisions](docs/DECISIONS.md) | Why important choices exist |\n| [Onboarding](docs/ONBOARDING.md) · [Contributing](CONTRIBUTING.md) | Work on the monorepo |\n| [Security](SECURITY.md) · [Support](SUPPORT.md) | Vulnerabilities and help |\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE).\n", "bytes": 15441, "sha": "98efc1c7caaebac50f85efa7dfe1d6a1978a70e8579536047ce0d2b687507cfa", "repo_slug": "0xsoftboi/suwappubot", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_0xsoftboi_suwappu_57c60b34/readme" }