BridgeKitty 🐱

Cross-chain bridge aggregator MCP server for AI agents. One server, 5 bridge backends, best routes across EVM, Solana, and Cosmos chains.

BridgeKitty gives AI agents (Claude, Cursor, GPT, or any MCP-compatible AI) the ability to find and execute cross-chain bridge transfers — with automatic route optimization, fee comparison, balance checks, and safety warnings.

Latest npm release: @persistenceone/[email protected]

What's New in v0.3.9

• XPRT tools extracted — staking, rewards, and farming tools moved to the standalone xprt-farming-toolkit package
• Persistence Interop backend removed — BridgeKitty is now a focused bridge aggregator across 5 backends (deBridge, Relay, LI.FI, Across, Squid)
• Slimmer surface area — fewer tools, clearer scope for agents

• sign_and_send parameter — agents can now sign and broadcast transactions directly using locally-stored wallet keys
• Full EVM signing support — works with all EVM backends (Across, Relay, LI.FI, Squid, deBridge) + Persistence Interop (EIP-712)
• Simulation fix — ERC20 bridges now work on fresh wallets (previously blocked by premature simulation)
• Solana signing — coming in next release

• Solana support — bidirectional bridging EVM ↔ Solana (native SOL delivery, not wrapped)
• Cosmos support — EVM → Persistence/Cosmos Hub via Squid (Axelar)
• Protocol fee transparency — deBridge fixFee, operating expenses, and total cost visible in every quote
• Balance warnings — warns when wallet can't cover bridge amount + protocol fees + gas
• XPRT staking — stake/unstake/claim rewards directly from the MCP server
• Farming multiplier — tracks your staking tier (1x → 3x → 5x) from the rewards API
• Quote auto-refresh — expired quotes automatically re-fetched on execute (60s expiry)
• ERC-20 approvals — always generated for token bridges (Relay + deBridge)
• Bridge status tracking — on-chain fallback when provider API hasn't indexed yet

Supported Bridges

| Backend | Type | Chains | Strength | |---------|------|--------|----------| | deBridge (DLN) | Direct | EVM + Solana | Fast intent-based fills, Solana support | | Relay | Direct | EVM + Solana | No protocol fee, gas-optimized | | LI.FI | Aggregator | EVM | Widest coverage (30+ bridges, any-to-any swap) | | Across | Direct | EVM | Fastest fills (~6s), same-token bridging | | Squid (Axelar) | Aggregator | EVM + Cosmos | Only option for EVM → Cosmos routes |

Bridge Directions

| Direction | Backends | Status | |-----------|----------|--------| | EVM → EVM | All 5 | ✅ Production | | EVM → Solana | deBridge, Relay | ✅ Production | | Solana → EVM | deBridge | ✅ Production | | EVM → Cosmos | Squid | ✅ Production |

Quick Start

npx (zero install)

npx @persistenceone/bridgekitty

Claude Code

Add to your MCP config (~/.claude/claude_code_config.json):

{
  "mcpServers": {
    "bridgekitty": {
      "command": "npx",
      "args": ["@persistenceone/bridgekitty"]
    }
  }
}

Cursor IDE

Add to Cursor's MCP settings (Settings > MCP Servers):

{
  "bridgekitty": {
    "command": "npx",
    "args": ["@persistenceone/bridgekitty"]
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "bridgekitty": {
      "command": "npx",
      "args": ["@persistenceone/bridgekitty"]
    }
  }
}

Wallet Setup

BridgeKitty can manage wallets for autonomous bridging. Run wallet_setup to create wallets for EVM, Cosmos, and Solana — or provide your own addresses in quotes.

Wallet config is stored in ~/.bridgekitty/.env (or the directory you run from). Keys never leave the local machine.

| Variable | Description | |----------|-------------| | PRIVATE_KEY | EVM private key (hex) | | MNEMONIC | BIP-39 mnemonic (derives EVM, Cosmos, Solana keys) | | SOLANA_PRIVATE_KEY | Solana private key (base58) |

Transaction Signing

By default, bridge_execute returns unsigned transactions for the agent or user to sign externally.

Set sign_and_send: true to enable autonomous signing — BridgeKitty will use the wallet keys stored in ~/.bridgekitty/.env to handle the full flow:

