Suwappu

Cross-chain DEX infrastructure for humans and AI agents.
Swap tokens across 45 chains via Telegram, WhatsApp, Discord, a web terminal, or a programmatic API.

Trade now  ·  Open Terminal  ·  Telegram Bot  ·  Agent Docs  ·  Security

Overview

45 chains. 19 swap providers. 3 agent protocols. 5 frontends.

Architecture

flowchart LR
    subgraph Clients["Entry Points"]
        TG["Telegram Bot"]
        WA["WhatsApp"]
        DC["Discord"]
        AI["AI Agents\nMCP + A2A + REST"]
        Web["Webapp + Terminal"]
        Ext["Browser Extension"]
    end

    subgraph Backend["Backend"]
        Bot["Python Monolith\nSwap Engine · 60+ Handlers\n120+ Services"]
        API["TypeScript API\nHono + Effect-TS\n50+ Endpoints"]
    end

    subgraph Providers["19 Swap Providers"]
        EVM["EVM Chains"]
        SOL["Solana"]
        TRON["TRON"]
    end

    TG & WA & DC --> Bot
    AI & Web & Ext --> API
    Bot --> API
    API --> EVM & SOL & TRON
    Bot --> EVM & SOL & TRON

Features

Trading

• Cross-chain swaps — 19 providers, chain-gated per route and raced in parallel, best-price selection, slippage protection
• MEV protection — CoW Protocol batch auctions (EVM) + Jito bundles (Solana)
• Limit orders — Buy/sell triggers, stop-loss, trailing stop with expiry
• DCA orders — Dollar-cost averaging on daily/weekly/monthly intervals
• Token sniping — Pump.fun + Raydium launch detection, instant/conditional/first-block modes
• Perpetuals — HyperLiquid integration (1-20x leverage, TP/SL, position monitoring)
• Copy trading — Follow up to 5 traders, auto-mirror swaps, PnL leaderboard

Security

• Anti-rug engine — Safety scoring (0-100), honeypot detection, mint/freeze authority checks, blacklist, liquidity analysis
• Transaction simulation — Simulate before execution
• Wallet encryption — AES-256-GCM envelope encryption with AWS KMS (auto-migrates from legacy Fernet)
• Turnkey TEE wallets — Hardware-isolated key management with sub-org policies
• 2FA — TOTP (Google Authenticator compatible) with configurable threshold (default $1,000+)
• Spending limits — Per-swap ($5K), hourly ($10K), daily ($50K) — user-customizable
• Withdrawal whitelisting — Pre-approved addresses with 24h cooldown

Agent Integration

Framework toolkits: LangChain · CrewAI · OpenClaw (zero-code, native MCP). Add Suwappu to any OpenClaw agent in one command:

openclaw mcp add suwappu --url https://api.suwappu.bot/mcp \
  --transport streamable-http \
  --header "Authorization=Bearer $SUWAPPU_API_KEY" --exclude execute_swap

See docs/features/openclaw_integration.md.

Engagement

• Points/XP system — Levels (Bronze → Platinum), daily check-ins, milestones, reward store
• 3-tier referrals — 30% fee share to referrers
• Subscription tiers — Free / Pro ($9.99) / Premium ($29.99) / Enterprise ($99.99) with rate limits
• x402 micropayments — Token-gated access protocol
• Tax export — CSV/JSON yearly reports with cost-basis tracking

Multi-Platform

Quick Start

MCP (Claude Desktop / Cursor)

Add to your Claude Desktop config:

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

For stdio-only clients, repository source packages/mcp-server contains the 0.6.0 forwarding bridge. The npm release is still 0.1.1, so use hosted MCP for the current catalog until 0.6.0 is published.

A2A (Agent-to-Agent)

# Discover capabilities
curl https://api.suwappu.bot/.well-known/agent.json

# Natural-language quote (`swap` wording is quote-only in A2A)
curl -X POST https://api.suwappu.bot/a2a \
  -H "Authorization: Bearer suwappu_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"message/send","params":{"message":{"kind":"message","role":"user","parts":[{"kind":"text","type":"text","text":"swap 0.5 ETH to USDC on base"}]}}}'

Local Development

# TypeScript API
cd api-ts && bun install && bun run dev

# Webapp
cd webapp && npm install && npm run dev

# Bot (Python)
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload

Each service needs its own .env — see .env.schema for the full contract and python3 scripts/doctor.py to check what's configured locally.

Swap Routing

The SwapEngine races all eligible providers for a given route in parallel and returns the best output amount — it's quote comparison, not a fixed priority list:

Request → Pre-checks (spending limits, safety score, MEV config)
        → SwapEngine: race eligible providers in parallel, pick best output
           Same-chain EVM   — CoW Protocol (MEV-protected batch auctions), OKX DEX,
                              1inch, KyberSwap, 0x, Li.Fi
           Solana           — Jupiter + Jito (MEV bundle protection)
           Cross-chain      — Socket, Li.Fi, Circle CCTP (USDC), Across, Wormhole,
                              LayerZero, Chainlink CCIP
           Chain-specific   — SunSwap (TRON), plus other per-chain DEX integrations
        → Points-based fee discount (up to 50%)

Supported Chains

The table below highlights the original launch chains. The canonical list of all 45 mainnet chains lives in bot/config/chains.py, drift-checked into showcase/src/data/stats.generated.json (18 of them are served on the agent API).

Bot Commands

