# suwappu
**Category:** ๐ป Developer Tools
**Repository:** https://github.com/0xSoftBoi/suwappubot
**Views:** 0
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/suwappu
## Description
Cross-chain DEX for AI agents. Swap tokens across 7+ chains.
## Claude Desktop Quick Installation
Heuristic fallback โ verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):
```json
"mcpServers": {
"suwappu": {
"command": "npx",
"args": ["-y","suwappu"]
}
}
```
## Documentation & README
Suwappu
[](https://www.suwappu.bot)
[](.github/workflows/test.yml)
[](.github/workflows/codeql.yml)
[](.github/workflows/scorecard.yml)
[](LICENSE)
[](showcase/src/data/stats.generated.json)
[](showcase/src/data/stats.generated.json)
[](docs/agent-clients.md)
[](api-ts/agent-card.json)
[](https://clawhub.ai/0xsoftboi/suwappu-dex)
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
**[www.suwappu.bot](https://www.suwappu.bot)** โ marketing site, embedded terminal preview
|
**[terminal.suwappu.bot](https://terminal.suwappu.bot)** โ the live Telegram Mini App: chart, order book, swap/limit/DCA, portfolio
|
---
Table of contents
1. [Overview](#overview)
2. [Architecture](#architecture)
3. [Features](#features)
4. [Quick Start](#quick-start)
5. [Swap Routing](#swap-routing)
6. [Supported Chains](#supported-chains)
7. [Bot Commands](#bot-commands)
8. [Project Structure](#project-structure)
9. [API Endpoints (TypeScript)](#api-endpoints-typescript)
10. [npm Packages](#npm-packages)
11. [Deployment](#deployment)
12. [Security](#security)
13. [Documentation](#documentation)
14. [Links](#links)
---
## Overview
**45 chains. 19 swap providers. 3 agent protocols. 5 frontends.**
| | |
|---|---|
| **Chains** | 45 mainnet chains โ EVM + Solana + TRON + Starknet (canonical list: `bot/config/chains.py`; 18 served on the agent API) |
| **Swap Providers** | 19 routing providers โ 0x, 1inch, Across, AVNU, CCIP, CCTP, CoW, GoatSwap, JuiceSwap, Jupiter, KyberSwap, LayerZero, Li.Fi, OKX, Socket, SunSwap, Tempo DEX, usdt0, Wormhole (chain-gated per route; source of truth: `showcase/src/data/stats.generated.json`) |
| **Agent Protocols** | REST API (50+ endpoints) ยท MCP (22 tools) ยท A2A (JSON-RPC) |
| **Platforms** | Telegram Bot ยท WhatsApp ยท Discord ยท Web Terminal ยท Browser Extension |
| **SDKs** | [`@suwappu/sdk`](https://www.npmjs.com/package/@suwappu/sdk) ยท [`@suwappu/mcp-server`](https://www.npmjs.com/package/@suwappu/mcp-server) ยท Python SDK |
---
## Architecture
```mermaid
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
| Protocol | Endpoint | Tools/Skills |
|----------|----------|-------------|
| **REST API** | `/v1/agent/*` | 50+ endpoints โ swaps, wallets, portfolio, perps, predictions, lending, webhooks |
| **MCP** | `/mcp` | 22 tools โ quotes, swaps, portfolio, perps, predictions, lending, wallet policies, and more |
| **A2A** | `/a2a` | Natural-language quotes/prices/discovery โ `swap ...` returns a quote; no A2A execution method |
**Framework toolkits:** [LangChain](https://github.com/0xSoftBoi/suwappu-langchain) ยท [CrewAI](https://github.com/0xSoftBoi/suwappu-crewai-crew) ยท **[OpenClaw](packages/openclaw/SKILL.md)** (zero-code, native MCP). Add Suwappu to any OpenClaw agent in one command:
```bash
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](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
| Platform | Capabilities |
|----------|-------------|
| **Telegram** | Full feature set โ 60+ commands across 60+ handlers, Mini App, inline keyboards |
| **WhatsApp** | Swaps, orders, DCA, alerts, voice messages, conversation flows |
| **Discord** | Whale alerts, trending tokens, leaderboard, analysis forum |
| **Web Terminal** | TradingView charts, order book, 20+ panels, keyboard shortcuts |
| **Browser Extension** | MV3 wallet โ injects `window.ethereum`/`window.solana`, EIP-1193/6963 + Wallet Standard |
---
## Quick Start
### MCP (Claude Desktop / Cursor)
Add to your Claude Desktop config:
```json
{
"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)
```bash
# 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
```bash
# 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`](.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).
| Chain | ID | Native | Type | Swap Providers |
|-------|-----|--------|------|---------------|
| Ethereum | 1 | ETH | EVM | CoW, Socket, Li.Fi, Across, CCTP, CCIP, LayerZero |
| BSC | 56 | BNB | EVM | Socket, Li.Fi, Across, LayerZero |
| Polygon | 137 | MATIC | EVM | CoW, Socket, Li.Fi, Across, CCTP |
| Arbitrum | 42161 | ETH | EVM | CoW, Socket, Li.Fi, Across, CCTP, LayerZero |
| Optimism | 10 | ETH | EVM | CoW, Socket, Li.Fi, Across, CCTP, LayerZero |
| Base | 8453 | ETH | EVM | CoW, Socket, Li.Fi, Across, CCTP |
| Avalanche | 43114 | AVAX | EVM | Socket, Li.Fi, Across, CCTP |
| Fantom | 250 | FTM | EVM | Socket, Li.Fi |
| Linea | 59144 | ETH | EVM | Socket, Li.Fi |
| Mantle | 5000 | MNT | EVM | Socket, Li.Fi |
| Gnosis | 100 | xDAI | EVM | Socket, Li.Fi |
| Scroll | 534352 | ETH | EVM | Socket, Li.Fi |
| Solana | โ | SOL | Solana | Jupiter, Jito, Wormhole |
| TRON | โ | TRX | TRON | Li.Fi |
---
## 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](docs/features/README.md) for
the fuller map, or `/start` in the bot for the current menu.
| Command | Description |
|---------|-------------|
| `/s` | Quick swap โ `/s ` |
| `/w` | Wallet management (create/import EVM, Solana, TRON) |
| `/b` | Balances across all chains |
| `/p` | Portfolio overview with PnL |
| `/o` | Limit orders + DCA |
| `/snipe` | Token sniping (Pump.fun, Raydium) |
| `/perps` | Perpetuals (HyperLiquid, 1-20x) |
| `/traders` | Copy trading leaderboard |
| `/a` | Price alerts |
| `/hx` | Transaction history |
| `/xp` | Points, levels, rewards |
| `/checkin` | Daily check-in (streak bonus) |
| `/ref` | Referral program (30% fee share) |
| `/tax` | Tax export (CSV/JSON) |
| `/c` | Custodial deposits/withdrawals |
| `/sub` | Subscription tiers |
| `/set` | Settings (slippage, 2FA, limits, notifications) |
| `/g` | Gas tracker |
| `/f` | Favorite tokens |
---
## 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)
| Route Module | Auth | Key Endpoints |
|-------------|------|--------------|
| **Agent** (`/v1/agent/*`) | Bearer | register, quote, swap, execute, portfolio, prices, tokens, wallets, wallet policies, webhooks, key rotation |
| **Perps** (`/v1/agent/perps/*`) | Bearer | markets, quote, positions |
| **Predictions** (`/v1/agent/predict/*`) | Bearer | markets, market details (Polymarket) |
| **Lending** (`/v1/agent/lend/*`) | Bearer | markets, market details (Morpho) |
| **MCP** (`/mcp`) | Bearer | 22 tools via JSON-RPC |
| **A2A** (`/a2a`) | Bearer | message/send, tasks/get, tasks/cancel |
| **Webapp Swap** (`/webapp/swap/*`) | Telegram | quote, execute, status, chains, tokens |
| **Webapp Auth** (`/webapp/*`) | Various | validate, telegram auth, Turnkey OAuth, trending, token info/chart |
| **Public** (`/public/swap/*`) | Optional | chains, tokens, quote, execute, status (rate-limited) |
| **Admin** (`/admin/*`) | Admin key | stats, agents, swaps, webhooks |
| **Internal** (`/internal/*`) | Internal key | Service-to-service swap, user, events, payment verification |
| **Health** (`/health`) | None | Health + DB connectivity |
---
## npm Packages
| Package | Version | Description |
|---------|---------|-------------|
| [`@suwappu/sdk`](https://www.npmjs.com/package/@suwappu/sdk) | 0.4.0 | TypeScript SDK + `suwappu` CLI |
| [`@suwappu/mcp-server`](https://www.npmjs.com/package/@suwappu/mcp-server) | 0.1.1 | MCP server for Claude Desktop/Cursor |
| [`@suwappu/openclaw`](https://www.npmjs.com/package/@suwappu/openclaw) | 0.2.0 | OpenClaw skill module |
> 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](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/`.
| Service | Production URL | Branch |
|---------|-----------------|--------|
| `python-api` (bot + FastAPI) | python-api-*.up.railway.app (no custom domain) | `main` |
| `api-ts` | api.suwappu.bot | `main` |
| `terminal` (live Mini App) | app.suwappu.bot ยท terminal.suwappu.bot | `main` |
| `showcase` | www.suwappu.bot | `main` |
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](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](./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](https://cyclonedx.org/) SBOM lives
at [`sbom/suwappubot.cdx.json`](./sbom/suwappubot.cdx.json) โ
every dependency across every ecosystem in this monorepo (Python,
npm, bun), deduplicated. Generated with
[Syft](https://github.com/anchore/syft), which auto-detects every
package manifest/lockfile in the tree; nothing is hand-authored.
Regenerate the SBOM:
```sh
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`](./.github/workflows/sbom.yml) โ on each published
Release, regenerates the CycloneDX SBOM with Syft and attaches it
as a Release asset.
- [`scorecard.yml`](./.github/workflows/scorecard.yml) โ weekly +
on push to `main`, runs [OpenSSF Scorecard](https://securityscorecards.dev/)
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](./SECURITY.md) for the actual
security posture and vulnerability-reporting process.
---
## Documentation
| Resource | Description |
|----------|-------------|
| [GitBook API Docs](gitbook/) | Full API reference (50+ files) |
| [Agent Clients](docs/agent-clients.md) | MCP, A2A, REST setup for AI agents |
| [Features](docs/features/README.md) | User-facing feature guides (HyperLiquid, Tempo, etc.) |
| [Deployment](docs/deployment/) | Railway, CI/CD, monitoring |
| [CLAUDE.md](CLAUDE.md) | Local setup, build commands, migrations, architecture gotchas |
### Governance
| Resource | Description |
|----------|-------------|
| [ARCHITECTURE.md](ARCHITECTURE.md) | System boundaries, decision taxonomy, standing decisions |
| [CONVENTIONS.md](CONVENTIONS.md) | Toolchain, git, code, testing, and naming rules |
| [AGENTS.md](AGENTS.md) | Policy for AI agents working in this repo |
| [CONTRIBUTING.md](CONTRIBUTING.md) ยท [SUPPORT.md](SUPPORT.md) ยท [SECURITY.md](SECURITY.md) | Contributing, getting help, vulnerability reporting |
| [CHANGELOG.md](CHANGELOG.md) | Notable changes |
| [`.env.schema`](.env.schema) ยท [`capabilities.yaml`](capabilities.yaml) | Generated env contract ยท optional-provider manifest (`python3 scripts/doctor.py` to probe) |
---
## Links
- **Webapp:** https://app.suwappu.bot
- **API:** https://api.suwappu.bot
- **Showcase:** https://www.suwappu.bot
- **Telegram Bot:** [@SuwappuBot](https://t.me/SuwappuBot)
- **Agent Card:** https://api.suwappu.bot/.well-known/agent.json
