BankrBot · alexn-symbiosis · Mar 7, 2026 · Mar 10, 2026
diff --git a/symbiosis/SKILL.md b/symbiosis/SKILL.md
@@ -0,0 +1,156 @@
+---
+name: symbiosis
+description: Cross-chain token swaps across 54+ blockchains via Symbiosis protocol. Use when the user wants to swap or bridge tokens between any chains — Base, Ethereum, Polygon, Arbitrum, Optimism, BNB Chain, Avalanche, Solana, Bitcoin, TON, Tron, and 40+ more. Supports any-to-any token swaps with automatic routing. Uses Bankr Submit API to execute transactions.
+metadata:
+  {
+    "clawdbot":
+      {
+        "emoji": "🔀",
+        "homepage": "https://symbiosis.finance",
+        "requires": { "bins": ["python3", "bankr"] },
+      },
+  }
+---
+
+# Symbiosis
+
+Cross-chain token swaps across 54+ blockchains. Swap any token on any chain to any token on any other chain.
+
+## When To Use
+
+Use Symbiosis when the user wants to:
+- **Bridge or swap tokens between different chains** (e.g., USDC from Base to Polygon, ETH from Ethereum to Arbitrum)
+- **Access chains beyond Bankr's native 5** (Arbitrum, Optimism, BNB Chain, Avalanche, zkSync, Linea, Scroll, Mantle, Blast, and 40+ more)
+- **Swap to/from Bitcoin, TON, or Tron**
+- **Get a cross-chain quote** without executing
+
+## Quick Start
+
+### Get a Quote
+
+```
+How much USDC will I get on Polygon if I bridge 10 USDC from Base?
+```
+
+Run the quote script:
+
+```bash
+scripts/symbiosis-quote.py 8453 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 6 10 137 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359 6
+```
+
+### Execute a Swap
+
+```
+Bridge 2 USDC from Base to Polygon using Symbiosis
+```
+
+Run the swap script:
+
+```bash
+scripts/symbiosis-swap.py 8453 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 6 2 137 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359 6
+```
+
+## Script Usage
+
+### symbiosis-swap.py
+
+Executes a full cross-chain swap: gets quote from Symbiosis API, approves token if needed, submits swap transaction via Bankr Submit API.
+
+```
+scripts/symbiosis-swap.py <src_chain_id> <src_token_address> <src_decimals> <amount> <dst_chain_id> <dst_token_address> <dst_decimals> [slippage]
+```
+
+- `amount` — human-readable (e.g., "2" for 2 USDC, "0.1" for 0.1 ETH)
+- `slippage` — optional, in basis points (default: 200 = 2%)
+- Reads Bankr API key from `~/.bankr/config.json`
+- Automatically gets wallet address from Bankr
+- Outputs transaction hash and Explorer tracking link
+
+### symbiosis-quote.py
+
+Gets a quote without executing. Same arguments, no slippage parameter.
+
+```
+scripts/symbiosis-quote.py <src_chain_id> <src_token_address> <src_decimals> <amount> <dst_chain_id> <dst_token_address> <dst_decimals>
+```
+
+## Common Chains and Tokens
+
+### Bankr Wallet Chains
+
+| Chain | ID | USDC Address | USDC Dec |
+|-------|----|-------------|----------|
+| Base | 8453 | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 | 6 |
+| Ethereum | 1 | 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 | 6 |
+| Polygon | 137 | 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359 | 6 |
+
+### Additional Chains via Symbiosis
+
+| Chain | ID | USDC Address | USDC Dec |
+|-------|----|-------------|----------|
+| Arbitrum | 42161 | 0xaf88d065e77c8cC2239327C5EDb3A432268e5831 | 6 |
+| Optimism | 10 | 0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85 | 6 |
+| BNB Chain | 56 | 0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d | 18 |
+| Avalanche | 43114 | 0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E | 6 |
+
+### Native Tokens
+
+Use `0x0000000000000000000000000000000000000000` as address for native gas tokens (ETH, POL, BNB, AVAX, etc.).
+
+**Reference**: [references/chains-and-tokens.md](references/chains-and-tokens.md) for the full list.
+
+## Examples
+
+### EVM to EVM
+
+```bash
+# 5 USDC: Base -> Arbitrum
+scripts/symbiosis-swap.py 8453 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 6 5 42161 0xaf88d065e77c8cC2239327C5EDb3A432268e5831 6
+
+# 0.01 ETH: Ethereum -> Base
+scripts/symbiosis-swap.py 1 0x0000000000000000000000000000000000000000 18 0.01 8453 0x0000000000000000000000000000000000000000 18
+
+# 10 USDC: Polygon -> BNB Chain
+scripts/symbiosis-swap.py 137 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359 6 10 56 0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d 18
+
+# 0.5 ETH: Base -> Optimism
+scripts/symbiosis-swap.py 8453 0x0000000000000000000000000000000000000000 18 0.5 10 0x0000000000000000000000000000000000000000 18
+```
+
+### Cross-ecosystem (Symbiosis-only routes)
+
+```bash
+# 10 USDC: Base -> Solana
+# Note: Solana chain ID in Symbiosis is 5426
+# Solana USDC: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v (but use Symbiosis synthetic address)
+scripts/symbiosis-swap.py 8453 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 6 10 5426 0x0000000000000000000000000000000000000000 9
+```
+
+### Prompt Examples
+
+Users might say:
+
+- "Bridge 5 USDC from Base to Arbitrum"
+- "Swap 0.1 ETH from Ethereum to Polygon"
+- "Move my USDC from Base to Optimism"
+- "How much will I get if I bridge 100 USDC from Base to Avalanche?"
+- "Cross-chain swap 50 USDC from Polygon to BNB Chain"
+- "Bridge ETH from Base to Solana"
+
+For each request: identify source chain + token, destination chain + token, look up chain IDs and token addresses from the tables above, and run the appropriate script.
+
+## How It Works
+
+1. **Quote**: Script calls Symbiosis API (`POST /crosschain/v1/swap`) with token details and wallet address
+2. **Approve**: If source token needs approval, script submits an ERC20 approve transaction via `POST https://api.bankr.bot/agent/submit`
+3. **Swap**: Script submits the swap transaction via `POST https://api.bankr.bot/agent/submit`
+4. **Track**: Returns an Explorer link for cross-chain status tracking
+
+All transactions are submitted through the Bankr Submit API using the user's Bankr wallet. No additional wallets or keys needed.
+
+## Resources
+
+- **Explorer**: https://explorer.symbiosis.finance
+- **Website**: https://symbiosis.finance
+- **API Docs**: [references/api-reference.md](references/api-reference.md)
+- **Chains & Tokens**: [references/chains-and-tokens.md](references/chains-and-tokens.md)
diff --git a/symbiosis/references/api-reference.md b/symbiosis/references/api-reference.md
@@ -0,0 +1,105 @@
+# Symbiosis API Reference
+
+Base URL: `https://api-v2.symbiosis.finance`
+
+## POST /crosschain/v1/swap
+
+Get a cross-chain swap quote with executable calldata.
+
+### Request
+
+```json
+{
+  "tokenAmountIn": {
+    "chainId": 8453,
+    "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    "decimals": 6,
+    "amount": "2000000"
+  },
+  "tokenOut": {
+    "chainId": 137,
+    "address": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
+    "decimals": 6
+  },
+  "from": "0xUserAddress",
+  "to": "0xUserAddress",
+  "slippage": 200,
+  "partnerId": "bankr"
+}
+```
+
+**Fields:**
+- `tokenAmountIn.amount` — amount in smallest units (e.g., "2000000" for 2 USDC with 6 decimals)
+- `slippage` — in basis points (200 = 2%, recommended default)
+- `partnerId` — always use "bankr"
+- `from` / `to` — user's wallet addresses (can be different for cross-chain)
+
+### Response
+
+```json
+{
+  "tx": {
+    "to": "0x691df9C4561d95a4a726313089c8536dd682b946",
+    "data": "0x...",
+    "value": "0",
+    "chainId": 8453
+  },
+  "approveTo": "0x41Ae964d0F61Bb5F5e253141A462aD6F3b625B92",
+  "tokenAmountOut": {
+    "address": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
+    "amount": "1497245",
+    "chainId": 137,
+    "decimals": 6
+  },
+  "fee": {
+    "amount": "250000",
+    "decimals": 6,
+    "priceUsd": 1.0
+  },
+  "estimatedTime": 32
+}
+```
+
+**Key fields:**
+- `tx` — the swap transaction to submit on the source chain
+- `approveTo` — if present, you must approve this spender before the swap
+- `tokenAmountOut.amount` — expected output in smallest units
+- `estimatedTime` — seconds until destination chain receives funds
+
+### Amount Conversion
+
+| Human Amount | Decimals | Smallest Units |
+|-------------|----------|---------------|
+| 2 USDC | 6 | "2000000" |
+| 0.1 ETH | 18 | "100000000000000000" |
+| 100 USDT | 6 | "100000000" |
+| 1.5 BNB | 18 | "1500000000000000000" |
+
+Formula: `amount_smallest = human_amount * 10^decimals`
+
+## POST /crosschain/v2/swap
+
+Bitcoin-specific endpoint. Returns a deposit address instead of calldata.
+
+### Response (Bitcoin)
+
+```json
+{
+  "depositAddress": "bc1q...",
+  "depositAddressExpiry": 1234567890,
+  "tokenAmountOut": { ... }
+}
+```
+
+The user sends BTC to `depositAddress` before `depositAddressExpiry`.
+
+## GET /crosschain/v1/chains
+
+Returns all supported chains.
+
+## Cross-Chain Status Tracking
+
+After submitting a swap transaction, track status at:
+`https://explorer.symbiosis.finance/transactions/<sourceChainId>/<txHash>`
+
+Typical completion: 15-60 seconds for most routes, up to 10 minutes for congested chains.
diff --git a/symbiosis/references/chains-and-tokens.md b/symbiosis/references/chains-and-tokens.md
@@ -0,0 +1,73 @@
+# Supported Chains and Common Tokens
+
+## Chains Supported by Both Bankr and Symbiosis
+
+| Chain | Chain ID | Native Token | Decimals |
+|-------|----------|-------------|----------|
+| Base | 8453 | ETH | 18 |
+| Ethereum | 1 | ETH | 18 |
+| Polygon | 137 | POL | 18 |
+| Unichain | 130 | ETH | 18 |
+| Solana | 5426 | SOL | 9 |
+
+## Additional Chains (Symbiosis-only, not native to Bankr)
+
+| Chain | Chain ID | Native Token | Decimals |
+|-------|----------|-------------|----------|
+| Arbitrum One | 42161 | ETH | 18 |
+| Optimism | 10 | ETH | 18 |
+| BNB Chain | 56 | BNB | 18 |
+| Avalanche C-Chain | 43114 | AVAX | 18 |
+| Gnosis | 100 | xDAI | 18 |
+| zkSync Era | 324 | ETH | 18 |
+| Linea | 59144 | ETH | 18 |
+| Scroll | 534352 | ETH | 18 |
+| Mantle | 5000 | MNT | 18 |
+| Blast | 81457 | ETH | 18 |
+| Mode | 34443 | ETH | 18 |
+| Sei | 1329 | SEI | 18 |
+| Gravity | 1625 | G | 18 |
+| ZetaChain | 7000 | ZETA | 18 |
+| Cronos | 25 | CRO | 18 |
+| Bitcoin | 3652501241 | BTC | 8 |
+| TON | 85918 | TON | 9 |
+| Tron | 728126428 | TRX | 6 |
+
+For the full list of 54+ chains, query: `GET https://api-v2.symbiosis.finance/crosschain/v1/chains`
+
+## Common Token Addresses
+
+### USDC
+
+| Chain | Address | Decimals |
+|-------|---------|----------|
+| Base (8453) | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 | 6 |
+| Ethereum (1) | 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 | 6 |
+| Polygon (137) | 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359 | 6 |
+| Arbitrum (42161) | 0xaf88d065e77c8cC2239327C5EDb3A432268e5831 | 6 |
+| Optimism (10) | 0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85 | 6 |
+| BNB Chain (56) | 0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d | 18 |
+| Avalanche (43114) | 0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E | 6 |
+
+### USDT
+
+| Chain | Address | Decimals |
+|-------|---------|----------|
+| Ethereum (1) | 0xdAC17F958D2ee523a2206206994597C13D831ec7 | 6 |
+| BNB Chain (56) | 0x55d398326f99059fF775485246999027B3197955 | 18 |
+| Polygon (137) | 0xc2132D05D31c914a87C6611C10748AEb04B58e8F | 6 |
+| Arbitrum (42161) | 0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9 | 6 |
+| Optimism (10) | 0x94b008aA00579c1307B0EF2c499aD98a8ce58e58 | 6 |
+| Avalanche (43114) | 0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7 | 6 |
+
+### Native Gas Tokens
+
+Use address `0x0000000000000000000000000000000000000000` with the appropriate decimals for the chain's native token (ETH=18, POL=18, BNB=18, SOL=9, BTC=8, etc.).
+
+## Bitcoin (Special)
+
+Bitcoin uses the Symbiosis v2 API (`/crosschain/v2/swap`) and returns a **deposit address** instead of calldata. The user must send BTC to the deposit address manually. The deposit address has an expiration time.
+
+## Solana (Special)
+
+Solana inbound swaps are limited to SOL and USDC as destination tokens. Outbound from Solana works for SOL and USDC as source.