1. Approval — sends ERC-20 approval transaction (if needed)
2. Re-build — re-fetches the bridge transaction with updated nonce (if approval was sent)
3. Simulate — runs eth_estimateGas pre-flight check
4. Sign — signs the transaction with the local private key
5. Broadcast — submits to the chain and returns the tx hash + explorer link

Optional API Keys

| Variable | Description | |----------|-------------| | LIFI_API_KEY | LI.FI API key (higher rate limits) | | DEBRIDGE_API_KEY | deBridge API key | | SQUID_INTEGRATOR_ID | Squid integrator ID |

MCP Tools

Core Bridge Tools

| Tool | Description | |------|-------------| | bridge_get_quote | Get competitive quotes from all backends. Shows fees, time estimates, balance warnings. | | bridge_execute | Build transaction(s) from a quote. Handles approvals, auto-refreshes expired quotes. Set sign_and_send: true to auto-sign and broadcast. | | bridge_status | Track bridge progress. On-chain fallback when API hasn't indexed yet. | | bridge_chains | List supported chains with provider coverage. | | bridge_tokens | Search tokens on a chain. |

Multi-hop & Discovery

| Tool | Description | |------|-------------| | bridge_quote_multi | Multi-hop route resolution when no direct route exists. | | bridgekitty_help | Agent onboarding guide with examples and tool usage. | | xprt_onboard | Guided onboarding flow for first-time users. |

Wallet Tools

| Tool | Description | |------|-------------| | wallet_setup | Create wallets for EVM, Cosmos, Solana from a single mnemonic. | | wallet_import | Import an existing wallet from a mnemonic or private key. | | wallet_status | Show configured wallet addresses and key source. | | wallet_balance | Check balances across all chains with USD prices (CoinGecko). |

XPRT staking & farming has moved to the standalone xprt-farming-toolkit package.

Example: Bridge USDC from Base to Arbitrum

Default (unsigned transactions)

Agent: "Bridge 100 USDC from Base to Arbitrum"

→ bridge_get_quote: Gets quotes from deBridge, Relay, LI.FI, Across
→ Shows: best rate, fees, estimated time, balance check
→ bridge_execute: Builds approval tx + bridge tx
→ Agent signs and sends both transactions
→ bridge_status: Tracks until destination confirmed

With sign_and_send (autonomous signing)

Agent: "Bridge 100 USDC from Base to Arbitrum"

→ bridge_get_quote: Gets quotes from all backends
→ bridge_execute with sign_and_send: true
  → Auto-signs approval tx + bridge tx using local wallet keys
  → Returns tx hash + explorer link
→ bridge_status: Tracks until destination confirmed

Architecture

Agent → MCP Tools → Routing Engine → [deBridge, Relay, LI.FI, Across, Squid]
                         ↓
                   Quote Cache (60s) + Circuit Breaker
                         ↓
                   Best Quote → buildTransaction
                         ↓
              ┌──────────┴──────────┐
              ↓                     ↓
        Unsigned TX          Signed + Broadcast
         (default)            (sign_and_send)

• Routing Engine: Parallel quotes from all backends, ranked by output amount
• Circuit Breaker: Auto-skips failing backends, gradual recovery
• Token Registry: 45+ verified tokens with canonical addresses per chain
• Gas Estimator: Chain-aware gas cost estimation with multi-RPC failover
• Balance Checker: Validates token + native balance for fees before execution
• Fee Transparency: Protocol fees (deBridge fixFee, operating expenses) surfaced in every quote

Security

• Exact-amount approvals only (never unlimited)
• Transaction simulation before execution
• Verified token registry prevents address spoofing
• No private keys in MCP protocol — agents sign transactions externally
• sign_and_send uses locally-stored keys only (never transmitted over the network)
• Circuit breaker prevents cascading failures
• Error messages sanitized (no key/path leakage)
• .env file permission checks + overwrite protection

Known Limitations

• Solana → EVM returns a serialized transaction for external signing (no auto-execute)
• Relay status tracking may show "unknown" for completed cross-chain bridges
• Solana SPL tokens not yet shown in wallet_balance (only native SOL)
• Cosmos → EVM bridging not yet supported (only EVM → Cosmos)

License

MIT