Core commands below — the bot has grown to 60+ handlers (savings, borrow, P2P, bulk pay, airdrops, gift cards, and more); see docs/features/README.md for the fuller map, or /start in the bot for the current menu.

Project Structure

suwappubot/
├── api-ts/             # TypeScript API (Hono + Effect-TS + Drizzle)
│   └── src/
│       ├── routes/     # 22 route modules, 50+ endpoints
│       ├── services/   # Services (swap, agent, perps, lending, etc.)
│       └── middleware/  # Auth (bearer, telegram, flex, admin, internal)
├── bot/                # Python Telegram bot
│   ├── handlers/       # 60+ command handlers
│   ├── services/       # 120+ services (swap engine, sniping, copy, security)
│   └── config/         # Chain configs, token configs, settings
├── api/                # Python FastAPI (webhook handlers)
├── webapp/             # React + Vite Telegram Mini App — 29 pages, dev-only, not deployed
├── terminal/           # Live Telegram Mini App (app.suwappu.bot) — 20+ panels, TradingView
├── extension/          # Browser wallet extension (MV3, EIP-1193/6963 + Wallet Standard)
├── showcase/           # Marketing site (Next.js)
├── contracts/          # SUWP token + on-chain harness (Solidity)
├── cloudflare/         # Cloudflare Worker (router)
├── packages/
│   ├── shared/         # Shared TypeScript types
│   ├── sdk/            # @suwappu/sdk (npm, published)
│   ├── mcp-server/     # @suwappu/mcp-server stdio -> hosted MCP bridge
│   ├── openclaw/       # @suwappu/openclaw (npm, published)
│   ├── design-tokens/  # @suwappu/design-tokens
│   └── sdk-python/     # Python SDK (development)
├── gitbook/            # API documentation (50+ files)
├── infra/              # AWS CDK — legacy, unused for app deploys (see Deployment)
├── database/           # DB init + runtime migrations
├── docs/               # Architecture, deployment, and feature docs
├── skills/             # Claude Code skills for this repo
├── monitoring/         # External health-check endpoint manifest
├── tests/              # Python tests
└── .github/workflows/  # CI/CD

packages/mcp-server source is vendored here and can be ahead of the published npm release; see the package README for the current version boundary.

API Endpoints (TypeScript)

npm Packages

Versions above are the current npm releases. Package source in this monorepo may be ahead while the next release is being prepared.

Deployment

Deploy target is Railway — there is no AWS/ECS/EC2 deploy path anymore. Railway is wired to GitHub, so merging to main/dev auto-deploys any service whose watched paths changed. See docs/deployment/railway.md and the /deploy skill. (The AWS Dockerfiles/CDK under infra/ are left in place for reversibility, not because they're live.)

webapp/ is unused in production — it has no Railway service and deploys nowhere. The live Telegram Mini App (app.suwappu.bot) is served by terminal/.

Development env uses the same services on the dev branch, e.g. devapi.suwappu.bot for api-ts.

CI/CD: GitHub Actions auto-deploys on push to main/dev (see docs/deployment/monitoring.md for how each layer's health is checked post-deploy).

Security

• Wallet encryption — AES-256-GCM envelope encryption with AWS KMS
• Turnkey TEE — Hardware-isolated key management
• 2FA — TOTP with backup codes, configurable threshold
• Spending limits — Per-swap, hourly, daily (user-customizable)
• Anti-rug — Safety scoring, honeypot detection, authority checks, emergency auto-sell
• Token analysis — GoPlus Security API integration
• Transaction simulation — Simulate before executing
• Withdrawal whitelisting — 24h cooldown for new addresses
• Audit logging — All security-sensitive actions logged

Report vulnerabilities to security@suwappu.bot — see SECURITY.md.

Supply chain

We practice continuous open-source dependency scanning and ship a checked-in Software Bill of Materials (SBOM).

• Checked-in SBOM. A CycloneDX SBOM lives at sbom/suwappubot.cdx.json — every dependency across every ecosystem in this monorepo (Python, npm, bun), deduplicated. Generated with Syft, which auto-detects every package manifest/lockfile in the tree; nothing is hand-authored.

  Regenerate the SBOM:

  Terminal

  Copy

  curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin
  syft . -o cyclonedx-json=sbom/suwappubot.cdx.json
  

• CI workflows (SHA-pinned). Two additive workflows live under .github/workflows/:

  • sbom.yml — on each published Release, regenerates the CycloneDX SBOM with Syft and attaches it as a Release asset.
  • scorecard.yml — weekly + on push to main, runs OpenSSF Scorecard and uploads SARIF to the repo Security tab.

  Both workflows pin every action to a full commit SHA (a stricter convention than this repo's other workflows, deliberately — a supply-chain-security workflow pinning its own dependencies loosely would undercut the point). This repo's Actions billing is active, so both run for real starting with the first push/release after merge — not dormant pending billing, unlike the initial rollout on other Suwappu satellite repos.

  Not audited, not SOC 2 — this is dependency-inventory tooling (what's in the tree and how it's fetched), not a security certification. See SECURITY.md for the actual security posture and vulnerability-reporting process.

Documentation

Governance

Links

• Webapp: https://app.suwappu.bot
• API: https://api.suwappu.bot
• Showcase: https://www.suwappu.bot
• Telegram Bot: @SuwappuBot
• Agent Card: https://api.suwappu.bot/.well-known/agent.json