io.github.persistenceOne/bridgekitty

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/bridgekitty@0.3.9

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

What's New in v0.3.0

• 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

What's New in v0.2.0

• 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

Bridge Directions

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.

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

MCP Tools

Core Bridge Tools

Multi-hop & Discovery

Wallet Tools

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