# deBridge Agent Skills & MCP Server > Agent skills and MCP server for cross-chain DeFi — bridging, swapping, > signing, and monitoring across 20+ EVM chains and Solana. ## MCP Server Connect to the deBridge MCP endpoint — no install required: ``` https://agents.debridge.com/mcp ``` ## Install Skills ``` npx skills add debridge-finance/debridge-skills ``` ## On-Demand Fetch (fallback) For clients without a shell or JS environment, fetch skills directly by URL. Base URI: `https://agents.debridge.com` ### debridge-common - [debridge-common](https://agents.debridge.com/skills/common/SKILL.md): Shared prerequisite for all deBridge agent skills. - [MCP Server Configuration by Environment](https://agents.debridge.com/skills/common/mcp-setup.md) - [Supported Chains and Token Configuration](https://agents.debridge.com/skills/common/chain-config.md) - [RPC Endpoint Discovery via Chainlist](https://agents.debridge.com/skills/common/rpc-discovery.md) - [MCP Connection Methods](https://agents.debridge.com/skills/common/mcpc-usage.md) - [Skill Freshness Check](https://agents.debridge.com/skills/common/skill-freshness.md) Scripts: - https://agents.debridge.com/skills/common/scripts/allowance.ts - https://agents.debridge.com/skills/common/scripts/approve.ts - https://agents.debridge.com/skills/common/scripts/balance.ts - https://agents.debridge.com/skills/common/scripts/convert-amount.ts - https://agents.debridge.com/skills/common/scripts/env-keys.mjs - https://agents.debridge.com/skills/common/scripts/erc20.ts - https://agents.debridge.com/skills/common/scripts/rpc.mjs - https://agents.debridge.com/skills/common/scripts/rpc.ts ### debridge-analytics - [debridge-analytics](https://agents.debridge.com/skills/analytics/SKILL.md): Query DeFi analytics and on-chain data from third-party MCP servers to make informed bridging and swapping decisions. - [Token Prices and Market Data](https://agents.debridge.com/skills/analytics/token-prices.md) - [On-Chain Explorer — Address, Transaction, Contract, Portfolio](https://agents.debridge.com/skills/analytics/onchain-explorer.md) - [DeFi Protocol Analytics — TVL, Fees, Yields, Vault Risk](https://agents.debridge.com/skills/analytics/defi-tvl.md) - [DEX Pool Analytics — Liquidity, OHLCV, Trades](https://agents.debridge.com/skills/analytics/dex-pools.md) - [Balance Queries with ethers.js and viem](https://agents.debridge.com/skills/analytics/balance-ethers.md) - [Balance Queries with Foundry Cast](https://agents.debridge.com/skills/analytics/balance-cast.md) - [Balance Queries on Solana](https://agents.debridge.com/skills/analytics/balance-solana.md) Scripts: - https://agents.debridge.com/skills/analytics/scripts/balance-evm.mjs - https://agents.debridge.com/skills/analytics/scripts/balance-solana.mjs ### debridge-signing - [debridge-signing](https://agents.debridge.com/skills/signing/SKILL.md): Sign and broadcast deBridge transactions. - [deBridge Signing with OWS (Open Wallet Standard)](https://agents.debridge.com/skills/signing/ows-signing.md) - [Signing with ethers.js or viem](https://agents.debridge.com/skills/signing/sdk-signer.md) - [Signing with Foundry Cast](https://agents.debridge.com/skills/signing/foundry-cast.md) - [Browser Wallet Signing (MetaMask / EIP-1193)](https://agents.debridge.com/skills/signing/metamask.md) - [Signing via Privy MCP](https://agents.debridge.com/skills/signing/privy-mcp.md) Scripts: - https://agents.debridge.com/skills/signing/scripts/debridge-evm-bridge.mjs - https://agents.debridge.com/skills/signing/scripts/debridge-solana-bridge.mjs - https://agents.debridge.com/skills/signing/scripts/erc20-approve.mjs - https://agents.debridge.com/skills/signing/scripts/ows-solana-sign.mjs ### debridge-swap - [debridge-swap](https://agents.debridge.com/skills/swap/SKILL.md): Execute token swaps, bridges, and cross-chain transfers via deBridge DLN. - [Preflight Checks](https://agents.debridge.com/skills/swap/preflight.md) - [Order Monitoring and Fulfillment Tracking](https://agents.debridge.com/skills/swap/monitoring.md) ### debridge-wallets - [debridge-wallets](https://agents.debridge.com/skills/wallets/SKILL.md): Set up a wallet for deBridge transactions. - [Privy Embedded Wallet Setup](https://agents.debridge.com/skills/wallets/privy-embedded.md) - [deBridge Signing with OWS (Open Wallet Standard)](https://agents.debridge.com/skills/wallets/ows-signing.md) --- # Full Content > Below is the full content of every skill and reference document, > inlined so an LLM can consume everything in a single request. --- ## Source: skills/analytics/SKILL.md --- name: debridge-analytics description: > Query DeFi analytics and on-chain data from third-party MCP servers to make informed bridging and swapping decisions. Covers token prices and exchange data (CoinGecko, Crypto.com, mcp-crypto-price), on-chain lookups and multi-chain analytics (Blockscout, Hive Intelligence), protocol TVL, yields, and vault risk (DefiLlama, Philidor), and DEX pool liquidity (DexPaprika). All servers are free and require no API key. Use this skill whenever the user asks about token prices, wallet balances, portfolio overview, transaction history, protocol TVL, DEX liquidity, yield opportunities, orderbook depth, vault risk, or on-chain data. Also use for: "what's the price of ETH", "check my balance", "show me the TVL of Aave", "is there enough liquidity to swap", "look up this transaction", "what's the risk of this vault". license: MIT metadata: author: deBridge version: "0.1.0" --- # DeFi Analytics PREREQUISITE: Read ../common/SKILL.md for environment detection, auth, and chain configuration. Third-party MCP servers provide analytics data useful before, during, and after deBridge operations: token prices, wallet balances, protocol TVL, DEX liquidity, and on-chain transaction details. All analytics MCPs listed here are free and require no API key. ## Quick Reference | Want to... | MCP | Go to | |-----------------------------------------|------------------------------|----------------------------------------------------| | Get token prices and market data | CoinGecko, Crypto.com | [token-prices.md](token-prices.md) | | Look up address, tx, or contract | Blockscout, Hive | [onchain-explorer.md](onchain-explorer.md) | | Check protocol TVL, fees, yields | DefiLlama, Philidor | [defi-tvl.md](defi-tvl.md) | | Analyze DEX pools, OHLCV, trades | DexPaprika | [dex-pools.md](dex-pools.md) | | Assess DeFi vault risk | Philidor | [defi-tvl.md](defi-tvl.md) | | Cross-chain swap quotes and volume | SODAX | See sodax endpoint below | | Query balances directly (no MCP) | ethers, viem, cast, web3 | Direct Balance Queries below | --- ## Installing Analytics MCPs ### npx vs npm install Use **`npx`** for one-shot exploration — the package is fetched, executed once, and not retained: ```bash npx -y @coingecko/coingecko-mcp # try CoinGecko MCP npx -y @nic0xflamel/defillama-mcp-server # try DefiLlama MCP npx dexpaprika-mcp # try DexPaprika MCP npx -y mcp-crypto-price # try mcp-crypto-price MCP ``` Use **`npm install -g`** (or add to `devDependencies`) when building a persistent agent harness, a recurring script, or a long-lived process: ```bash npm install -g @coingecko/coingecko-mcp # always available, faster startup ``` | Scenario | Use | |---------------------------------------------|-------------| | First time trying an MCP | `npx -y` | | One-off query during a conversation | `npx -y` | | CI/CD pipeline, ephemeral environment | `npx -y` | | Agent harness running the MCP repeatedly | `npm install -g` or `devDependencies` | | Project with pinned MCP versions | `devDependencies` in `package.json` | ### Adding to Claude Desktop All analytics MCPs use the same config pattern. Add to the Claude Desktop config file (see ../common/mcp-setup.md for file location): For hosted MCPs (CoinGecko, Blockscout) that expose a remote endpoint: ```json { "mcpServers": { "": { "type": "streamable-http", "url": "" } } } ``` ### Adding to Claude Code (CLI) Stdio (local): ```bash claude mcp add -- npx -y ``` Streaming (hosted): ```bash claude mcp add --transport http ``` --- ## API Key Requirements All analytics MCPs are free and require no API key: | MCP | API Key Required | Endpoint | |------------------|------------------|---------------------------------------------------| | CoinGecko | No | Hosted: `https://mcp.api.coingecko.com/mcp` | | Crypto.com | No | Hosted: `https://mcp.crypto.com/market-data/mcp` | | Blockscout | No | Hosted: `https://mcp.blockscout.com/mcp` | | Hive Intelligence| No | Hosted: `https://hiveintelligence.xyz/mcp` | | Philidor | No | Hosted: `https://mcp.philidor.io/api/mcp` | | DexPaprika | No | Hosted: `https://mcp.dexpaprika.com/streamable-http` | | DefiLlama | No | Local: `npx -y @nic0xflamel/defillama-mcp-server` | | mcp-crypto-price | No | Local: `npx -y mcp-crypto-price` | | SODAX | No | Hosted: `https://builders.sodax.com/mcp` | | Arcadia Finance | No | Hosted: `https://mcp.arcadia.finance/mcp` | --- ## Use Case Routing ### Before a Bridge or Swap 1. **Check token price** → [token-prices.md](token-prices.md) — verify the token is priced as expected before committing. 2. **Check destination pool liquidity** → [dex-pools.md](dex-pools.md) — ensure the destination chain has sufficient liquidity. 3. **Check wallet balances** → Direct Balance Queries below, or Blockscout `get_tokens_by_address` per chain. ### After a Bridge or Swap 4. **Verify transaction on-chain** → [onchain-explorer.md](onchain-explorer.md) — confirm the tx landed on the destination chain. 5. **Check received balance** → Blockscout `get_tokens_by_address` or Direct Balance Queries below. ### Research and Analysis 6. **Protocol TVL and yields** → [defi-tvl.md](defi-tvl.md) — compare protocols, check yield opportunities on destination chains. --- ## Direct Balance Queries (No MCP Required) When no analytics MCP is connected, query balances directly using the signer/runtime detected during WALLET_DISCOVERY in ../common/SKILL.md. Route based on available tool: | Chain / Runtime | Read this file | |-----------------------|--------------------------------------------| | EVM (ethers / viem) | [balance-ethers.md](balance-ethers.md) | | EVM (Foundry cast) | [balance-cast.md](balance-cast.md) | | Solana | [balance-solana.md](balance-solana.md) | | none | Install one: `npm install ethers` is fastest | ### Auto-Discovery Balance Flow ⚠️ **STOP — Do NOT ask the user for an address or chain.** When the user says "check my balance", "what's my balance", "show balances", or anything balance-related, skip all clarifying questions and immediately run discovery. This is the #1 anti-pattern: asking "which chain?" or "what address?" when the skill requires auto-discovery. The agent MUST: 1. **Discover wallets FIRST** — run ALL applicable discovery methods and collect addresses: - **OWS**: `ows wallet list` → parse EVM (`eip155:` lines) and Solana (`solana:` lines) addresses. - **env-keys**: `node ../common/scripts/env-keys.mjs --json` → collect addresses from environment variables and `.env` files. This replaces ad-hoc shell commands like `test -n "$PRIVATE_KEY"` — always use the script. - **Cast**: `cast wallet list` if Foundry is available. - Do NOT ask the user for an address — discover it. 2. **Query native balances** across ALL chains (both EVM and Solana if addresses exist for both). "All" is the default — never ask which chain. - EVM: `node scripts/balance-evm.mjs
--all` - Solana: `node scripts/balance-solana.mjs
--tokens` 3. **Query ERC-20 token balances** — native balance scripts only report native tokens. For ERC-20/SPL discovery the agent MUST also use analytics MCPs. Try each in order until one succeeds: - **Blockscout MCP** (preferred): call `mcp__blockscout__get_tokens_by_address` with `address` and `chain_id` (as string) for each major EVM chain (at minimum: `"1"`, `"56"`, `"137"`, `"42161"`, `"10"`, `"8453"`). Hosted at `https://mcp.blockscout.com/mcp` — no API key. - **Hive Intelligence** (fallback): call `mcp__hive_portfolio__get_wallet_token_balances` with `id` = address and `is_all` = true. Hosted at `https://mcp.hiveintelligence.xyz/hive_portfolio_wallet/mcp` — no API key. - **ethers.js `balanceOf`** (last resort): only if you already know specific token contract addresses from context. Cannot enumerate unknown tokens — skip if no addresses known. - Do NOT report only native balances and stop. ERC-20 discovery is required when analytics MCPs are available. 4. **Report results** for every wallet, every chain, both native and token balances. Group by chain for readability. ### Bundled Scripts **Scripts accept only standard addresses — never wallet names.** ```bash # EVM — pass a 0x address, query all deBridge EVM chains node scripts/balance-evm.mjs 0x000A5539cD9505b44575c56f929C657c73899c30 --all # EVM — pass a 0x address, query specific chains only node scripts/balance-evm.mjs 0x000A5539cD9505b44575c56f929C657c73899c30 --chains 1,137,42161 # EVM — query a specific ERC-20 token balance (e.g., USDC on Polygon) node scripts/balance-evm.mjs 0x000A5539cD9505b44575c56f929C657c73899c30 --chains 137 --token 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359 # Solana — pass a base58 address, query native SOL + SPL tokens node scripts/balance-solana.mjs B7Z1whe4TX3tVXwb93Nsd9U4f4QZfnuzm5DyUnKxVSUr --tokens # JSON output for piping node scripts/balance-evm.mjs 0x000A5539cD9505b44575c56f929C657c73899c30 --all --json node scripts/balance-solana.mjs B7Z1whe4TX3tVXwb93Nsd9U4f4QZfnuzm5DyUnKxVSUr --tokens --json ``` **Arguments:** - First argument: a standard blockchain address (EVM `0x` hex, 42 chars; or Solana base58, 32-44 chars). **Required.** - `--all`: (EVM only) query all deBridge-supported EVM chains. - `--chains `: (EVM only) comma-separated chain IDs. - `--token `: (EVM only) query a specific ERC-20 token balance instead of native balance. Reads decimals and symbol on-chain. - `--tokens`: (Solana only) also list non-zero SPL token balances. - `--json`: output as JSON. **Do NOT pass OWS wallet names, ENS names, or any non-address string.** Resolve addresses first via WALLET_DISCOVERY, then pass the resolved address to the script. All direct query methods require an RPC endpoint. Resolve RPCs in this order: 1. Environment variable (`$RPC_URL`, `$ETH_RPC_URL`). 2. User-provided URL. 3. Discover from Chainlist — read ../common/rpc-discovery.md. ### When to Use Direct Queries vs MCP | Scenario | Use | |----------|-----| | Native balances, multi-chain | Bundled script (`balance-evm.mjs --all`) — parallel RPC calls | | ERC-20 token discovery | Blockscout MCP `get_tokens_by_address` — enumerates all tokens without knowing addresses | | Full portfolio ("check my balance") | **Both**: bundled script for native + Blockscout/Hive MCP for ERC-20 tokens | | No MCP available at all | Bundled script for native only — warn user that ERC-20 tokens are not shown | --- ## When No Analytics MCP Is Available If no analytics MCPs are installed, you can still gather basic data: | Need | Fallback | |------|----------| | Token balance | Direct RPC query — see Direct Balance Queries above | | Token price | deBridge MCP itself: compare `create_tx` input/output amounts for an implied exchange rate | | Transaction verification | Use an RPC `eth_getTransactionReceipt` call or the bundled scripts | | Pool liquidity / TVL / yields | No direct fallback — suggest installing CoinGecko MCP (free, no key): `claude mcp add --transport http coingecko https://mcp.api.coingecko.com/mcp` | For a quick start with zero setup, CoinGecko (hosted, no API key), Crypto.com (hosted, no API key), and Blockscout (hosted, no API key) cover most pre-swap research needs. ## Common Errors | Error | Cause | Fix | |--------------------------------|-------------------------------|----------------------------------------------------------| | MCP tool not found | MCP not installed/configured | Follow installation in the relevant reference file | | Rate limited (429) | Too many requests | Add delay between calls or switch to a different free MCP | | `npx` hangs on first run | Large package download | Use `npm install -g` for persistent use | | Chain not supported | MCP doesn't cover that chain | Check chain support in each reference file | --- ## Source: skills/analytics/balance-cast.md --- title: Balance Queries with Foundry Cast impact: HIGH impactDescription: "Balance query method for developers with Foundry toolchain" tags: balance, foundry, cast, cli, erc20, native, wallet --- # Foundry Cast Balance Queries ## Prerequisites ```bash which cast || echo "Install Foundry: curl -L https://foundry.paradigm.xyz | bash && foundryup" ``` ## Deriving Address from Private Key ```bash ADDRESS=$(cast wallet address --private-key "$PRIVATE_KEY") echo "$ADDRESS" ``` ## Native Token Balance ### Single Chain ```bash # Human-readable (ether units) cast balance "$ADDRESS" --rpc-url "$RPC_URL" --ether # Raw wei cast balance "$ADDRESS" --rpc-url "$RPC_URL" ``` ### Multi-Chain Scan **Recommended:** Use the bundled script instead: ```bash node scripts/balance-evm.mjs --chains 1,42161,8453,10,137,56,43114,59144 ``` For cast-based multi-chain scanning, discover RPCs dynamically: ```bash #!/usr/bin/env bash ADDRESS=$(cast wallet address --private-key "$PRIVATE_KEY") CHAIN_IDS=(1 42161 8453 10 137 56 43114 59144) for id in "${CHAIN_IDS[@]}"; do RPC=$(node ../common/scripts/rpc.mjs "$id") bal=$(cast balance "$ADDRESS" --rpc-url "$RPC" --ether 2>/dev/null) || bal="error" printf "chain %s: %s\n" "$id" "$bal" done ``` ## ERC-20 Token Balance ### Query Balance ```bash # Raw units cast call "$TOKEN_ADDRESS" "balanceOf(address)(uint256)" "$ADDRESS" --rpc-url "$RPC_URL" # Get decimals to convert to human-readable DECIMALS=$(cast call "$TOKEN_ADDRESS" "decimals()(uint8)" --rpc-url "$RPC_URL") RAW=$(cast call "$TOKEN_ADDRESS" "balanceOf(address)(uint256)" "$ADDRESS" --rpc-url "$RPC_URL") # Convert with cast HUMAN=$(cast from-wei "$RAW" "$DECIMALS") SYMBOL=$(cast call "$TOKEN_ADDRESS" "symbol()(string)" --rpc-url "$RPC_URL") echo "$HUMAN $SYMBOL" ``` ### USDC Across Chains ```bash ADDRESS=$(cast wallet address --private-key "$PRIVATE_KEY") # USDC addresses from ../common/chain-config.md check_usdc() { local chain="$1" rpc="$2" token="$3" local raw raw=$(cast call "$token" "balanceOf(address)(uint256)" "$ADDRESS" --rpc-url "$rpc" 2>/dev/null) || { echo "$chain: error"; return; } local human human=$(cast from-wei "$raw" 6) printf "%-12s %s USDC\n" "$chain" "$human" } check_usdc "Ethereum" "$(node ../common/scripts/rpc.mjs 1)" "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" check_usdc "Arbitrum" "$(node ../common/scripts/rpc.mjs 42161)" "0xaf88d065e77c8cC2239327C5EDb3A432268e5831" check_usdc "Base" "$(node ../common/scripts/rpc.mjs 8453)" "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" check_usdc "Polygon" "$(node ../common/scripts/rpc.mjs 137)" "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359" ``` ## Token Allowance Check Useful before bridge/swap operations: ```bash cast call "$TOKEN_ADDRESS" \ "allowance(address,address)(uint256)" "$OWNER" "$SPENDER" \ --rpc-url "$RPC_URL" ``` ## Common Errors | Error | Fix | |-------|-----| | `cast: command not found` | Install Foundry: `curl -L https://foundry.paradigm.xyz \| bash && foundryup` | | Connection refused | RPC endpoint down — try another from chainlist | | `from-wei` wrong result | Verify decimals — USDC is 6, not 18 | | Empty response from `cast call` | Address is not a contract on this chain — check token address | --- ## Source: skills/analytics/balance-ethers.md --- title: Balance Queries with ethers.js and viem impact: HIGH impactDescription: "Primary balance query method for Node.js CLI and headless agents" tags: balance, ethers, viem, erc20, native, wallet, typescript, javascript --- # ethers.js / viem Balance Queries ## Setup ### ethers v6 ```typescript import { ethers } from "ethers"; const provider = new ethers.JsonRpcProvider(process.env.RPC_URL); // Derive address from private key (if no address provided) const wallet = new ethers.Wallet(process.env.PRIVATE_KEY); const address = wallet.address; ``` ### viem ```typescript import { createPublicClient, http } from "viem"; import { mainnet } from "viem/chains"; import { privateKeyToAccount } from "viem/accounts"; const client = createPublicClient({ chain: mainnet, // replace with target chain transport: http(process.env.RPC_URL), }); // Derive address from private key (if no address provided) const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`); const address = account.address; ``` ## Native Token Balance ### ethers ```typescript const balance = await provider.getBalance(address); console.log(`${ethers.formatEther(balance)} ETH`); ``` ### viem ```typescript import { formatEther } from "viem"; const balance = await client.getBalance({ address }); console.log(`${formatEther(balance)} ETH`); ``` ## ERC-20 Token Balance ### ethers ```typescript const erc20Abi = ["function balanceOf(address) view returns (uint256)", "function decimals() view returns (uint8)", "function symbol() view returns (string)"]; const token = new ethers.Contract(tokenAddress, erc20Abi, provider); const [balance, decimals, symbol] = await Promise.all([ token.balanceOf(address), token.decimals(), token.symbol(), ]); console.log(`${ethers.formatUnits(balance, decimals)} ${symbol}`); ``` ### viem ```typescript import { formatUnits } from "viem"; import { erc20Abi } from "viem"; const [balance, decimals, symbol] = await Promise.all([ client.readContract({ address: tokenAddress, abi: erc20Abi, functionName: "balanceOf", args: [address], }), client.readContract({ address: tokenAddress, abi: erc20Abi, functionName: "decimals", }), client.readContract({ address: tokenAddress, abi: erc20Abi, functionName: "symbol", }), ]); console.log(`${formatUnits(balance, decimals)} ${symbol}`); ``` ## Multi-Chain Balance Scan **Recommended:** Use the bundled script instead of inline code: ```bash node scripts/balance-evm.mjs 0x000A5539cD9505b44575c56f929C657c73899c30 --chains 1,42161,8453,10,137,56,43114,59144 ``` The script accepts only a standard 0x EVM address (42 chars). Resolve wallet names first via WALLET_DISCOVERY. For inline code, discover RPCs dynamically via `../common/scripts/rpc.mjs` (or `rpc.ts`): ### ethers ```typescript import { ethers } from "ethers"; import { getRpc, getChainInfo } from "../common/scripts/rpc.mjs"; const chainIds = [1, 42161, 8453, 10, 137, 56, 43114, 59144]; async function getBalance(chainId: number, address: string) { const rpcUrl = await getRpc(chainId); const info = await getChainInfo(chainId); const provider = new ethers.JsonRpcProvider(rpcUrl, undefined, { staticNetwork: true }); const balance = await Promise.race([ provider.getBalance(address), new Promise((_, rej) => setTimeout(() => rej(new Error("timeout")), 5000)), ]); return { name: info?.name, symbol: info?.nativeCurrency.symbol, balance: ethers.formatEther(balance) }; } const results = await Promise.allSettled(chainIds.map(id => getBalance(id, address))); for (const r of results) { if (r.status === "fulfilled") { const { name, symbol, balance } = r.value; console.log(`${name}: ${balance} ${symbol}`); } } ``` Key details: - RPCs are discovered from Chainlist with health checks — no hardcoded URLs. - Use `staticNetwork: true` to skip the initial `eth_chainId` call — faster and avoids retry loops on slow RPCs. - Always race with a timeout — public RPCs can hang indefinitely. - Use `Promise.allSettled` (not `Promise.all`) so one failed chain does not abort the rest. ## ERC-20 Scan Across Chains Check a specific token (e.g., USDC) on multiple chains. Token addresses come from `../common/chain-config.md`; RPCs are discovered dynamically: ```typescript import { ethers } from "ethers"; import { getRpc } from "../common/scripts/rpc.mjs"; // USDC addresses from ../common/chain-config.md const usdcByChain = [ { chainId: 1, name: "Ethereum", token: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", decimals: 6 }, { chainId: 42161, name: "Arbitrum", token: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", decimals: 6 }, { chainId: 8453, name: "Base", token: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", decimals: 6 }, { chainId: 137, name: "Polygon", token: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", decimals: 6 }, ]; const abi = ["function balanceOf(address) view returns (uint256)"]; const results = await Promise.allSettled( usdcByChain.map(async (c) => { const rpc = await getRpc(c.chainId); const provider = new ethers.JsonRpcProvider(rpc, undefined, { staticNetwork: true }); const contract = new ethers.Contract(c.token, abi, provider); const balance = await Promise.race([ contract.balanceOf(address), new Promise((_, rej) => setTimeout(() => rej(new Error("timeout")), 5000)), ]); return { name: c.name, balance: ethers.formatUnits(balance, c.decimals) }; }) ); ``` ## Deriving Address from Private Key When only `PRIVATE_KEY` is available and no address is known: ```typescript // ethers const address = new ethers.Wallet(process.env.PRIVATE_KEY).address; // viem import { privateKeyToAccount } from "viem/accounts"; const address = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`).address; ``` ⚠️ CAUTION: Never log or expose `PRIVATE_KEY`. Derive the address, then discard the wallet object if signing is not needed. ## Common Errors | Error | Fix | |-------|-----| | `staticNetwork` not recognized | ethers v6.7+ required — update: `npm install ethers@latest` | | RPC timeout on `getBalance` | Use `Promise.race` with timeout; try next RPC from chainlist | | `balanceOf` returns 0 unexpectedly | Verify token address matches the chain (USDC addresses differ per chain) | | `CALL_EXCEPTION` on `decimals()` | Address is not an ERC-20 contract on this chain | --- ## Source: skills/analytics/balance-solana.md --- title: Balance Queries on Solana impact: HIGH impactDescription: "Balance query method for Solana wallets using bundled script or @solana/web3.js" tags: balance, solana, spl-token, native, wallet, rpc --- # Solana Balance Queries ## RPC Endpoint RPCs are resolved dynamically via `../common/scripts/rpc.mjs` (Solana chain ID `7565164`). Override order: 1. `$SOLANA_RPC_URL` environment variable 2. `$RPC_URL_7565164` environment variable 3. Public fallback ## Bundled Script (Recommended) The fastest path — handles SOL balance and optional SPL token listing: ```bash node scripts/balance-solana.mjs [--tokens] [--json] ``` The script accepts only a standard Solana base58 address (32-44 chars). Resolve wallet names first via WALLET_DISCOVERY (e.g., `ows wallet list` → extract the `solana:` address). Examples: ```bash # SOL balance for a resolved address node scripts/balance-solana.mjs B7Z1whe4TX3tVXwb93Nsd9U4f4QZfnuzm5DyUnKxVSUr # SOL + all SPL tokens node scripts/balance-solana.mjs B7Z1whe4TX3tVXwb93Nsd9U4f4QZfnuzm5DyUnKxVSUr --tokens # JSON output for piping node scripts/balance-solana.mjs B7Z1whe4TX3tVXwb93Nsd9U4f4QZfnuzm5DyUnKxVSUr --tokens --json ``` ## Native SOL Balance ### @solana/web3.js ```typescript import { Connection, PublicKey, LAMPORTS_PER_SOL } from "@solana/web3.js"; import { getRpc } from "../common/scripts/rpc.mjs"; const rpcUrl = await getRpc(7565164); const connection = new Connection(rpcUrl); const pubkey = new PublicKey(address); const lamports = await connection.getBalance(pubkey); console.log(`${lamports / LAMPORTS_PER_SOL} SOL`); ``` ## SPL Token Balance ### @solana/web3.js + @solana/spl-token ```typescript import { Connection, PublicKey } from "@solana/web3.js"; import { getAssociatedTokenAddress, getAccount } from "@solana/spl-token"; import { getRpc } from "../common/scripts/rpc.mjs"; const rpcUrl = await getRpc(7565164); const connection = new Connection(rpcUrl); const owner = new PublicKey(address); const mint = new PublicKey(tokenMintAddress); const ata = await getAssociatedTokenAddress(mint, owner); const account = await getAccount(connection, ata); console.log(`Balance: ${account.amount.toString()} (raw)`); ``` ## All SPL Token Balances Use the bundled script: `node scripts/balance-solana.mjs --tokens` ## Common Errors | Error | Fix | |-------|-----| | `Invalid param: could not find account` | Token account does not exist — wallet holds no balance of that token | | RPC 429 rate limit | Use a dedicated RPC provider or add delay between calls | | `FetchError` / timeout | Public RPC is congested — set `$SOLANA_RPC_URL` to a private endpoint | | Wrong balance (too large/small) | SOL uses 9 decimals (1 SOL = 1e9 lamports); SPL tokens vary — check the mint's decimals | --- ## Source: skills/analytics/defi-tvl.md --- title: DeFi Protocol Analytics — TVL, Fees, Yields, Vault Risk impact: HIGH impactDescription: "Protocol health, yield data, and vault risk scoring for informed bridging decisions" tags: defillama, philidor, tvl, fees, revenue, yields, stablecoins, dex-volume, vault-risk --- # DeFi Protocol Analytics DefiLlama provides protocol TVL, fee revenue, yield farming data, DEX volumes, stablecoin metrics, and token prices — all without an API key. ## Installation Two npm packages are available. Both wrap the DefiLlama public API. ### @nic0xflamel/defillama-mcp-server (OpenAPI proxy) Dynamically generates tools from the full DefiLlama OpenAPI surface. ```bash claude mcp add defillama -- npx -y @nic0xflamel/defillama-mcp-server ``` ### @iqai/defillama-mcp (curated tools with AI entity resolution) 19 typed tools with fuzzy matching on protocol/chain names. Includes token pricing endpoints not in @nic0xflamel. ```bash claude mcp add defillama -- pnpm dlx @iqai/defillama-mcp ``` No API key required for either package. Tool names differ — see sections below. --- ## Key Tools (@nic0xflamel/defillama-mcp-server) ### TVL and Protocols | Tool | Parameters (\* = required) | Description | |------|-----------|-------------| | `get_v2_chains` | (none) | Current TVL of all chains | | `get_protocols` | (none) | List all protocols with TVL | | `get_tvl__by_protocol` | `protocol`\* | Current TVL of a specific protocol | | `get_v2_historicalChainTvl` | (none) | Historical TVL of DeFi on all chains | | `get_v2_historicalChainTvl__by_chain` | `chain`\* | Historical TVL of a specific chain | ### DEX Volumes | Tool | Parameters (\* = required) | Description | |------|-----------|-------------| | `get_overview_dexs` | `excludeTotalDataChart`, `excludeTotalDataChartBreakdown` | DEX volume summaries across all chains | | `get_overview_dexs__by_chain` | `chain`\*, `excludeTotalDataChart`, `excludeTotalDataChartBreakdown` | DEX volumes for a specific chain | | `get_summary_dexs__by_protocol` | `protocol`\*, `excludeTotalDataChart`, `excludeTotalDataChartBreakdown` | DEX volume for a specific protocol | ### Fees and Revenue | Tool | Parameters (\* = required) | Description | |------|-----------|-------------| | `get_overview_fees` | `excludeTotalDataChart`, `excludeTotalDataChartBreakdown`, `dataType` (dailyFees/dailyRevenue) | Fee and revenue summaries | | `get_overview_fees__by_chain` | `chain`\*, `excludeTotalDataChart`, `excludeTotalDataChartBreakdown`, `dataType` | Fees and revenue for a specific chain | | `get_summary_fees__by_protocol` | `protocol`\*, `dataType` (dailyFees/dailyRevenue) | Fees and revenue for a specific protocol | ### Yields | Tool | Parameters (\* = required) | Description | |------|-----------|-------------| | `get_pools` | (none) | Latest data for all yield pools with predictions | | `get_chart__by_pool` | `pool`\* (UUID from pool data) | Historical APY and TVL for a specific pool | ### Stablecoins | Tool | Parameters (\* = required) | Description | |------|-----------|-------------| | `get_stablecoincharts_all` | `stablecoin` (integer — optional filter) | Historical market cap sum of all stablecoins | > **Note:** @nic0xflamel does not include token pricing tools. Use @iqai (below) or CoinGecko MCP for pricing. --- ## Key Tools (@iqai/defillama-mcp) All @iqai tools support AI entity resolution — pass protocol/chain names as-is (e.g., "Uniswap", "Ethereum") and they auto-resolve to slugs. ### TVL and Protocols | Tool | Parameters (\* = required) | Description | |------|-----------|-------------| | `defillama_get_chains` | `order` (asc/desc) | Chains ranked by TVL (top 20) | | `defillama_get_protocol_data` | `protocol`, `sortCondition` (change_1h/1d/7d/tvl), `order` | Protocol TVL; omit protocol for top 10 | | `defillama_get_historical_chain_tvl` | `chain` | Historical TVL over time (last 10 points) | ### DEX Volumes | Tool | Parameters (\* = required) | Description | |------|-----------|-------------| | `defillama_get_dexs_data` | `protocol`, `chain`, `sortCondition` (total24h/total7d/total30d/change_1d/change_7d/change_1m), `order` | DEX trading volume metrics | ### Fees and Revenue | Tool | Parameters (\* = required) | Description | |------|-----------|-------------| | `defillama_get_fees_and_revenue` | `protocol`, `chain`, `dataType` (dailyFees/dailyRevenue/dailyHoldersRevenue), `sortCondition`, `order` | Protocol fee and revenue metrics | ### Yields | Tool | Parameters (\* = required) | Description | |------|-----------|-------------| | `defillama_get_latest_pool_data` | `sortCondition` (tvlUsd/apy/apyBase/apyReward/apyMean30d), `order`, `limit` (1-100) | Current yield farming pools with APY | | `defillama_get_historical_pool_data` | `pool`\* (UUID from latest pool data) | Historical APY/TVL for a specific pool | ### Stablecoins | Tool | Parameters (\* = required) | Description | |------|-----------|-------------| | `defillama_get_stablecoin` | `includePrices` (boolean) | Top 20 stablecoins with circulation | | `defillama_get_stablecoin_chains` | (none) | Chains ranked by stablecoin market cap | | `defillama_get_stablecoin_charts` | `stablecoin` (ID or name), `chain` | Historical stablecoin market cap | | `defillama_get_stablecoin_prices` | (none) | Historical stablecoin price data | ### Token Prices (only in @iqai) | Tool | Parameters (\* = required) | Description | |------|-----------|-------------| | `defillama_get_prices_current_coins` | `coins`\* ("chain:address"), `searchWidth` | Current token prices by contract | | `defillama_get_chart_coins` | `coins`\*, `start`, `end`, `span`, `period`, `searchWidth` | Historical price time-series | | `defillama_get_percentage_coins` | `coins`\*, `timestamp`, `period` (1h/1d/7d), `lookForward` | Price change percentage | | `defillama_get_historical_prices_by_contract` | `coins`\*, `timestamp`\*, `searchWidth` | Historical prices at a specific time | | `defillama_get_batch_historical` | `coins`\*, `searchWidth` | Historical prices at multiple timestamps | | `defillama_get_prices_first_coins` | `coins`\* | First recorded price for tokens | ### Other (only in @iqai) | Tool | Parameters (\* = required) | Description | |------|-----------|-------------| | `defillama_get_options_data` | `dataType`, `protocol`, `chain`, `sortCondition`, `order` | Options protocol volume and premiums | | `defillama_get_blockchain_timestamp` | `chain`\*, `timestamp`\* | Block number at a specific time | --- ## Example: Research Before a Large Bridge ``` 1. Check deBridge TVL → get_tvl__by_protocol (protocol: "debridge") or defillama_get_protocol_data (protocol: "debridge") 2. Check yield on destination chain → get_pools or defillama_get_latest_pool_data (sortCondition: "apy", order: "desc", limit: 10) 3. Verify token price (@iqai only) → defillama_get_prices_current_coins (coins: "ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48") 4. Use findings to advise on best chain/token for yield or liquidity. ``` Chain slugs for pricing: `ethereum`, `bsc`, `polygon`, `arbitrum`, `optimism`, `base`, `avalanche`, `solana`. For token pricing without @iqai, use CoinGecko MCP (see [token-prices.md](token-prices.md)). --- ## Philidor (DeFi Vault Risk Scoring — No API Key, Hosted) Scores 700+ DeFi vaults across Morpho, Aave, Spark, Yearn, Beefy, Compound, and Uniswap. Three-vector risk framework (Asset 40%, Platform 40%, Governance 20%) with Prime/Core/Edge tier classification. Use after identifying yield opportunities via DefiLlama to assess risk before bridging funds. ### Installation Hosted endpoint (no install, no key): ```bash claude mcp add --transport http philidor https://mcp.philidor.io/api/mcp ``` ### Key Tools | Tool | Parameters (\* = required) | Description | |------|-----------|-------------| | `search_vaults` | `query`, `chain`, `protocol`, `asset`, `riskTier`, `minTvl`, `sortBy`, `sortOrder`, `limit` | Search and filter DeFi vaults by chain, protocol, asset, risk tier, TVL | | `get_vault` | `id`, `network`, `address` | Detailed vault info including risk breakdown and historical snapshots | | `get_vault_risk_breakdown` | `network`\*, `address`\* | Detailed risk vectors: Asset Composition, Platform Code, Governance scores | | `compare_vaults` | `vaults`\* (array of 2-3) | Side-by-side comparison on TVL, APR, risk score, audit status | | `find_safest_vaults` | `asset`, `chain`, `minTvl` | Top 10 safest vaults, filtered by asset/chain/TVL | | `get_protocol_info` | `protocolId`\* | Protocol details: TVL, vault count, auditors, security incidents | | `get_curator_info` | `curatorId`\* | Curator's managed vaults, TVL, chain distribution | | `get_market_overview` | (none) | DeFi vault market: total TVL, vault count, risk distribution by protocol | | `explain_risk_score` | `score`\* (number) | Explain a risk score: tier, calculation method, thresholds | | `list_vaults_with_incidents` | (none) | Vaults with critical incidents in the last 365 days | ### Example: Assess Vault Risk After Bridging ``` 1. Find yield via DefiLlama → get_pools → identify high-APY vault on Arbitrum 2. Check risk → get_vault_risk_breakdown (network: "arbitrum", address: "0x...") 3. Compare → find_safest_vaults (asset: "USDC", chain: "arbitrum") 4. If acceptable → bridge via ../swap/SKILL.md. If high → suggest safer vault. ``` --- ## Arcadia Finance (LP Management & Lending — No API Key, Hosted) DeFi LP management and lending protocol with tools for pool analytics, LP strategy evaluation, and position management. Use to assess lending pool rates and LP strategies on destination chains before/after bridging. ### Installation Hosted endpoint (no install, no key): ```bash claude mcp add --transport http arcadia https://mcp.arcadia.finance/mcp ``` ### Key Tools (Read — Analytics) | Tool | Parameters (\* = required) | Description | |------|-----------|-------------| | `read_pool_list` | `chain_id` | All lending pools: TVL, utilization, liquidity, interest rate | | `read_pool_info` | `pool_address`\*, `days`, `chain_id` | Pool detail with APY history over time | | `read_strategy_list` | `featured_only`, `limit`, `offset`, `chain_id` | LP strategies with APY per range width | | `read_strategy_info` | `strategy_id`\*, `chain_id` | Full strategy detail: APY, range widths | | `read_asset_list` | `search`, `chain_id` | Supported collateral assets | | `read_asset_prices` | `asset_addresses`\*, `chain_id` | USD prices for assets | | `read_account_info` | `account_address`\*, `chain_id` | Account health factor, collateral, debt | | `read_account_pnl` | `account_address`\*, `chain_id` | PnL and yield earned | | `read_strategy_recommendation` | `account_address`\*, `chain_id` | Rebalancing recommendation for an account | ### Key Tools (Write — Position Management) Tools for building transactions: `write_account_deposit`, `write_account_withdraw`, `write_account_borrow`, `write_account_add_liquidity` (flash-action: deposit + LP in one tx), `write_account_swap` (flash-action: swap within account). All require `account_address`\* and `chain_id`. ### Example: Evaluate LP Strategies Before Bridging ``` 1. List featured strategies → read_strategy_list (featured_only: true, chain_id: 8453) 2. Get detail → read_strategy_info (strategy_id from step 1) 3. Check lending rates → read_pool_list (chain_id: 8453) 4. Compare APY vs risk → advise on best deployment after bridging. ``` --- ## Source: skills/analytics/dex-pools.md --- title: DEX Pool Analytics — Liquidity, OHLCV, Trades impact: MEDIUM impactDescription: "Pool liquidity and price data for swap destination assessment" tags: dexpaprika, dex, pools, ohlcv, liquidity, trades, coinpaprika --- # DEX Pool Analytics DexPaprika provides real-time DEX pool data: liquidity, OHLCV candles, recent trades, and token info across multiple networks. No API key required. Use before deBridge swaps to assess destination pool depth and recent trading activity. ## Installation Hosted endpoint (recommended — no install): ```bash claude mcp add --transport http dexpaprika https://mcp.dexpaprika.com/streamable-http ``` Local (alternative): `npx dexpaprika-mcp` — no API key needed. ## Key Tools ### Discovery | Tool | Parameters (* = required) | Description | |------|-----------|-------------| | `getCapabilities` | — | Server capabilities, workflow patterns, network synonyms, common pitfalls | | `getNetworks` | — | All supported networks | | `getNetworkDexes` | `network`*, `page`, `limit`, `sort`(asc/desc), `order_by`(pool) | DEXes on a specific network | | `search` | `query`* | Search tokens, pools, DEXes by name/symbol/address | | `getStats` | — | Aggregate DEX statistics | ### Pool Data | Tool | Parameters (* = required) | Description | |------|-----------|-------------| | `getNetworkPools` | `network`*, `page`, `limit`, `sort`(asc/desc), `order_by`(volume_usd/price_usd/transactions/last_price_change_usd_24h/created_at) | All pools on a network | | `getDexPools` | `network`*, `dex`*, `page`, `limit`, `sort`(asc/desc), `order_by`(volume_usd/price_usd/transactions/last_price_change_usd_24h/created_at) | Pools for a specific DEX | | `getNetworkPoolsFilter` | `network`*, `page`, `limit`, `volume_24h_min`, `volume_24h_max`, `txns_24h_min`, `created_after`(unix), `created_before`(unix), `sort_by`(volume_24h/txns_24h/created_at), `sort_dir`(asc/desc) | Filtered pool search | | `getPoolDetails` | `network`*, `pool_address`*, `inversed` | Full pool info: TVL, volume, fees | | `getPoolOHLCV` | `network`*, `pool_address`*, `start`*, `end`, `limit`, `interval`(1m/5m/10m/15m/30m/1h/6h/12h/24h), `inversed` | Candlestick price data | | `getPoolTransactions` | `network`*, `pool_address`*, `page`, `limit`, `cursor` | Recent swaps and trades | ### Token Data | Tool | Parameters (* = required) | Description | |------|-----------|-------------| | `getTokenDetails` | `network`*, `token_address`* | Token metadata and market data | | `getTokenPools` | `network`*, `token_address`*, `page`, `limit`, `sort`(asc/desc), `order_by`(volume_usd/price_usd/transactions/last_price_change_usd_24h/created_at), `reorder`, `address` | Pools containing a token | | `getTokenMultiPrices` | `network`*, `tokens`*: array (up to 10) | Batch token prices | ## Supported Networks DexPaprika uses network slug identifiers: | Network | Slug | |---------|------| | Ethereum | `ethereum` | | Arbitrum | `arbitrum` | | Base | `base` | | Polygon | `polygon` | | BNB Chain (BSC) | `bsc` | | Optimism | `optimism` | | Avalanche | `avalanche` | | Solana | `solana` | Call `getNetworks` for the full list. ## Example: Check Liquidity Before Cross-Chain Swap ``` 1. Search for the destination token: Call mcp__dexpaprika__search: query: "USDC base" 2. Get pools containing the token: Call mcp__dexpaprika__getTokenPools: network: "base" token_address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" order_by: "volume_24h" limit: 5 3. Check the top pool's details: Call mcp__dexpaprika__getPoolDetails: network: "base" pool_address: "" 4. If 24h volume > bridge amount and TVL is healthy → proceed with the swap. If low liquidity → warn the user about potential slippage. ``` ## Example: Get Price Candles for a Pool ``` Call mcp__dexpaprika__getPoolOHLCV: network: "ethereum" pool_address: "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640" // USDC/ETH on Uniswap V3 start: "2025-01-01" interval: "1d" limit: 30 Returns 30 daily candles with open, high, low, close, and volume. ``` --- ## Source: skills/analytics/onchain-explorer.md --- title: On-Chain Explorer — Address, Transaction, Contract, Portfolio impact: HIGH impactDescription: "Verify transactions and inspect addresses after bridge/swap operations" tags: blockscout, hive, explorer, transactions, address, contract, abi, ens, portfolio --- # On-Chain Explorer Look up addresses, transactions, contracts, and token transfers on-chain. Primary use after deBridge operations: verify the transaction landed, inspect contract ABIs, or check destination wallet state. ## Blockscout MCP (Primary — No API Key, 3000+ Chains) Official hosted MCP covering 3,000+ EVM-compatible chains. No installation or API key required. ### Installation Hosted endpoint (recommended): ```bash claude mcp add --transport http blockscout https://mcp.blockscout.com/mcp ``` ### Key Tools | Tool | Parameters | Description | |------|-----------|-------------| | `get_chains_list` | — | All known blockchain networks | | `get_block_info` | `chain_id`, `number_or_hash`, `include_transactions` | Block details by number or hash | | `get_address_info` | `chain_id`, `address` | Balance, ENS name, contract status | | `get_tokens_by_address` | `chain_id`, `address`, `cursor` | ERC-20 holdings with market data | | `get_transactions_by_address` | `chain_id`, `address`, `age_from` (required), `age_to`, `methods`, `cursor` | Transactions in a time range | | `get_token_transfers_by_address` | `chain_id`, `address`, `age_from` (required), `age_to`, `token`, `cursor` | Token transfers by address and timeframe | | `get_transaction_info` | `chain_id`, `transaction_hash`, `include_raw_input` | Full transaction details with decoded input | | `get_contract_abi` | `chain_id`, `address` | Smart contract ABI (verified contracts) | | `inspect_contract_code` | `chain_id`, `address`, `file_name` | Verified contract source code | | `lookup_token_by_symbol` | `chain_id`, `symbol` | Find token by symbol or name | | `get_address_by_ens_name` | `name` | ENS to Ethereum address resolution | | `get_block_number` | `chain_id`, `datetime` | Block number at a specific time | | `nft_tokens_by_address` | `chain_id`, `address`, `cursor` | NFTs owned by address | | `read_contract` | `chain_id`, `address`, `abi`, `function_name`, `args`, `block` | Read-only contract call | | `direct_api_call` | `chain_id`, `endpoint_path`, `query_params`, `cursor` | Raw Blockscout API access | ### Chain IDs Blockscout uses standard EVM chain IDs. Common ones for deBridge: | Chain | Chain ID | |-------|----------| | Ethereum | 1 | | Arbitrum | 42161 | | Polygon | 137 | | BSC | 56 | | Base | 8453 | | Optimism | 10 | | Avalanche | 43114 | | Linea | 59144 | ### Example: Verify Bridge Transaction on Destination Chain ``` 1. After deBridge bridge completes, take the destination tx hash. 2. Call mcp__blockscout__get_transaction_info: chain_id: "42161" // Arbitrum transaction_hash: "0xabc123..." include_raw_input: false 3. Confirm status is "ok" and the expected token transfer is present. 4. Call mcp__blockscout__get_tokens_by_address: chain_id: "42161" address: "" 5. Verify the expected token balance increased. ``` ### Example: Look Up Token by Symbol on a Chain ``` Call mcp__blockscout__lookup_token_by_symbol: chain_id: "8453" // Base symbol: "USDC" Returns: contract address, name, decimals, total supply. ``` --- ## Hive Intelligence (Multi-Chain Analytics — No API Key, Hosted) 300+ tools across 9 sub-servers covering market data, DeFi, DEX, portfolios, tokens, NFTs, sentiment, network infra, and search. Each sub-server exposes tools directly — no meta-tool indirection needed. ### Installation Connect to individual sub-servers by category. Each is a separate hosted endpoint: ```bash # Add the sub-servers you need claude mcp add --transport http hive-portfolio https://mcp.hiveintelligence.xyz/hive_portfolio_wallet/mcp claude mcp add --transport http hive-tokens https://mcp.hiveintelligence.xyz/hive_token_contract/mcp claude mcp add --transport http hive-defi https://mcp.hiveintelligence.xyz/hive_defi_protocol/mcp claude mcp add --transport http hive-dex https://mcp.hiveintelligence.xyz/hive_onchain_dex/mcp claude mcp add --transport http hive-market https://mcp.hiveintelligence.xyz/hive_market_data/mcp ``` ### Sub-Server Catalog | Sub-Server | Endpoint | Tools | Focus | |------------|----------|-------|-------| | Portfolio & Wallet | `mcp.hiveintelligence.xyz/hive_portfolio_wallet/mcp` | 38 | Wallet balances, token holdings, DeFi positions, transaction history across chains | | Token & Contract | `mcp.hiveintelligence.xyz/hive_token_contract/mcp` | 27 | Token info, top holders, holder charts, token filtering, contract details | | DeFi Protocol | `mcp.hiveintelligence.xyz/hive_defi_protocol/mcp` | 23 | Protocol TVL, fees, yields, global DeFi stats | | On-Chain DEX | `mcp.hiveintelligence.xyz/hive_onchain_dex/mcp` | 44 | Pool analytics, trending pools, OHLCV, trades, DEX data | | Market Data | `mcp.hiveintelligence.xyz/hive_market_data/mcp` | 80 | Prices, market charts, OHLCV, gainers/losers, exchange data | | NFT Analytics | `mcp.hiveintelligence.xyz/hive_nft_analytics/mcp` | 37 | NFT collections, marketplace data, floor prices, tickers | | Social Sentiment | `mcp.hiveintelligence.xyz/hive_social_sentiment/mcp` | 17 | Topic news/posts, sentiment metrics, trending topics | | Network Infra | `mcp.hiveintelligence.xyz/hive_network_infrastructure/mcp` | 24 | Network status, gas prices, blockchain stats | | Search & Discovery | `mcp.hiveintelligence.xyz/hive_search_discovery/mcp` | 10 | Search tokens/protocols, trending, categories, new coins | ### Key Tools by Use Case **Portfolio (hive_portfolio_wallet):** | Tool | Parameters (* = required) | Description | |------|-----------|-------------| | `get_wallet_balance` | `id`*, `chain_id` | Wallet balance on a chain | | `get_wallet_token_balances` | `id`*, `is_all`, `chain_ids` | Token balances across chains | | `get_wallet_defi_positions_all_chains` | `id`*, `chain_ids` | DeFi positions across all chains | | `get_wallet_history` | `id`*, `chain_id`* | Transaction history | **Token Data (hive_token_contract):** | Tool | Parameters (* = required) | Description | |------|-----------|-------------| | `get_token_info` | `network`*, `address`* | Token metadata and on-chain info | | `get_token_top_holders` | `network`*, `address`* | Top token holders | | `get_token_details` | `networkId`*, `address`* | Detailed token information | ### Example: Portfolio Overview Before Bridge ``` 1. Call mcp__hive_portfolio__get_wallet_token_balances: id: "0xYourWallet" is_all: true 2. Identify which chains have the most of the target token. 3. Bridge from the chain with the highest balance. ``` --- ## When to Use Which | Scenario | MCP | Tool | |----------|-----|------| | Verify a single transaction | Blockscout | `get_transaction_info` | | Look up contract ABI or source | Blockscout | `get_contract_abi` / `inspect_contract_code` | | Read contract state | Blockscout | `read_contract` | | ENS resolution | Blockscout | `get_address_by_ens_name` | | Token holdings for an address | Blockscout | `get_tokens_by_address` | | Transfer history by time range | Blockscout | `get_transactions_by_address` | | Block details | Blockscout | `get_block_info` | | Multi-chain portfolio overview | Hive (hive-portfolio) | `get_wallet_token_balances` | | Social sentiment analysis | Hive (hive-sentiment) | Connect `hive_social_sentiment` sub-server | | NFT analytics | Hive (hive-nft) | Connect `hive_nft_analytics` sub-server | --- ## Source: skills/analytics/token-prices.md --- title: Token Prices and Market Data impact: HIGH impactDescription: "Price verification before bridge/swap operations" tags: prices, market-data, coingecko, cryptocom, ohlcv, trending, orderbook --- # Token Prices and Market Data Real-time and historical token pricing. Use before deBridge operations to verify token value, check price impact, or compare across chains. ## CoinGecko MCP (Primary — No API Key) CoinGecko covers 15,000+ coins across 200+ networks including on-chain DEX data via GeckoTerminal. ### Installation Hosted endpoint (no install, no key): ```bash claude mcp add --transport http coingecko https://mcp.api.coingecko.com/mcp ``` Local (one-shot): `npx -y @coingecko/coingecko-mcp` ### Key Tools | Tool | Parameters | Description | |------|-----------|-------------| | `get_simple_price` | `vs_currencies`* (string), `ids` (string), `symbols` (string), `names` (string), `include_market_cap`, `include_24hr_vol`, `include_24hr_change`, `include_last_updated_at`, `precision` | Current prices with optional market cap and volume | | `get_id_coins` | `id`* (coin ID), `market_data`, `localization`, `tickers`, `community_data`, `developer_data`, `sparkline` | Full coin data: description, links, market data | | `get_coins_markets` | `vs_currency`* (e.g., "usd"), `ids`, `symbols`, `names`, `category`, `order`, `per_page`, `page`, `sparkline`, `price_change_percentage`, `precision` | Paginated market data for multiple coins | | `get_search` | `query`* (string) | Search coins, categories, and exchanges by keyword | | `get_search_trending` | `show_max` (string) | Trending coins and NFTs | | `get_id_simple_token_price` | `id`* (platform), `contract_addresses`* (string), `vs_currencies`* (string), `include_market_cap`, `include_24hr_vol`, `include_24hr_change`, `include_last_updated_at`, `precision` | Token price by contract address on a platform | | `get_coins_contract` | `id`* (platform), `contract_address`* | Coin data by contract address | | `get_range_coins_market_chart` | `id`*, `vs_currency`*, `from`*, `to`*, `interval`, `precision` | Historical OHLCV in a date range | | `get_range_coins_ohlc` | `id`*, `vs_currency`*, `from`*, `to`*, `interval`* | OHLC candlestick data in a date range | | `get_tokens_networks_onchain_info` | `network`*, `address`* | On-chain token info via GeckoTerminal | ### CoinGecko Coin IDs CoinGecko uses slug-style IDs (not ticker symbols): - ETH → `ethereum` - USDC → `usd-coin` - SOL → `solana` Call `get_search` or `get_id_coins` to resolve a symbol to its CoinGecko ID. ### Example: Check Price Before Bridging ``` 1. Call mcp__coingecko__get_simple_price: ids: "usd-coin" vs_currencies: "usd" include_24hr_change: true 2. Verify USDC is at expected peg ($1.00 ± 0.01). 3. If stable → proceed to ../swap/SKILL.md. If depegged → warn the user before proceeding. ``` --- ## Crypto.com Exchange MCP (No API Key — Hosted) Real-time exchange data from Crypto.com: orderbooks, recent trades, and OHLCV candles. Complements CoinGecko by providing exchange-level market microstructure data. ### Installation Hosted endpoint (no install, no key): ```bash claude mcp add --transport http cryptocom https://mcp.crypto.com/market-data/mcp ``` ### Key Tools | Tool | Parameters (\* = required) | Description | |------|-----------|-------------| | `get_instruments` | (none) | List all available trading instruments | | `get_instrument` | `instrument_name`\* | Instrument detail by ID | | `get_tickers` | `instrument_name` | Ticker(s) — price, volume, bid/ask for one or all instruments | | `get_ticker` | `instrument_name`\* | Single ticker for an instrument | | `get_index_price` | `instrument_name`\* | Index price for an instrument | | `get_mark_price` | `instrument_name`\* | Mark price for an instrument | | `get_book` | `instrument_name`\*, `depth` (max 150) | Order book snapshot (bids/asks) | | `get_trades` | `instrument_name`\*, `count` (max 150) | Recent trades (default 10) | | `get_candlestick` | `instrument_name`\*, `timeframe`\* | OHLCV candles (up to 50) | Instrument names use underscore format: `BTC_USDT`, `ETH_USDT`, `SOL_USDT`, etc. Call `get_instruments` to list all. ### Example: Check BTC Market Depth Before Large Swap ``` 1. Call mcp__cryptocom__get_book: instrument_name: "BTC_USDT" depth: 20 2. Review bid/ask spread and depth to estimate slippage. 3. Call mcp__cryptocom__get_candlestick: instrument_name: "BTC_USDT" timeframe: "4h" 4. Check recent price trend before proceeding with the bridge. ``` --- ## mcp-crypto-price (No API Key — Local) Real-time prices, market analysis with exchange volume distribution, and historical trend analysis. Uses the CoinCap public API. ### Installation ```bash claude mcp add crypto-price -- npx -y mcp-crypto-price ``` One-shot: `npx -y mcp-crypto-price` ### Key Tools | Tool | Parameters (\* = required) | Description | |------|-----------|-------------| | `get-crypto-price` | `symbol`\* (e.g., "BTC") | Real-time price, 24h change, volume, market cap | | `get-market-analysis` | `symbol`\* | Top 5 exchanges by volume with price per exchange and volume distribution % | | `get-historical-analysis` | `symbol`\*, `interval` (m1/m5/m15/m30/h1/h2/h6/h12/d1), `days` (1-30) | Historical data with trend analysis, high/low, volatility metrics | | `get-top-assets` | `limit` (1-50, default 10) | Top cryptocurrencies ranked by market cap | ### Example: Pre-Bridge Market Analysis ``` 1. Call mcp__crypto_price__get-market-analysis: symbol: "ETH" 2. Review which exchanges have the most volume and whether prices are consistent across them. 3. Call mcp__crypto_price__get-historical-analysis: symbol: "ETH" interval: "h1" days: 7 4. Check volatility metrics before committing to the swap. ``` --- ## When to Use Which | Scenario | MCP | Tool | |----------|-----|------| | Quick price check by coin name | CoinGecko | `get_simple_price` | | Price by contract address | CoinGecko | `get_coins_contract` or `get_id_simple_token_price` | | Historical OHLCV chart (by coin ID) | CoinGecko | `get_range_coins_market_chart` | | On-chain DEX token data | CoinGecko | `get_tokens_networks_onchain_info` (GeckoTerminal) | | Trending coins and markets | CoinGecko | `get_search_trending` | | Exchange orderbook depth | Crypto.com | `get_book` | | Exchange-level OHLCV candles | Crypto.com | `get_candlestick` | | Recent exchange trades | Crypto.com | `get_trades` | | Exchange volume distribution | mcp-crypto-price | `get-market-analysis` | | Historical volatility and trends | mcp-crypto-price | `get-historical-analysis` | --- ## Source: skills/common/SKILL.md --- name: debridge-common description: > Shared prerequisite for all deBridge agent skills. Runs three stages: ENVIRONMENT_DETECTION (CLI, MCP Desktop, browser, headless, chat-only), ACCESS_SETUP (streaming MCP, stdio MCP via @debridge-finance/debridge-mcp, SDK), and WALLET_DISCOVERY (auto-discover all signers and resolve wallet addresses). Run this first before any deBridge operation. Use whenever the user mentions deBridge for the first time in a session, asks about supported chains, needs to connect to deBridge MCP, or wants to check what signing methods are available. Also use when troubleshooting deBridge connectivity, checking environment capabilities, or setting up RPC endpoints. license: MIT metadata: author: deBridge version: "0.1.0" --- # Environment Discovery ## Quick Reference | Want to... | Go to | |-------------------------------|------------------------------------------| | Detect environment type | ENVIRONMENT_DETECTION below | | Refresh skills to latest | Skill Freshness Check below | | Connect to deBridge MCP | ACCESS_SETUP below + [mcp-setup.md](mcp-setup.md) | | Discover wallets and signers | WALLET_DISCOVERY below | | Look up chain IDs and tokens | [chain-config.md](chain-config.md) | | Discover RPC endpoints | [rpc-discovery.md](rpc-discovery.md) | | Run bundled helper scripts | `scripts/` directory (balance, allowance, convert, RPC) | | Connect to MCP (all methods) | [mcpc-usage.md](mcpc-usage.md) | | Swap or bridge tokens | ../swap/SKILL.md | | Set up a wallet | ../wallets/SKILL.md | ## Detection Output After completing all three phases, record: ``` Environment: Access: Signer: Wallets: "": EVM: <0x_address> Solana: ``` Downstream skills use these values to select the right code paths. The `Wallets` section contains resolved standard addresses discovered during WALLET_DISCOVERY — pass these addresses (never wallet names) to all scripts and tools. --- ## ENVIRONMENT_DETECTION Run checks in order. Stop at the first match. ### 1.1 CLI Agent The agent can execute shell commands and has a runtime available. Detection: ```bash which node && echo "node available" ``` If bash works AND `node` is found → **Environment = CLI**. Capabilities: full filesystem, package install (`npm`), can run MCP stdio server locally, can read environment variables. ### 1.2 MCP Desktop The agent has MCP tools but limited or no bash access. Detection: tool list includes any `mcp__debridge__*` tool. The agent is running inside Claude Desktop, Cursor, Windsurf, or an IDE with MCP support. If MCP tools visible AND bash is unavailable or restricted → **Environment = MCP Desktop**. Capabilities: MCP tool calls, may have file read/write via IDE, cannot install packages. ### 1.3 Browser The agent runs in a browser context. Detection: `window.ethereum` or EIP-1193 provider is accessible. If browser APIs available → **Environment = Browser**. Capabilities: injected wallet, DOM access, HTTP fetch. Cannot run local commands. ### 1.4 Headless / Autonomous The agent runs programmatically without direct user interaction. Detection: running inside OpenHands, CrewAI, LangChain, AutoGPT, or a custom SDK application. Has network access. May or may not have bash. If programmatic agent framework detected → **Environment = Headless**. Capabilities: varies by framework. Check tool list and bash availability individually. ### 1.5 Chat-Only (Fallback) None of the above matched. The agent has no tool access. **Environment = Chat-only**. All instructions become guidance for the user to execute manually. --- ## Skill Freshness Check Optional: if skills may be outdated, read [skill-freshness.md](skill-freshness.md) for update methods (GitHub fetch, MCP resources, llms.txt). Otherwise proceed with bundled skills. --- ## Installing npm Packages When **Environment = CLI** or **Headless** with Node.js available, npm packages (MCP servers, SDKs, CLIs, utilities) can be installed in two ways: **`npx -y `** — downloads, runs once, discards. Use for: - First-time exploration or trying a tool - One-off queries during a conversation - CI/CD pipelines and ephemeral environments - Any situation where the package is not needed again **`npm install -g `** — installs permanently. Use for: - Agent harnesses that start the package repeatedly - Long-lived processes and recurring scripts - Projects that need reproducible, version-pinned dependencies (add to `devDependencies` in `package.json` instead of `-g`) | Scenario | Command | Why | |----------|---------|-----| | Connect to deBridge MCP | `claude mcp add --transport http debridge https://agents.debridge.com/mcp` | Streaming, no install needed | | Try a CLI tool | `npx -y ethers` | Quick one-shot use | | Build a trading bot | `npm install ethers viem` | Pinned in `package.json`, no re-download | | CI/CD pipeline | `npx -y ` | Clean environment each run | This applies to all npm packages referenced in downstream skills — MCP servers, signing libraries, SDKs, and utilities. ### Connecting to deBridge MCP Without Native Streamable HTTP Support For environments that support Streamable HTTP, connect directly to `https://agents.debridge.com/mcp` (see [mcp-setup.md](mcp-setup.md)). For environments that only support stdio transport, use `@debridge-finance/debridge-mcp` — a thin stdio proxy. Read [mcpc-usage.md](mcpc-usage.md) for all connection methods. Quick start (stdio): `claude mcp add debridge npx -- -y @debridge-finance/debridge-mcp@latest` --- ## ACCESS_SETUP ### 2.1 Probe for Existing MCP Connection Call `mcp__debridge__get_supported_chains` (no parameters). - **Returns chain data** → MCP is already connected. Access = **streaming-mcp** or **stdio-mcp**. Skip to WALLET_DISCOVERY. - **Tool not found** → MCP not connected. Continue to 2.2. ### 2.2 Set Up MCP by Environment | Environment | Recommended Method | Action | |--------------|--------------------|----------------------------------------------------| | CLI | streaming-mcp | `claude mcp add --transport http debridge https://agents.debridge.com/mcp` | | CLI (stdio) | stdio proxy | `claude mcp add debridge npx -- -y @debridge-finance/debridge-mcp@latest` | | MCP Desktop | streaming-mcp | Read [mcp-setup.md](mcp-setup.md) for client config | | Browser | manual | Guide user to set up an MCP-capable environment | | Headless | stdio-mcp | Read [mcp-setup.md](mcp-setup.md) for SDK or stdio proxy setup | | Chat-only | manual | Guide user to set up an MCP-capable environment | #### CLI: Streamable HTTP (preferred) If the environment supports Streamable HTTP transport, connect directly to the hosted endpoint: ```bash claude mcp add --transport http debridge https://agents.debridge.com/mcp ``` This requires restarting the Claude Code session. After restart, all `mcp__debridge__*` tools are available. #### CLI: Stdio Proxy (fallback for stdio-only environments) If the environment only supports stdio transport, use `@debridge-finance/debridge-mcp` as a local proxy: ```bash claude mcp add debridge npx -- -y @debridge-finance/debridge-mcp@latest ``` This requires restarting the Claude Code session. The proxy forwards all requests to `https://agents.debridge.com/mcp` transparently. Read [mcpc-usage.md](mcpc-usage.md) for all connection methods and configuration details. For Claude Desktop, Cursor, or programmatic SDK setup, read [mcp-setup.md](mcp-setup.md). ### 2.3 Future Access Methods These are **not available yet** but will be supported: - **`@debridge/sdk`** — TypeScript/JavaScript SDK, installable via npm. COMING SOON. - **`@debridge/cli`** — Command-line tool for bridge/swap. COMING SOON. When available, this skill will add detection and routing for them. ### 2.4 Verify Connection After setup, call `mcp__debridge__get_supported_chains` again. - Returns chain data → MCP is working. Proceed to WALLET_DISCOVERY. - Fails → read [mcp-setup.md](mcp-setup.md) troubleshooting section. --- ## WALLET_DISCOVERY A signer is needed for on-chain transactions (bridge, swap, token approval). deBridge requires signing EIP-712 typed data messages and standard EVM transactions. **Auto-discovery is mandatory.** When the user asks to check balances, bridge, swap, or perform any on-chain operation, the agent MUST automatically discover all available signers and resolve their wallet addresses — never ask the user for an address or wallet name. Run the checks below in order, collect ALL matches (do not stop at the first), then use the highest-priority signer for signing operations. After discovery, record all found wallets in the Detection Output (see top of this file) so downstream skills can use them without re-running discovery. Check in order. Collect all matches. ### 3.1 OWS (Open Wallet Standard) **Detection:** ```bash which ows && echo "available" ``` Or check for the Node.js SDK: ```bash node -e "require('@open-wallet-standard/core')" 2>/dev/null && echo "ows-node" ``` If any available → **Signer = ows**. **Address discovery — resolve all addresses now:** ```bash ows wallet list ``` Parse the output to extract addresses for each chain. The output format is: ``` ID: Name: Secured: ✓ (encrypted) eip155:1 → 0x solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp → ... Created: ``` Parsing rules: - Wallet name is on the `Name:` line (e.g., `Name: default`). - Each chain address is indented and follows the pattern `: →
`. - EVM address: extract from any `eip155:` line — all EVM chains share the same address. - Solana address: extract from the `solana:` line. - If multiple wallets exist, discover addresses for ALL of them. **Store the resolved standard addresses** (e.g., `0x000A...9c30` for EVM, `B7Z1...SUr` for Solana). Always pass these standard addresses — never wallet names — to scripts and downstream tools. OWS provides local self-custody signing with encrypted keys, policy-gated access, and multi-chain support (EVM, Solana, Tron). Recommended for CLI and agent environments — see ../wallets/SKILL.md Option 1 for setup. ### 3.2 Private Key in Environment Use the bundled `env-keys.mjs` script to scan environment variables and `.env` files in one step. The script never prints raw key values — only variable names, sources, chain types, and derived addresses. **Detection and address discovery (single command):** ```bash node scripts/env-keys.mjs ``` Human-readable output shows a table of discovered keys with their source, chain, and derived address. Use `--json` for machine-readable output: ```bash node scripts/env-keys.mjs --json ``` JSON output format: ```json [ { "name": "PRIVATE_KEY", "source": "env", "chain": "evm", "address": "0x...", "format": "hex-0x" }, { "name": "SOLANA_PRIVATE_KEY", "source": ".env", "chain": "solana", "address": "B7Z1...", "format": "json-array" } ] ``` If any keys found → **Signer = env-privkey**. Record the derived addresses in the Detection Output. The script scans (in priority order): 1. Environment variables: `PRIVATE_KEY`, `*_PRIVATE_KEY`, `*_KEY` (filtered by format) 2. `.env` in current directory 3. `.env.local` in current directory 4. `~/.env` in home directory **Security warnings (issued automatically by the script):** - Keys found in `.env` files on disk trigger a plaintext storage warning - Keys found in environment variables trigger a weaker warning - Both recommend migrating to OWS for encrypted self-custody 🚨 **If keys are found in files on disk**, relay the script's warning and recommend: > 1. Move to OWS: `curl -fsSL https://docs.openwallet.sh/install.sh | bash && ows wallet create` > 2. Delete the file containing the key after migrating > 3. Rotate the key if the file was ever committed to git or shared ⚠️ CAUTION: Never log, print, or include private key values in any output. The script enforces this — do not bypass it with ad-hoc shell commands like `echo $PRIVATE_KEY` or `grep` that could leak key material. ### 3.3 Foundry Cast **Detection:** ```bash which cast && echo "available" ``` If available → **Signer = foundry-cast**. Cast supports EIP-712 signing (`cast wallet sign --data`) and raw transaction sending (`cast send`). Requires a keystore or `--private-key` flag. **Address discovery:** ```bash # List cast wallets/keystores cast wallet list 2>/dev/null ``` ### 3.4 Browser Wallet (EIP-1193) If `window.ethereum` exists → **Signer = browser-wallet**. Supports `eth_signTypedData_v4` for EIP-712 and `eth_sendTransaction` for raw transactions. **Address discovery:** Call `eth_requestAccounts` to get the connected address. ### 3.5 ethers.js or viem **Detection:** ```bash node -e "require('ethers')" 2>/dev/null && echo "ethers" node -e "require('viem')" 2>/dev/null && echo "viem" ``` If either available → **Signer = ethers-viem**. Both support EIP-712 via `signer.signTypedData()` (ethers) or `walletClient.signTypedData()` (viem). Both can send raw transactions. **Address discovery:** Requires a private key or keystore — address comes from the key discovery in 3.2. ### 3.6 MCP-Managed Wallet Check if MCP tools include a signing or wallet tool: - `mcp__privy__eth_sendTransaction` → Privy embedded wallet is available. - Any other MCP signing tool → compatible MCP wallet. If available → **Signer = mcp-wallet**. Privy MCP handles signing server-side (keys in TEE). The agent passes `create_tx` output directly to Privy's `eth_sendTransaction` — no local key or RPC needed. See ../wallets/privy-embedded.md for setup. **Address discovery:** Call the MCP wallet's address/list endpoint to get managed addresses. ### 3.8 No Signer Available If none matched → **Signer = none**. Guide the user to set up a signer: - Recommended: install OWS (`curl -fsSL https://docs.openwallet.sh/install.sh | bash`) — multi-chain, encrypted keys, works with CLI/Node.js/Python - Quick start: set `PRIVATE_KEY` environment variable (EVM-only, plaintext) - For development: install Foundry (`curl -L https://foundry.paradigm.xyz | bash && foundryup`) - For delegated custody: set up Privy embedded wallet (see ../wallets/privy-embedded.md) - For all options: read ../wallets/SKILL.md ### 3.9 Discovery Output After completing all checks, record discovered wallets. Example: ``` Signers found: ows, env-privkey Primary signer: ows Wallets: OWS "default": EVM: 0x000A5539cD9505b44575c56f929C657c73899c30 Solana: B7Z1whe4TX3tVXwb93Nsd9U4f4QZfnuzm5DyUnKxVSUr env-privkey: EVM: 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18 ``` Pass these resolved addresses to all downstream operations — balance scripts, signing, bridging. Never pass wallet names to scripts. --- ## MCP Tool Reference | MCP Tool | Purpose | |-------------------------------------------------|--------------------------------------------| | `mcp__debridge__get_instructions` | Return the server's canonical workflow guide — call first | | `mcp__debridge__get_supported_chains` | List supported chains with IDs and names | | `mcp__debridge__search_tokens` | Find token by name, symbol, or address | | `mcp__debridge__create_tx` | Build cross-chain bridge/swap transaction | | `mcp__debridge__transaction_same_chain_swap` | Build same-chain swap transaction | All MCP tools expect token amounts in **raw units** (the smallest indivisible unit: wei for EVM, lamports for Solana) passed as strings. See [chain-config.md](chain-config.md) for decimals and conversion. --- ## Common Errors | Error | Cause | Fix | |----------------------------|--------------------------|------------------------------------------------------| | MCP tool not found | Server not connected | Re-run ACCESS_SETUP | | `npx` not found | Node.js not installed | Install Node.js 18+ | | Permission denied on key | Env var not exported | `export PRIVATE_KEY=...` in shell config | | Chain ID not recognized | Wrong ID format | Use deBridge chain IDs from [chain-config.md](chain-config.md) | | Amount format error | Human-readable passed | Convert to raw units first | ## References - [chain-config.md](chain-config.md) — Chain IDs, tokens, decimals, amount conversion - [mcp-setup.md](mcp-setup.md) — MCP configuration for all environments - [rpc-discovery.md](rpc-discovery.md) — RPC endpoint discovery via Chainlist --- ## Source: skills/common/chain-config.md --- title: Supported Chains and Token Configuration impact: HIGH impactDescription: "Required for all cross-chain operations — chain IDs, tokens, decimals" tags: chains, tokens, config, chain-id, decimals, amounts --- # Chain Configuration Use `mcp__debridge__get_supported_chains` for the live list. This reference covers common chains for quick lookup. ## EVM Chains | Chain | deBridge Chain ID | Native Token | Decimals | |-------------------|-------------------|--------------|----------| | Ethereum | 1 | ETH | 18 | | BNB Chain | 56 | BNB | 18 | | Polygon | 137 | POL | 18 | | Arbitrum One | 42161 | ETH | 18 | | Optimism | 10 | ETH | 18 | | Avalanche C-Chain | 43114 | AVAX | 18 | | Base | 8453 | ETH | 18 | | Linea | 59144 | ETH | 18 | | Sonic | 100000014 | S | 18 | | Berachain | 100000020 | BERA | 18 | | Mantle | 100000023 | MNT | 18 | | Abstract | 100000017 | ETH | 18 | Native token address on all EVM chains: `0x0000000000000000000000000000000000000000` ## Non-EVM Chains | Chain | deBridge Chain ID | Native Token | Decimals | Native Address | |--------|-------------------|--------------|----------|--------------------------------------------| | Solana | 7565164 | SOL | 9 | 11111111111111111111111111111111 | | Tron | 100000026 | TRX | 6 | T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb | ## deBridge-Internal Chain IDs Some chains use deBridge-internal IDs that differ from standard EVM chain IDs. Always use the deBridge chain ID when calling MCP tools. | Chain | deBridge ID | Standard Chain ID | |-----------|-------------|-------------------| | Neon | 100000001 | 245022934 | | Gnosis | 100000002 | 100 | | Sonic | 100000014 | 146 | | Abstract | 100000017 | 2741 | | Berachain | 100000020 | 80094 | | Mantle | 100000023 | 5000 | ## Common Tokens Use `mcp__debridge__search_tokens` for the live database. Quick reference: ### USDC | Chain | Address | Decimals | |----------|----------------------------------------------|----------| | Ethereum | 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 | 6 | | Arbitrum | 0xaf88d065e77c8cC2239327C5EDb3A432268e5831 | 6 | | Polygon | 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359 | 6 | | Base | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 | 6 | | Solana | EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v | 6 | ### USDT | Chain | Address | Decimals | |-----------|----------------------------------------------|----------| | Ethereum | 0xdAC17F958D2ee523a2206206994597C13D831ec7 | 6 | | BNB Chain | 0x55d398326f99059fF775485246999027B3197955 | 18 | | Arbitrum | 0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9 | 6 | | Tron | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | 6 | ## Amount Conversion All deBridge MCP tools expect amounts in **raw units** (the smallest indivisible unit of a token: wei for ETH, lamports for SOL) passed as strings. Formula: `raw_units = human_amount × 10^decimals` | Human Amount | Token | Decimals | Raw Units | |--------------|-------|----------|--------------------------| | "100" | USDC | 6 | "100000000" | | "1.5" | ETH | 18 | "1500000000000000000" | | "0.5" | SOL | 9 | "500000000" | | "50" | USDT | 6 | "50000000" | Always look up token decimals first via `mcp__debridge__search_tokens` if the token is not listed above. ### Bundled Script The `scripts/convert-amount.ts` helper handles conversion in both directions and can read decimals on-chain: ```bash npx tsx scripts/convert-amount.ts 100 6 # → {"raw":"100000000","decimals":6,"human":"100"} npx tsx scripts/convert-amount.ts 100 0xA0b8...eB48 1 # reads decimals from contract on Ethereum npx tsx scripts/convert-amount.ts 100000000 6 --reverse # raw → human ``` ## Dynamic Lookup For tokens not listed: 1. Call `mcp__debridge__search_tokens` with the token name, symbol, or address. 2. Response includes `address`, `decimals`, `chainId`, and `symbol`. 3. Use the returned values for subsequent MCP calls. For chains not listed: 1. Call `mcp__debridge__get_supported_chains` (no parameters). 2. Response includes all supported chain IDs and names. --- ## Source: skills/common/mcp-setup.md --- title: MCP Server Configuration by Environment impact: HIGH impactDescription: "Required for connecting agents to deBridge execution layer" tags: mcp, setup, streaming, stdio, claude-desktop, cursor, claude-code --- # deBridge MCP Setup ## Claude Desktop Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows): ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` --- ## Cursor / Windsurf / VS Code Add to `.cursor/mcp.json`, `.windsurf/mcp.json`, or equivalent IDE MCP config: ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` --- ## Claude Code (CLI) Streamable HTTP (preferred): ```bash claude mcp add --transport http debridge https://agents.debridge.com/mcp ``` Stdio proxy (for environments without Streamable HTTP support): ```bash claude mcp add debridge npx -- -y @debridge-finance/debridge-mcp@latest ``` --- ## Headless / Programmatic (MCP SDK) ### Streaming Transport ```typescript import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; const client = new Client({ name: "my-agent", version: "1.0.0" }); const transport = new StreamableHTTPClientTransport( new URL("https://agents.debridge.com/mcp") ); await client.connect(transport); const chains = await client.callTool({ name: "get_supported_chains", arguments: {} }); ``` --- ## Verification After configuration, verify the connection: 1. Call `mcp__debridge__get_supported_chains` (no parameters). 2. Expected: JSON array of chain objects with `chainId` and `chainName`. 3. If successful → MCP is ready. Proceed to WALLET_DISCOVERY in SKILL.md. 4. If failed → see troubleshooting below. --- ## Troubleshooting | Symptom | Cause | Fix | |----------------------------|---------------------------|----------------------------------------------------------| | Tool `mcp__debridge__*` not found | Server not configured | Add config per sections above | | Connection refused (stdio) | Node.js missing | Install Node.js 18+ | | Connection timeout | Network/firewall | Check HTTPS access to `agents.debridge.com` | | Auth error | None expected | deBridge MCP is public, no API key needed | --- ## Source: skills/common/mcpc-usage.md --- title: MCP Connection Methods impact: LOW impactDescription: "Setup guide for connecting to deBridge MCP across different environments" tags: debridge-mcp, proxy, cli, mcp-client, stdio, streamable-http --- # Connecting to deBridge MCP ## Recommended: Direct Streamable HTTP Connection If your environment supports Streamable HTTP MCP transport, connect directly to the hosted endpoint — no installation, no local process: ``` https://agents.debridge.com/mcp ``` ### Claude Code (CLI & IDE plugins) ```bash claude mcp add --transport http debridge https://agents.debridge.com/mcp ``` ### Generic Streamable HTTP configuration ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` This works in Claude Desktop, Cursor, Windsurf, VS Code (GitHub Copilot), Cline, Continue, Zed, and any agent that supports Streamable HTTP transport. --- ## Fallback: Stdio Proxy via @debridge-finance/debridge-mcp Some agent frameworks only support stdio transport and cannot connect to a remote HTTP endpoint directly. Use `@debridge-finance/debridge-mcp` — a thin stdio proxy that forwards all requests to the hosted deBridge MCP: ### Claude Code (CLI & IDE plugins) ```bash claude mcp add debridge npx -- -y @debridge-finance/debridge-mcp@latest ``` ### Generic stdio configuration ```json { "mcpServers": { "debridge": { "command": "npx", "args": ["-y", "@debridge-finance/debridge-mcp@latest"] } } } ``` ### Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `REMOTE_MCP_URL` | `https://agents.debridge.com/mcp` | Remote MCP endpoint to proxy to | | `MCP_TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` | | `PORT` | `3000` | HTTP listen port (HTTP mode only) | Key details: - The proxy dynamically discovers tools and resources from the upstream endpoint — no local tool definitions needed. - In stdio mode (default), it opens a long-lived connection to the upstream MCP and mirrors capabilities locally. - In HTTP mode (`MCP_TRANSPORT=http`), it runs an Express reverse proxy on `localhost:3000/mcp`. - Works anywhere `npx` is available — no global install required. --- After setup via either method, verify the connection by calling `mcp__debridge__get_supported_chains` (no parameters). If it returns chain data, MCP is ready. --- ## Source: skills/common/rpc-discovery.md --- title: RPC Endpoint Discovery via Chainlist impact: HIGH impactDescription: "Required for any direct chain interaction — balance queries, signing, tx sending" tags: rpc, chainlist, endpoints, provider, public-rpc, privacy --- # RPC Endpoint Discovery All direct chain interactions (balance queries, signing, sending transactions) require an RPC endpoint. This reference describes how to discover and select RPC endpoints programmatically using the Chainlist registry. ## RPC Resolution Order Check in order. Stop at the first match. 1. **Environment variable** — `$ETH_RPC_URL`, `$RPC_URL`, or chain-specific vars (`$ARB_RPC_URL`, `$BASE_RPC_URL`). 2. **User-provided RPC** — the user explicitly gave an RPC URL. 3. **Chainlist registry** — fetch and filter from `https://chainlist.org/rpcs.json`. ## Chainlist Registry `https://chainlist.org/rpcs.json` is a public JSON array of all known EVM chains with their RPC endpoints. ### Schema ```json { "name": "Ethereum Mainnet", "chainId": 1, "nativeCurrency": { "name": "Ether", "symbol": "ETH", "decimals": 18 }, "rpc": [ { "url": "https://eth.llamarpc.com", "tracking": "none", "isOpenSource": true }, { "url": "https://eth-mainnet.nodereal.io/v1/...", "tracking": "yes" } ], "explorers": [ { "name": "etherscan", "url": "https://etherscan.io", "standard": "EIP3091" } ], "isTestnet": false } ``` ### Key Fields | Field | Type | Purpose | |-------|------|---------| | `chainId` | number | EVM chain ID — use to match deBridge chain config | | `rpc[].url` | string | RPC endpoint URL | | `rpc[].tracking` | string | `"none"`, `"limited"`, `"yes"`, `"unspecified"` | | `rpc[].isOpenSource` | boolean | Whether the RPC implementation is open-source | | `nativeCurrency` | object | Native token name, symbol, and decimals | | `isTestnet` | boolean | Filter out testnets for production use | ### Tracking Values | Value | Meaning | Recommendation | |-------|---------|----------------| | `"none"` | No user tracking | Preferred — use these first | | `"limited"` | Aggregated analytics only | Acceptable fallback | | `"yes"` | Tracks users | Avoid unless no alternative | | `"unspecified"` | Unknown policy | Treat as `"limited"` | ## Fetching and Filtering ### Node.js ```typescript const resp = await fetch("https://chainlist.org/rpcs.json"); const chains = await resp.json(); function getRpcs(chainId: number): string[] { const chain = chains.find((c: any) => c.chainId === chainId && !c.isTestnet); if (!chain) return []; return chain.rpc .filter((r: any) => r.tracking === "none" || r.tracking === "limited" ) .filter((r: any) => !r.url.includes("${") && !r.url.includes("{") // skip template URLs with API key placeholders ) .map((r: any) => r.url); } // Example: get privacy-respecting Ethereum RPCs const ethRpcs = getRpcs(1); // → ["https://eth.llamarpc.com", "https://rpc.mevblocker.io", ...] ``` ### Bash (curl + jq) ```bash # Get first no-tracking RPC for a chain ID get_rpc() { local chain_id="$1" curl -sL https://chainlist.org/rpcs.json | jq -r --argjson id "$chain_id" ' .[] | select(.chainId == $id and .isTestnet != true) | .rpc[] | select(.tracking == "none") | select(.url | (contains("${") or contains("{")) | not) | .url ' | head -1 } # Example ETH_RPC=$(get_rpc 1) ARB_RPC=$(get_rpc 42161) ``` ## Mapping deBridge Chain IDs to Chainlist Some deBridge chains use internal IDs (see chain-config.md). Map to standard EVM chain IDs before querying Chainlist: | Chain | deBridge ID | Chainlist ID | |-------|-------------|--------------| | Sonic | 100000014 | 146 | | Berachain | 100000020 | 80094 | | Neon | 100000001 | 245022934 | | Gnosis | 100000002 | 100 | All other deBridge chain IDs match standard EVM chain IDs directly. ## RPC Health Check Public RPCs can be unreliable. Always verify connectivity before use: ```typescript // Node.js — quick health check async function checkRpc(url: string, timeoutMs = 3000): Promise { try { const controller = new AbortController(); setTimeout(() => controller.abort(), timeoutMs); const resp = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", method: "eth_blockNumber", params: [], id: 1 }), signal: controller.signal, }); const data = await resp.json(); return !!data.result; } catch { return false; } } ``` ```bash # Bash — quick health check check_rpc() { local url="$1" curl -s --max-time 3 -X POST "$url" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \ | jq -e '.result' > /dev/null 2>&1 } ``` ## Caching Chainlist data changes infrequently. Cache the full `rpcs.json` response: - **CLI agents**: cache to `/tmp/chainlist-rpcs.json`, refresh every 24 hours. - **Long-lived processes**: cache in memory, refresh every 6 hours. - **One-shot queries**: fetch fresh each time (< 500 KB). ## Bundled Scripts Two RPC discovery scripts with identical functionality — use whichever matches your runtime: | Script | Runtime | Import | |--------|---------|--------| | `scripts/rpc.mjs` | Node.js (ESM) | `import { getRpc } from "../common/scripts/rpc.mjs"` | | `scripts/rpc.ts` | TypeScript (`npx tsx`) | `import { getRpc } from "./rpc"` | Both support CLI usage: ```bash node scripts/rpc.mjs 42161 # → first healthy RPC for Arbitrum node scripts/rpc.mjs 42161 --all # list all RPCs node scripts/rpc.mjs 137 --json # → {"chainId":137,"rpc":"https://...","name":"Polygon"} node scripts/rpc.mjs 7565164 # → Solana RPC (env var or public fallback) ``` `rpc.mjs` also supports Solana (chain ID `7565164`) via `$SOLANA_RPC_URL` or a public fallback — Solana is not on Chainlist. Other scripts (`balance-evm.mjs`, `balance-solana.mjs`, `debridge-evm-bridge.mjs`, `debridge-solana-bridge.mjs`) import `rpc.mjs` for auto-discovery. ## Common Errors | Error | Cause | Fix | |-------|-------|-----| | All RPCs timeout | Network restriction or all endpoints overloaded | Try a different tracking tier, or use a paid RPC provider | | 401/403 from RPC | URL contains API key placeholder | Filter out template URLs containing `${` or `{` | | Wrong chain data | Used deBridge internal ID | Map to standard EVM chain ID first (table above) | | Stale block number | RPC node behind | Try the next RPC in the list | --- ## Source: skills/common/skill-freshness.md --- title: Skill Freshness Check impact: LOW impactDescription: "Optional — refresh skills to get latest chain support and bug fixes" tags: freshness, update, github, mcp-resources, llms-txt --- # Skill Freshness Check Skills evolve with new chain support, MCP tool changes, and bug fixes. Try methods in order; stop at the first success. ## Method 1: GitHub Raw Fetch (CLI, Headless with HTTP tools) Fetch the skill catalog and individual files directly from GitHub raw content. Detect the available HTTP tool: ```bash # Prefer: gh CLI (authenticated, no rate limit) gh api repos/debridge-finance/debridge-skills/contents/skills/index.json \ --jq '.content' | base64 -d # Or: curl curl -sL https://raw.githubusercontent.com/debridge-finance/debridge-skills/main/skills/index.json # Or: wget wget -qO- https://raw.githubusercontent.com/debridge-finance/debridge-skills/main/skills/index.json ``` Parse `index.json` to discover skills, then fetch individual SKILL.md files: ```bash curl -sL https://raw.githubusercontent.com/debridge-finance/debridge-skills/main/skills/bridge/SKILL.md ``` Agents with built-in web fetch (Claude Code `WebFetch`, OpenHands `browse`) can use the same raw URLs directly. ## Method 2: MCP Resources (MCP Desktop, any MCP-connected environment) If deBridge MCP is connected (confirmed during ACCESS_SETUP), the server at `https://agents.debridge.com/mcp` exposes skills as MCP resources. List and read them: ``` resources/list → returns available skill resources resources/read → fetch individual skill content by URI ``` This requires no filesystem access — works in sandboxed MCP Desktop environments. ## Method 3: llms.txt (any environment with HTTP fetch) Fetch the lightweight skill catalog: ``` https://agents.debridge.com/llms.txt ``` This returns skill names, descriptions, and links to individual SKILL.md files. Parse for the skills relevant to the current task. Works in any environment that can make HTTPS requests. ## No Update Available If none of the above work (no HTTP tools, no MCP), proceed with bundled/cached skills. They are functional but may be outdated. Inform the user: > "Using bundled deBridge skills. For the latest instructions, visit https://github.com/debridge-finance/debridge-skills" --- ## Source: skills/signing/SKILL.md --- name: debridge-signing description: > Sign and broadcast deBridge transactions. Routes to the correct signing method based on the detected signer: OWS local self-custody wallet, private key with ethers/viem, Foundry cast, browser wallet (MetaMask), or Privy embedded wallet. Use this skill whenever a deBridge transaction needs to be signed and sent on-chain — including bridge transactions, swap transactions, and token approvals. Also use when the user asks "how do I sign this transaction", "send the transaction", "approve the token", "broadcast to chain", "sign with OWS", "ows wallet", or needs help with EIP-712 typed data signing. This skill is called automatically by the bridge and swap workflows, but can also be used standalone for signing guidance. license: MIT metadata: author: deBridge version: "0.1.0" --- # Transaction Signing PREREQUISITE: Read ../common/SKILL.md for environment detection, auth, and chain configuration. ## Quick Reference | Want to... | Go to | |-----------------------------------|------------------------------------| | Sign with OWS (recommended) | [ows-signing.md](ows-signing.md) | | Sign with ethers.js or viem | [sdk-signer.md](sdk-signer.md) | | Sign with Foundry cast | [foundry-cast.md](foundry-cast.md)| | Sign with MetaMask / browser | [metamask.md](metamask.md) | | Sign via Privy MCP | [privy-mcp.md](privy-mcp.md) | | Set up a wallet from scratch | ../wallets/SKILL.md | ## What Needs Signing deBridge transactions from `mcp__debridge__create_tx` (cross-chain) or `mcp__debridge__transaction_same_chain_swap` (same-chain) return up to two transaction objects to sign: 1. **Token approval tx** (if allowance insufficient) — a standard EVM transaction calling `approve()` on the token contract. 2. **Bridge/swap tx** — an EVM transaction that may include EIP-712 typed data for DLN order creation. Both are standard `{to, data, value, chainId}` objects. Sign and broadcast to the source chain RPC. ## Signer Routing Use the `Signer` value from WALLET_DISCOVERY to select the right reference: | Signer value | Environment | Read this file | |-----------------|----------------|--------------------------------------| | ows | CLI | [ows-signing.md](ows-signing.md) | | env-privkey | CLI + Node.js | [sdk-signer.md](sdk-signer.md) | | env-privkey | CLI + cast | [foundry-cast.md](foundry-cast.md) | | foundry-cast | CLI | [foundry-cast.md](foundry-cast.md) | | browser-wallet | Browser | [metamask.md](metamask.md) | | ethers-viem | CLI / Headless | [sdk-signer.md](sdk-signer.md) | | mcp-wallet | Any | [privy-mcp.md](privy-mcp.md) | | none | Any | ../wallets/SKILL.md — set up first | ### Resolving env-privkey When Signer = `env-privkey`, a private key exists but a signing library is still needed. Pick based on what is available: 1. Node.js + ethers or viem installed → [sdk-signer.md](sdk-signer.md) 2. `cast` available → [foundry-cast.md](foundry-cast.md) 3. None of the above → install one: `npm install ethers` is the fastest path. ## Transaction Flow After `mcp__debridge__create_tx` or `mcp__debridge__transaction_same_chain_swap` returns tx data: ### Step 0: Preflight Checks Before signing, the agent MUST verify: 1. **Native balance for gas + fixFee** — Parse `fixFee` (wei) and `estimatedTransactionFee.total` from the response. Check that the wallet's native balance on the source chain covers both. If insufficient, stop and tell the user how much more they need. 2. **ERC-20 allowance** (EVM only, non-native tokens) — If the response does NOT include `approveTx`, the agent MUST still check the token's allowance for the bridge contract (`tx.to`). Use `scripts/erc20-approve.mjs` to check and approve if needed. Do NOT assume the MCP always returns `approveTx` — it may not. 3. **SOL rent/fees** (Solana source) — Solana bridge txs require ~0.024 SOL for rent deposits + tx fees, on top of the bridge amount. Check SOL balance before signing. ### Step 1: Check for Approval If the response includes an approval transaction (`approveTx`): 1. Sign and send the approval tx first. 2. Wait for confirmation (1 block). 3. Proceed to Step 2. If no `approveTx` but source token is ERC-20, run `scripts/erc20-approve.mjs` to check/approve (see Step 0). ### Step 2: Sign and Send Bridge Transaction 1. Take the main tx object (`tx` field from `create_tx` response). 2. Sign with the detected signer. 3. Broadcast to the source chain RPC. 4. Record the transaction hash. ### Step 3: Hand Off to Monitoring (cross-chain only) For cross-chain bridges, pass the tx hash and order ID to ../swap/monitoring.md for order tracking. Same-chain swaps settle in a single transaction — no monitoring needed. ## RPC Endpoints Most signers need an RPC connection to the source chain: - OWS: for EVM, `ows sign tx` handles signing locally — broadcast via RPC separately; for Solana, set `SOLANA_RPC_URL` or use the default public RPC - ethers/viem: pass RPC URL to provider constructor - cast: use `--rpc-url` flag - browser wallet: uses the wallet's connected RPC - Privy MCP: handles RPC internally — no RPC URL needed from the agent Use public RPCs or the user's configured RPC. Prefer user-provided RPCs or environment variables (`$ETH_RPC_URL`, `$RPC_URL`) over hardcoded defaults. The balance query skills include public RPCs as fallback defaults — override them when the user has configured RPCs. For programmatic RPC discovery from Chainlist, read ../common/rpc-discovery.md. ## Common Errors | Error | Cause | Fix | |-----------------------------|--------------------------------|-------------------------------------------------| | Insufficient funds for gas | Wallet has no native token | Fund wallet with ETH/native token on source chain | | Nonce too low | Pending tx or state mismatch | Wait for pending tx or reset nonce | | Transaction reverted | Approval not confirmed yet | Wait for approval confirmation before bridge tx | | Invalid signature | Wrong chain ID in signer | Ensure signer chain ID matches source chain | ## References - [ows-signing.md](ows-signing.md) — OWS local self-custody signing (EVM, Solana, Tron) - [sdk-signer.md](sdk-signer.md) — ethers.js and viem signing - [foundry-cast.md](foundry-cast.md) — Foundry cast CLI signing - [metamask.md](metamask.md) — Browser wallet signing - [privy-mcp.md](privy-mcp.md) — Privy embedded wallet signing via MCP --- ## Source: skills/signing/foundry-cast.md --- title: Signing with Foundry Cast impact: HIGH impactDescription: "Primary signing method for developers with Foundry toolchain" tags: signing, foundry, cast, cli, eip-712, private-key --- # Foundry Cast Signing ## Prerequisites ```bash which cast || echo "Install Foundry: curl -L https://foundry.paradigm.xyz | bash && foundryup" ``` ## Sign and Send Transaction Given tx data from `mcp__debridge__create_tx`: ### With private key from environment ```bash cast send "$TX_TO" --data "$TX_DATA" \ --value "$TX_VALUE" \ --rpc-url "$RPC_URL" \ --private-key "$PRIVATE_KEY" \ --chain-id "$CHAIN_ID" ``` ### With Foundry keystore ```bash cast send "$TX_TO" --data "$TX_DATA" \ --value "$TX_VALUE" \ --rpc-url "$RPC_URL" \ --account my-account \ --chain-id "$CHAIN_ID" ``` Keystore accounts are stored in `~/.foundry/keystores/`. Create one: ```bash cast wallet import my-account --interactive ``` ⚠️ CAUTION: Prefer keystore over `--private-key` flag. The flag may leak the key to shell history. ## Sign EIP-712 Typed Data ```bash cast wallet sign-auth \ --private-key "$PRIVATE_KEY" \ --rpc-url "$RPC_URL" \ "$TYPED_DATA_JSON" ``` For complex typed data, write the JSON to a temp file: ```bash echo "$TYPED_DATA_JSON" > /tmp/typed-data.json cast wallet sign --data --from "$WALLET_ADDRESS" /tmp/typed-data.json rm /tmp/typed-data.json ``` ## Approval Transaction Send token approval before the bridge tx: ```bash # Approve max allowance for the spender cast send "$TOKEN_ADDRESS" \ "approve(address,uint256)" "$SPENDER_ADDRESS" "$(cast max-uint)" \ --rpc-url "$RPC_URL" \ --private-key "$PRIVATE_KEY" ``` Wait for confirmation before sending the bridge tx: ```bash cast receipt "$APPROVAL_TX_HASH" --rpc-url "$RPC_URL" ``` ## Useful Cast Commands | Command | Purpose | |---------|---------| | `cast balance $ADDR --rpc-url $RPC` | Check native token balance | | `cast call $TOKEN "balanceOf(address)" $ADDR --rpc-url $RPC` | Check token balance | | `cast call $TOKEN "allowance(address,address)" $OWNER $SPENDER --rpc-url $RPC` | Check allowance | | `cast chain-id --rpc-url $RPC` | Verify chain ID | | `cast tx $HASH --rpc-url $RPC` | Get transaction details | ## Common Errors | Error | Fix | |-------|-----| | `insufficient funds` | Fund wallet with native token for gas | | `nonce too low` | Wait for pending tx: `cast nonce $ADDR --rpc-url $RPC` | | `unknown account` | Keystore not found — check `ls ~/.foundry/keystores/` | --- ## Source: skills/signing/metamask.md --- title: Browser Wallet Signing (MetaMask / EIP-1193) impact: HIGH impactDescription: "Required for browser-based agent environments with injected wallet" tags: signing, metamask, browser, eip-1193, eip-712, injected-provider --- # Browser Wallet Signing ## Prerequisites Verify injected provider: ```javascript if (typeof window.ethereum === "undefined") { throw new Error("No browser wallet detected. Install MetaMask or another EIP-1193 wallet."); } ``` ## Connect Wallet ```javascript const accounts = await window.ethereum.request({ method: "eth_requestAccounts", }); const walletAddress = accounts[0]; ``` ## Switch Chain Ensure the wallet is on the correct source chain before signing: ```javascript await window.ethereum.request({ method: "wallet_switchEthereumChain", params: [{ chainId: "0x" + sourceChainId.toString(16) }], }); ``` ## Sign and Send Transaction Given tx data from `mcp__debridge__create_tx`: ```javascript const txHash = await window.ethereum.request({ method: "eth_sendTransaction", params: [{ from: walletAddress, to: tx.to, data: tx.data, value: tx.value ? "0x" + BigInt(tx.value).toString(16) : "0x0", }], }); ``` The wallet will prompt the user for confirmation. Wait for the user to approve. ## Sign EIP-712 Typed Data For DLN order signatures: ```javascript const signature = await window.ethereum.request({ method: "eth_signTypedData_v4", params: [walletAddress, JSON.stringify(typedData)], }); ``` The `typedData` object must include `domain`, `types`, `primaryType`, and `message` fields. ## Approval Transaction Send token approval before the bridge tx: ```javascript const approveTxHash = await window.ethereum.request({ method: "eth_sendTransaction", params: [{ from: walletAddress, to: approveTxData.to, data: approveTxData.data, value: "0x0", }], }); // Wait for confirmation before proceeding to bridge tx ``` ## Common Errors | Error | Fix | |-------|-----| | User rejected request | User declined in wallet popup — retry or explain why approval is needed | | Chain mismatch | Call `wallet_switchEthereumChain` before signing | | `eth_signTypedData_v4` not supported | Wallet is outdated — update MetaMask or use `eth_signTypedData_v3` | --- ## Source: skills/signing/ows-signing.md --- title: deBridge Signing with OWS (Open Wallet Standard) impact: HIGH impactDescription: "Local self-custody signing for deBridge transactions and messages via OWS SDK/CLI" tags: ows, signing, self-custody, local-key, evm, solana, tron, deBridge --- # deBridge Signing with OWS Local self-custody signing for deBridge transactions and messages using OWS wallets. Keys stay encrypted on the user's machine and are decrypted only in-process during signing — never exposed. OWS supports nine chain families. The ones that overlap with deBridge, sorted by relevance: | Chain family | OWS signing | deBridge support | Notes | |--------------|-------------|------------------|-------| | EVM | `ows sign tx` / `ows sign message` | All EVM chains (Ethereum, Arbitrum, Base, Polygon, etc.) | Standard EVM tx signing works directly | | Solana | `ows sign message --encoding hex` | Solana (chainId `7565164`) | Needs scripted format adaptation — see below | | Tron | `ows sign tx` / `ows sign message` | Tron (chainId `100000026`) | base58check addresses, 6-decimal TRX | OWS also supports Bitcoin, Cosmos, TON, Sui, Spark, and Filecoin — these are not yet supported by deBridge. ## EVM Sign + Broadcast For EVM chains, `ows sign tx` returns a **raw signature** (`{signature, recovery_id}`), not a broadcast-ready signed transaction. You must assemble the signed tx before broadcasting. The bundled script handles this: ```bash # Agent calls MCP to get the quote, then pipes create_tx JSON to the script echo '' | node scripts/debridge-evm-bridge.mjs --src-chain 137 ``` The agent MUST call `mcp__debridge__create_tx` first, then pipe the JSON response to this script. The script handles: build unsigned EIP-1559 tx → sign with `ows sign tx` CLI → extract r/s/v from signature → assemble → broadcast → wait for confirmation. It also handles `approveTx` (ERC-20 allowance) automatically. **Do NOT call MCP from inside JS scripts.** The agent is the MCP client — scripts only handle signing and broadcasting. ### OWS EVM signature format `ows sign tx --json` returns: ```json {"signature": "<128-char hex>", "recovery_id": 0} ``` - `r` = first 64 hex chars, `s` = next 64 hex chars, `v` = `recovery_id` (0 or 1) - These must be attached to an ethers.js `Transaction` object via `tx.signature = Signature.from({r, s, v})` before broadcasting `tx.serialized` --- ## Solana Sign + Broadcast Pipeline The rest of this section covers the Solana-specific signing pipeline. Solana requires a scripted pipeline because of three format differences that the script handles automatically: 1. **Blockhash insertion** — deBridge returns a placeholder (all zeros) since blockhashes expire in ~60–90s; the script fetches a fresh one. 2. **Byte-range extraction** — Solana V0 signatures cover only the message bytes (offset 65+), not the full serialized tx; the script extracts the right range for OWS `signMessage()`. 3. **Encoding conversion** — OWS returns a hex signature; Solana RPC expects base64; the script converts before broadcast. Bundled scripts in `scripts/`: | Script | What it does | Install | |--------|--------------|---------| | `scripts/debridge-solana-bridge.mjs` | **Sign + broadcast**: reads create_tx JSON from stdin → sign → broadcast (recommended) | `npm install @open-wallet-standard/core` | | `scripts/ows-solana-sign.mjs` | Sign-only: takes tx hex, signs and broadcasts | `npm install @open-wallet-standard/core` | **Prefer `debridge-solana-bridge.mjs`** — the agent calls MCP to get the quote, then pipes the JSON to the script via stdin. This avoids passing large hex strings through shell variables. ## Prerequisites - OWS wallet created (`ows wallet create`) with a funded Solana address - deBridge MCP configured (see ../common/mcp-setup.md) - OWS SDK installed for your environment (see Install table above) - Solana RPC endpoint — set `SOLANA_RPC_URL` env var or use the default public RPC (see ../common/rpc-discovery.md) ## Step 1: Get a deBridge Quote Call `mcp__debridge__create_tx` with Solana as the source chain (chainId `7565164`). The response `tx.data` is a hex-encoded Solana V0 versioned transaction with a placeholder blockhash (all zeros). ## Step 2: Sign and Broadcast ⚠️ CAUTION: This executes a real transaction. ### Node.js ```bash node scripts/ows-solana-sign.mjs ``` Examples: ```bash # Basic — sign and broadcast, print tx hash node scripts/ows-solana-sign.mjs 01000000...abcdef agent-treasury # Custom RPC + JSON output (for piping to monitoring) node scripts/ows-solana-sign.mjs 01000000...abcdef agent-treasury \ --rpc https://my-rpc.example.com --json # Using SOLANA_RPC_URL env var SOLANA_RPC_URL=https://my-rpc.example.com \ node scripts/ows-solana-sign.mjs 01000000...abcdef agent-treasury ``` ### What the Script Does The script performs five steps (see source for detailed comments): 1. Parse the hex-encoded Solana V0 transaction from deBridge 2. Fetch a fresh blockhash from Solana RPC (`getLatestBlockhash`) 3. Insert the blockhash into the transaction at the correct offset 4. Sign the message bytes (offset 65+) via OWS SDK `signMessage(wallet, chain, message, undefined, "hex")` (Node.js) / `sign_message(wallet, chain, message, encoding="hex")` (Python) 5. Assemble the final transaction, convert to base64, and broadcast via `sendTransaction` All steps run in a single invocation because blockhashes expire in ~60–90 seconds. ### Output - Default: prints the transaction signature (hash) on success - `--json`: prints the full Solana RPC response as JSON - Exit code 1 on error (RPC failure, broadcast rejection) ## Example Prompts Cross-chain from Solana: - "Bridge 10 USDC from Solana to Arbitrum" - "Swap 2 SOL from Solana to ETH on Ethereum" Quote only: - "Get a deBridge quote for 100 USDC from Solana to Base, don't execute yet" ## Security Notes - OWS wallet keys are encrypted locally and decrypted only in-process during signing — never exposed in script output. - Use `confirmed` commitment (not `finalized`) for the freshest blockhash. - For testing, use small amounts to minimize risk from blockhash expiry or failed broadcasts. - deBridge MCP is read-only by itself — it generates tx data but cannot sign or broadcast. - Account for ~0.024 SOL in rent/fees on top of the bridge amount when funding the wallet. ## Troubleshooting | Issue | Fix | |-------|-----| | `Cannot find module '@open-wallet-standard/core'` | Run `npm install @open-wallet-standard/core` | | No `ows sign send-tx` for Solana | `signAndSend` is optional in the OWS spec and not available as a CLI command. Use the bundled scripts | | `ows sign tx` produces invalid signature | Signs the exact bytes you pass without extracting Solana message portion. The scripts handle extraction automatically | | Blockhash expired | All steps run in one invocation (~60–90s window). Re-run the script | | Transaction simulation failed | Check wallet has enough SOL for rent/fees (~0.024 SOL) on top of the bridge amount | | Signature verification failed | Ensure you're using the scripts (they insert the blockhash before signing, as required) | --- ## Source: skills/signing/privy-mcp.md --- title: Signing via Privy MCP impact: HIGH impactDescription: "Server-side signing for zero-UI agent workflows via Privy embedded wallet" tags: signing, privy, mcp, embedded-wallet, tee, eth_sendTransaction --- # Privy MCP Signing Privy MCP handles signing and broadcasting server-side. The agent passes transaction data directly to Privy's `eth_sendTransaction` tool — no local private key, no RPC URL, no signing library needed. ## Prerequisites Privy MCP must be configured and connected. If not set up, read ../wallets/privy-embedded.md first. Verify Privy MCP is available by checking for `mcp__privy__eth_sendTransaction` in the tool list. ## Sign and Send Transaction Given tx data from `mcp__debridge__create_tx`: ``` Call mcp__privy__eth_sendTransaction: - to: "0xeF4fB24aD0916217251F553c0596F8Edc630EB66" - value: "1000000000000000" - data: "0xb9303701..." - chain_id: 42161 ``` The `create_tx` response fields map directly to Privy's parameters — no format conversion needed. Privy signs with the embedded wallet's key (secured in TEE) and broadcasts to the chain's RPC. Returns the transaction hash. ## Approval Transaction If `create_tx` returns an `approveTx`, send it first: ``` Call mcp__privy__eth_sendTransaction: - to: - value: "0" - data: - chain_id: ``` Wait for confirmation before sending the bridge/swap transaction. ## Sign EIP-712 Typed Data If Privy MCP exposes a typed data signing tool (e.g., `mcp__privy__eth_signTypedData`), use it directly: ``` Call mcp__privy__eth_signTypedData: - domain: - types: - primaryType: - message: ``` If the tool is not available, the standard `eth_sendTransaction` flow handles most deBridge operations without separate EIP-712 signing. ## Key Differences from Local Signers | Aspect | Local signers | Privy MCP | |-----------------|----------------------------|-----------------------------------| | Private key | Agent has access | Never exposed — managed in TEE | | RPC connection | Agent must provide | Handled by Privy internally | | Gas estimation | Agent must estimate | Handled by Privy internally | | Nonce management| Agent must track | Handled by Privy internally | | Chain switching | Agent must configure | Pass `chain_id` per call | ## Common Errors | Error | Fix | |-------|-----| | Privy MCP tool not found | Privy MCP not configured — read ../wallets/privy-embedded.md | | Insufficient funds | Fund Privy wallet with token + native gas on source chain | | Invalid chain_id | Use standard EVM chain IDs (not deBridge internal IDs). For chains with deBridge-internal IDs (Sonic, Berachain, Neon, Gnosis, Mantle, Abstract), use the standard chain ID from the mapping table in ../common/chain-config.md | | App Secret invalid | Regenerate at [dashboard.privy.io](https://dashboard.privy.io) and reconfigure MCP | --- ## Source: skills/signing/sdk-signer.md --- title: Signing with ethers.js or viem impact: HIGH impactDescription: "Primary signing method for Node.js CLI and headless agents" tags: signing, ethers, viem, eip-712, private-key, typescript, javascript --- # ethers.js / viem Signing ## Setup ```typescript // ethers v6 import { ethers } from "ethers"; const provider = new ethers.JsonRpcProvider(process.env.RPC_URL); const wallet = new ethers.Wallet(process.env.PRIVATE_KEY, provider); ``` ```typescript // viem import { createWalletClient, http } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { mainnet } from "viem/chains"; const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`); const client = createWalletClient({ account, chain: mainnet, // replace with source chain transport: http(process.env.RPC_URL), }); ``` ⚠️ CAUTION: Never log or expose `PRIVATE_KEY`. Read from environment only. ## Sign and Send Transaction Given tx data from `mcp__debridge__create_tx`: ```typescript // ethers v6 const txResponse = await wallet.sendTransaction({ to: tx.to, data: tx.data, value: tx.value, chainId: tx.chainId, gasLimit: tx.gasLimit, // if provided }); const receipt = await txResponse.wait(1); // wait 1 confirmation console.log("tx hash:", receipt.hash); ``` ```typescript // viem const hash = await client.sendTransaction({ to: tx.to as `0x${string}`, data: tx.data as `0x${string}`, value: BigInt(tx.value || "0"), chain: sourceChain, // match source chain }); ``` ## Sign EIP-712 Typed Data For DLN order signatures: ```typescript // ethers v6 const signature = await wallet.signTypedData( typedData.domain, typedData.types, typedData.message ); ``` ```typescript // viem const signature = await client.signTypedData({ domain: typedData.domain, types: typedData.types, primaryType: typedData.primaryType, message: typedData.message, }); ``` ## Approval Transaction If `create_tx` returns an `approveTx`, send it first: ```typescript // ethers v6 const approveResponse = await wallet.sendTransaction({ to: approveTx.to, data: approveTx.data, value: "0", }); await approveResponse.wait(1); // must confirm before bridge tx ``` ## Common Errors | Error | Fix | |-------|-----| | `INSUFFICIENT_FUNDS` | Fund wallet with native token for gas | | `NONCE_EXPIRED` | Pending tx — wait or use `wallet.getNonce("pending")` | | `CALL_EXCEPTION` | Tx will revert — check approval, balance, and params | --- ## Source: skills/swap/SKILL.md --- name: debridge-swap description: > Execute token swaps, bridges, and cross-chain transfers via deBridge DLN. Use this skill whenever the user wants to move, send, swap, exchange, trade, convert, or bridge tokens — whether on the same chain or across different chains (EVM-to-EVM, EVM-to-Solana, any L2-to-L2). This skill handles the full lifecycle: token lookup, quoting, amount conversion, balance checks, transaction signing, execution, and order tracking. IMPORTANT: Trigger this skill even for casual or indirect requests about moving tokens between wallets or chains. Common patterns include: "swap X for Y", "bridge tokens from A to B", "move my USDC to Base", "send ETH to Solana", "trade BNB for USDT on BSC", "how much to bridge from Polygon to Optimism", "convert DAI to USDC on Arbitrum", "exchange my tokens", "transfer to a cheaper L2", "what's the rate for swapping", "get me a quote", and any mention of moving crypto between chains or swapping one token for another. Also triggers for order monitoring: "my order is stuck", "check DLN order status", "track my bridge transaction", "order stuck on Created". If the user mentions specific token names (USDC, ETH, USDT, DAI, SOL, BNB, MATIC, AVAX) alongside any intent to move, send, swap, or trade them — use this skill. license: MIT metadata: author: deBridge version: "0.2.0" --- # Token Swap & Bridge PREREQUISITE: Read ../common/SKILL.md for environment detection, auth, and chain configuration. ## Quick Reference | Want to... | Go to | |-------------------------------|--------------------------------------------| | Look up chain IDs / tokens | ../common/chain-config.md | | Run preflight checks | [preflight.md](preflight.md) | | Sign and send transaction | ../signing/SKILL.md | | Track cross-chain order | [monitoring.md](monitoring.md) | | SDK workflow (coming soon) | Not yet available — use MCP | ## MCP Availability Check Before starting, verify MCP is connected: 1. Call `mcp__debridge__get_supported_chains` (no parameters). 2. If it returns chain data → MCP is ready. Continue below. 3. If tool not found → MCP not connected. Set up the connection: - **Streamable HTTP (preferred):** `claude mcp add --transport http debridge https://agents.debridge.com/mcp` - **Stdio proxy (fallback):** `claude mcp add debridge npx -- -y @debridge-finance/debridge-mcp@latest` Both require restarting the session. For full setup details: read ACCESS_SETUP in ../common/SKILL.md or ../common/mcp-setup.md. ## Routing Decision Determine whether this is a same-chain or cross-chain operation: - **Source and destination on the same chain** → same-chain swap. Go to [Same-Chain Swap](#same-chain-swap). - **Source and destination on different chains** → cross-chain swap/bridge. Go to [Cross-Chain Swap](#cross-chain-swap). --- ## Same-Chain Swap ### Step 1: Resolve Tokens Look up token addresses and decimals on the swap chain. ``` Call mcp__debridge__search_tokens: - query: "USDC" (NOT "search" — the parameter is "query") - chainId: "42161" (string, NOT number) ``` Repeat for the output token. Record `address` and `decimals`. ### Step 2: Build Swap Transaction ``` Call mcp__debridge__transaction_same_chain_swap: - chainId: "42161" (string, chain deBridge ID) - tokenIn: "0xaf88...e5831" (input token address) - tokenInAmount: "1000000000" (amount in raw units — see Amount Conversion) - tokenOut: "0x0000...0000" (output token address) - tokenOutRecipient: "0xYourAddress" (recipient address on the same chain) ``` Optional parameters: - `slippage` — tolerance or `"auto"` (default: auto) - `tokenOutAmount` — expected output or `"auto"` - `senderAddress` — transaction submitter address - `affiliateFeePercent` / `affiliateFeeRecipient` — affiliate fees **All parameters are strings.** Do NOT pass numbers for chain IDs. #### Response Format The response includes: - `tx` — the transaction object to sign and send (format depends on chain, see below) - `tokenIn` / `tokenOut` — token metadata with `amount`, `minAmount`, `approximateUsdValue` - `slippage` / `recommendedSlippage` — applied and recommended slippage (bps) - `estimatedTransactionFee` — gas estimate with `total` (in raw native units) and `approximateUsdValue` - `comparedAggregators` — price comparison with other DEX aggregators - `costsDetails` — detailed fee breakdown **EVM chains** — `tx` contains `{to, data, value}`: ```json { "tx": { "to": "0x663D...c251", "data": "0x258c...", "value": "0" }, "tokenOut": { "amount": "10027065", "minAmount": "10019037", ... } } ``` **Solana** (chain ID `7565164`) — `tx` contains `{data}` only (hex-encoded serialized transaction): ```json { "tx": { "data": "0x01000000..." }, "tokenOut": { "amount": "87206972", "minAmount": "86927910", ... } } ``` Solana transactions are fully serialized — pass `tx.data` to the Solana signing pipeline (see ../signing/ows-signing.md for OWS Solana flow). ### Step 3: Preflight Checks Read [preflight.md](preflight.md) before proceeding. Checks: balance, allowance (for ERC-20 input on EVM), and gas budget. ### Step 4: Sign and Send Read ../signing/SKILL.md — it detects the available signer and routes to the correct signing method. 1. If ERC-20 input on EVM and allowance insufficient → sign and send approval tx first. Wait for 1 confirmation. 2. Sign and send the swap tx. Same-chain swaps settle in a single transaction. No monitoring step needed — the tx receipt confirms completion. --- ## Cross-Chain Swap Cross-chain swaps (also called bridges or cross-chain transfers) move tokens between different blockchains. ### Non-EVM Destinations **Solana** (deBridge chain ID `7565164`): - Recipient addresses are base58 (e.g., `Gh9ZwEm...`), not hex — validate format before calling `create_tx`. - Native token (SOL) address: `11111111111111111111111111111111` (32 ones). - Token amounts still use raw units but SOL has 9 decimals, not 18. **Tron** (deBridge chain ID `100000026`): - Recipient addresses are base58check (e.g., `T9yD14N...`), starting with `T` — not the same encoding as Solana. - Native token (TRX) has 6 decimals. For both: the source side (EVM) follows the normal EVM flow — approval if needed on the source chain, then sign and send. The `approveTx` from `create_tx` is always a source-chain operation. ### Step 1: Resolve Tokens Look up token addresses and decimals on source and destination chains. ``` Call mcp__debridge__search_tokens: - query: "USDC" (NOT "search" — the parameter is "query") - chainId: "1" (string, NOT number) ``` Repeat for destination chain. Record `address` and `decimals` from the response. For native tokens (ETH, BNB, etc.), use the zero address from ../common/chain-config.md. For Solana native token (SOL), use `11111111111111111111111111111111`. ### Step 2: Build Transaction ``` Call mcp__debridge__create_tx: - srcChainId: "1" (string, source chain deBridge ID) - srcChainTokenIn: "0xA0b8...eB48" (source token address) - srcChainTokenInAmount: "100000000" (amount in raw units — see Amount Conversion) - dstChainId: "42161" (string, destination chain deBridge ID) - dstChainTokenOut: "0xaf88...e5831" (destination token address) - dstChainTokenOutRecipient: "0xRecipient..." (recipient on destination chain) - srcChainOrderAuthorityAddress: "0xSender..." (REQUIRED — sender's address on source chain) - dstChainOrderAuthorityAddress: "0xRecipient..." (REQUIRED — recipient's address on destination chain) ``` **All parameters are strings.** Do NOT pass numbers for chain IDs. Optional parameters: - `dstChainTokenOutAmount` — expected output amount or `"auto"` for best quote (default: auto) - `prependOperatingExpenses` — set `true` to add estimated operating expenses to the input amount - `affiliateFeePercent` / `affiliateFeeRecipient` — affiliate fees The response from `create_tx` includes: - `tx` — the main transaction object (`to`, `data`, `value`, `chainId`) - `approveTx` — token approval transaction (if ERC-20 allowance is insufficient) - `orderId` — the DLN order ID for tracking - Estimated output amount and fees ### Step 3: Preflight Checks Read [preflight.md](preflight.md) before proceeding. Preflight checks: - Source token balance - Token allowance (for ERC-20) - Native token balance for gas - Slippage tolerance ### Step 4: Sign and Send Read ../signing/SKILL.md — it detects the available signer and routes to the correct signing method. Execution order: 1. If `approveTx` is present → sign and send approval first. Wait for 1 confirmation. 2. Sign and send the main `tx`. Record the transaction hash. ### Step 5: Monitor Read [monitoring.md](monitoring.md) to track the DLN order from creation to fulfillment on the destination chain. --- ## Amount Conversion All amounts must be in raw units (smallest indivisible unit) as strings. ``` raw_units = human_amount × 10^decimals ``` Example: 100 USDC (6 decimals) → `"100000000"` See ../common/chain-config.md for decimals and conversion table. ### Bundled Scripts The `../common/scripts/` directory has TypeScript helpers that handle amount conversion, balance checks, allowances, and approvals. All scripts auto-discover RPC endpoints from Chainlist and read token decimals on-chain. | Script | Purpose | Example | |--------|---------|---------| | `convert-amount.ts` | Convert human ↔ raw units | `npx tsx ../common/scripts/convert-amount.ts 100 0xA0b8...eB48 1` | | `balance.ts` | Query native or ERC-20 balance | `npx tsx ../common/scripts/balance.ts 0xAddr 42161 --token 0xToken` | | `allowance.ts` | Check ERC-20 allowance | `npx tsx ../common/scripts/allowance.ts 0xToken 0xOwner 0xSpender 1 --check 100` | | `approve.ts` | Send ERC-20 approval tx | `npx tsx ../common/scripts/approve.ts 0xToken 0xSpender 1 --amount 1000` | | `rpc.ts` | Discover RPC from Chainlist | `npx tsx ../common/scripts/rpc.ts 42161 --json` | All scripts support `--json` for machine-readable output and `--rpc ` to override RPC discovery. ## Common Errors | Error | Cause | Fix | |------------------------------|------------------------------------|----------------------------------------------| | No route found | Token pair not supported on chains | Check `get_supported_chains` and `search_tokens` | | Insufficient allowance | Preflight should catch this | Send approval tx first, then retry | | Slippage exceeded | Price moved during execution | Re-call `create_tx` or `transaction_same_chain_swap` for fresh quote | | Amount too small | Below minimum amount | Increase amount or check minimum | | Insufficient liquidity | Pool too small for amount | Reduce amount or try a different pair | | Destination chain unsupported| Wrong chain ID format | Use deBridge chain IDs from ../common/chain-config.md | --- ## Source: skills/swap/monitoring.md --- title: Order Monitoring and Fulfillment Tracking impact: HIGH impactDescription: "Required for tracking cross-chain order status after execution" tags: monitoring, order-status, dln, fulfillment, polling --- # Order Monitoring After broadcasting a bridge transaction, track the DLN order until fulfillment on the destination chain. ## Get Order ID The order ID comes from the `create_tx` response (`orderId` field). Record it before signing. If the order ID is lost, it can be recovered from the transaction hash using the deBridge Explorer. ## Poll Order Status Query the DLN statistics API: ``` GET https://stats-api.dln.trade/api/Orders/{orderId} ``` ### Example ```bash curl -s "https://stats-api.dln.trade/api/Orders/$ORDER_ID" | jq '.status' ``` ```typescript const response = await fetch(`https://stats-api.dln.trade/api/Orders/${orderId}`); const order = await response.json(); console.log("Status:", order.status); ``` ## Status Values | Status | Meaning | Action | |-----------------|------------------------------------------------------|--------------------| | `None` | Order not yet indexed | Wait, poll again | | `Created` | Order submitted on source chain, awaiting fulfillment| Wait, poll again | | `Fulfilled` | Order filled on destination chain by a taker | Almost done | | `SentUnlock` | Unlock transaction sent on source chain | Almost done | | `ClaimedUnlock` | Fully completed — funds delivered, collateral unlocked | Done | | `Cancelled` | Order was cancelled | Check why | Normal flow: `Created` → `Fulfilled` → `SentUnlock` → `ClaimedUnlock` ## Polling Strategy - **First poll**: 10 seconds after broadcast (order needs to be indexed). - **Interval**: every 15–30 seconds. - **Timeout**: most orders fulfill within 1–5 minutes. Alert the user if still `Created` after 10 minutes. - **Terminal states**: `ClaimedUnlock` (success) or `Cancelled` (failure). ## deBridge Explorer For manual inspection, the order can be viewed at: ``` https://app.debridge.com/order?orderId={orderId} ``` Share this link with the user for visual tracking. ## Common Issues | Issue | Cause | Fix | |------------------------------|--------------------------------|--------------------------------------| | Order stuck on `Created` | No taker picked up the order | Wait — takers may need more time | | Order `Cancelled` | Expired or manually cancelled | Re-create the bridge with `create_tx`| | Order not found (404) | Not yet indexed | Wait 30 seconds and retry | ## Post-Delivery Verification After an order reaches `ClaimedUnlock`, verify the balance on the destination chain using: - ../analytics/onchain-explorer.md — verify the transaction and token balances on the destination chain via Blockscout --- ## Source: skills/swap/preflight.md --- title: Preflight Checks impact: HIGH impactDescription: "Mandatory validation before any bridge or swap execution" tags: preflight, balance, allowance, gas, slippage, validation --- # Preflight Checks Run all checks before signing any transaction. Stop if any check fails. ## 1. Source Token Balance Verify the wallet holds enough of the source token. ### ERC-20 Token ```bash # cast cast call "$TOKEN_ADDRESS" "balanceOf(address)" "$WALLET_ADDRESS" --rpc-url "$RPC_URL" ``` ```typescript // ethers v6 const balance = await tokenContract.balanceOf(walletAddress); // balance must be >= srcChainTokenInAmount (both in raw units) ``` If balance < required amount → **STOP**. Inform the user of the shortfall. ### Native Token (ETH, BNB, etc.) ```bash cast balance "$WALLET_ADDRESS" --rpc-url "$RPC_URL" ``` For native token bridges, the balance must cover both the bridge amount AND gas. ## 2. Token Allowance (ERC-20 only) Skip this check for native token transfers. Check if the deBridge contract is approved to spend the token: ```bash cast call "$TOKEN_ADDRESS" "allowance(address,address)" "$WALLET_ADDRESS" "$SPENDER_ADDRESS" --rpc-url "$RPC_URL" ``` The `$SPENDER_ADDRESS` is the `tx.to` field from the `create_tx` or `transaction_same_chain_swap` response. If allowance < required amount: - The response should include an `approveTx` object. - Send the approval transaction first (see ../signing/SKILL.md). - Wait for 1 confirmation before proceeding. ## 3. Gas Budget Verify the wallet has enough native token to pay for gas: ```bash cast balance "$WALLET_ADDRESS" --rpc-url "$RPC_URL" ``` Estimate gas cost: - Approval tx: ~50,000 gas - Bridge tx: ~200,000–500,000 gas (varies by route) - Total native needed: `(approval_gas + bridge_gas) × gas_price` If the bridge is for the native token, the balance must cover `bridge_amount + gas_cost`. If insufficient gas → **STOP**. User needs to fund the wallet with native token. ## 4. Slippage The `create_tx` call may accept slippage parameters. If the estimated output amount is significantly less than expected: - Re-call `create_tx` to get a fresh quote (prices change). - If slippage is too high, inform the user and ask whether to proceed. - For automated agents, a default slippage tolerance of 1% (100 bps) is reasonable. Increase for volatile tokens or illiquid pairs. ## Summary | Check | Fails when | Action | |-------------|------------------------------------|---------------------------------| | Balance | Token balance < bridge amount | Stop, inform user | | Allowance | Allowance < bridge amount | Send approval tx, wait, retry | | Gas | Native balance < estimated gas | Stop, user must fund wallet | | Slippage | Output significantly below expect | Re-quote or increase tolerance | All checks pass → proceed to ../signing/SKILL.md. ## Bundled Scripts The `../common/scripts/` directory has TypeScript helpers that automate these checks. All scripts auto-discover RPC endpoints from Chainlist. | Script | Preflight use | Example | |--------|--------------|---------| | `balance.ts` | Check token or native balance | `npx tsx ../common/scripts/balance.ts 0xAddr 42161 --token 0xUSDC` | | `allowance.ts` | Check ERC-20 allowance | `npx tsx ../common/scripts/allowance.ts 0xUSDC 0xOwner 0xSpender 42161 --check 1000000000` | | `approve.ts` | Send approval tx | `npx tsx ../common/scripts/approve.ts 0xUSDC 0xSpender 42161 --amount 1000000000` | --- ## Source: skills/wallets/SKILL.md --- name: debridge-wallets description: > Set up a wallet for deBridge transactions. Use when the user has no signer available, needs to create a new wallet, or wants to configure wallet access for an AI agent. Covers OWS local self-custody wallets (recommended — multi-chain, encrypted keys, CLI/JS), generating a raw private key, creating a Foundry keystore, installing a browser wallet (MetaMask), and setting up Privy embedded wallets for zero-UI autonomous agent trading. Use this skill when: the user says "I don't have a wallet", "how do I set up a wallet", "create a new wallet", "generate an address", "I need a wallet for bridging", "set up OWS", "OWS wallet", "set up Privy", "embedded wallet for my agent", "keystore setup", or when WALLET_DISCOVERY detected no signer. Also relevant for "conversational trading setup" and "autonomous agent wallet". license: MIT metadata: author: deBridge version: "0.1.0" --- # Wallet Setup PREREQUISITE: Read ../common/SKILL.md for environment detection, auth, and chain configuration. Use this skill when WALLET_DISCOVERY detected **Signer = none**. Choose the method that matches your environment. ## Quick Reference | Environment | Recommended method | Go to | |-------------------|--------------------------|----------------------------------------------| | CLI / Agent | **OWS** (recommended) | Option 1 below | | CLI + Node.js | Raw private key + env var| Option 2 below | | CLI + Foundry | Foundry keystore | Option 3 below | | Browser | Install MetaMask | Option 4 below | | Agent (zero-UI) | Privy embedded wallet | Option 5 / [privy-embedded.md](privy-embedded.md) | **Why OWS first?** It supports all deBridge chains (EVM, Solana, Tron) from a single wallet, encrypts keys at rest with policy-gated signing, works across CLI/Node.js environments, and generates addresses for all chains in one step. More secure than raw private keys, simpler than Foundry for multi-chain use. After setup, re-run WALLET_DISCOVERY to confirm the signer is detected, then proceed to ../signing/SKILL.md. --- ## Option 1: OWS Wallet (Open Wallet Standard) — Recommended Local self-custody wallet — private keys encrypted at rest on the user's machine, decrypted only in-process during signing, then wiped from memory. Policy-gated access, multi-chain support (EVM, Solana, Tron, Bitcoin, Cosmos, TON, Sui, and more). ### Install Pick the method that matches your environment: | Environment | Command | What it installs | |-------------|---------|------------------| | Any (full suite) | `curl -fsSL https://docs.openwallet.sh/install.sh \| bash` | CLI + Node.js SDK | | Node.js only | `npm install @open-wallet-standard/core` | Node.js SDK (prebuilt binaries, no Rust needed) | | From source | `git clone https://github.com/open-wallet-standard/core.git && cd core/ows && cargo build --workspace --release` | Rust build | The full suite (`curl`) is recommended for agents — it gives you the CLI plus the Node.js SDK. ### Create Wallet ```bash ows wallet create ``` This generates keys for all supported chains in one step. Record the addresses from the output. ### Verify ```bash ows wallet list ``` ### Fund the Wallet Send tokens to the OWS wallet address on the source chain before bridging. ### Signing Proceed to ../signing/SKILL.md — the signing skill routes to [ows-signing.md](../signing/ows-signing.md) for OWS-specific signing flows (EVM direct, Solana pipeline, Tron). --- ## Option 2: Private Key via Environment Variable Fastest path if you only need a single EVM chain. Generates a random private key and stores it in the shell environment. Less secure than OWS — the key is stored in plaintext. ### Generate with Node.js ```bash node -e "const w = require('ethers').Wallet.createRandom(); console.log('Address:', w.address); console.log('Private key:', w.privateKey)" ``` If ethers is not installed: ```bash npx -y ethers node -e "const w = require('ethers').Wallet.createRandom(); console.log('Address:', w.address); console.log('Private key:', w.privateKey)" ``` ### Generate with OpenSSL ```bash openssl rand -hex 32 ``` This outputs a raw 32-byte hex string. Prefix with `0x` for use as a private key. ### Store in Environment Add to shell profile (`~/.bashrc`, `~/.zshrc`, or `.env`): ```bash export PRIVATE_KEY="0x" ``` Then reload: `source ~/.bashrc` ⚠️ CAUTION: Never commit private keys to git. Add `.env` to `.gitignore`. ### Derive Address ```bash # ethers node -e "const w = new (require('ethers').Wallet)('$PRIVATE_KEY'); console.log(w.address)" # cast cast wallet address --private-key "$PRIVATE_KEY" ``` ### Fund the Wallet The new wallet has zero balance. Send native tokens (ETH, etc.) to the derived address before bridging. Use a faucet for testnet work. --- ## Option 3: Foundry Keystore More secure than a raw environment variable — the private key is encrypted at rest. EVM-only. ### Prerequisites ```bash which cast || (curl -L https://foundry.paradigm.xyz | bash && foundryup) ``` ### Create Keystore ```bash cast wallet new ~/.foundry/keystores/debridge ``` This generates a new key pair and encrypts it with a password. Record the address from the output. ### Or Import Existing Key ```bash cast wallet import debridge --interactive ``` Enter the private key and a password when prompted. ### Use in Commands ```bash cast send "$TO" "$DATA" --account debridge --rpc-url "$RPC_URL" ``` Cast will prompt for the keystore password. ### Fund the Wallet Send native tokens to the keystore address before bridging. --- ## Option 4: Browser Wallet (MetaMask) For browser-based environments. ### Install 1. Go to [metamask.io/download](https://metamask.io/download). 2. Install the browser extension. 3. Create a new wallet or import an existing one. 4. Record the wallet address. ### Connect to deBridge Chains MetaMask ships with Ethereum mainnet. Add other chains: 1. Open MetaMask → Settings → Networks → Add Network. 2. Use [chainlist.org](https://chainlist.org) to auto-add chains by name. 3. Or add manually using chain IDs from ../common/chain-config.md. ### Fund the Wallet Send native tokens to the MetaMask address on the source chain before bridging. --- ## Option 5: Privy Embedded Wallet Server-side wallets managed by Privy infrastructure (keys secured in TEEs). The agent signs and broadcasts transactions via Privy MCP — no browser, no wallet popup, no local keys. Best for autonomous agent workflows that need delegated custody. Read [privy-embedded.md](privy-embedded.md) for full setup. Quick summary: 1. Create a Privy account at [dashboard.privy.io](https://dashboard.privy.io) and get App ID + App Secret. 2. Install Privy MCP server and add it alongside deBridge MCP. 3. Create wallets via Privy MCP (`create_wallet` for EVM and/or Solana). 4. Fund the wallet on the source chain. 5. The agent passes `create_tx` output directly to Privy's `eth_sendTransaction` — no format conversion needed. --- ## After Setup For Option 1 (OWS): 1. Verify OWS CLI is available (`ows wallet list`). 2. Proceed to ../signing/SKILL.md — it routes to the OWS signing reference. 3. Then to ../swap/SKILL.md for the operation. For Options 2–4: 1. Re-run WALLET_DISCOVERY to verify the signer is detected. 2. Proceed to ../signing/SKILL.md for transaction signing. 3. Then to ../swap/SKILL.md for the operation. For Option 5 (Privy): 1. Verify both deBridge and Privy MCPs are connected. 2. The agent uses deBridge MCP for routing and Privy MCP for signing — no separate signing step needed. 3. Proceed directly to ../swap/SKILL.md. ## References - [privy-embedded.md](privy-embedded.md) — Full Privy embedded wallet setup and integration --- ## Source: skills/wallets/ows-signing.md --- title: deBridge Signing with OWS (Open Wallet Standard) impact: HIGH impactDescription: "Local self-custody signing for deBridge transactions via OWS CLI" tags: ows, signing, self-custody, local-key, evm, solana, tron, deBridge --- # deBridge Signing with OWS Local self-custody signing for deBridge transactions using OWS wallets. Keys stay encrypted on the user's machine and are decrypted only in-process during signing — never exposed. OWS supports several chain families including | Chain family | OWS signing | deBridge support | Notes | |--------------|-------------|------------------|-------| | EVM | `ows sign tx` / `ows sign message` | All EVM chains (Ethereum, Arbitrum, Base, Polygon, etc.) | Standard EVM tx signing works directly | | Solana | `ows sign message --encoding hex` | Solana (chainId `7565164`) | Requires manual flow — see below | | Tron | `ows sign tx` / `ows sign message` | Tron (chainId `100000026`) | base58check addresses, 6-decimal TRX | ## Solana Manual Sign + Broadcast The rest of this document covers the Solana-specific workaround. For EVM and Tron, `ows sign tx` works directly with the hex transaction data returned by `mcp__debridge__create_tx`. The agent gets a quote from deBridge MCP, then signs locally and broadcasts via a single script — required because the OWS CLI lacks Solana-aware transaction handling. ``` User prompt → deBridge MCP (quote + tx data) → Script (blockhash → sign → broadcast) → On-chain ``` Works for Solana-to-EVM bridges, Solana-to-Solana swaps routed cross-chain, and any deBridge order with Solana as the source. ## Prerequisites - Node.js 18+ (preferred) or Python 3 with `base58` (`pip3 install base58`) - deBridge MCP configured (see ../common/mcp-setup.md) - OWS wallet with a funded Solana wallet (bridge amount + ~0.024 SOL for rent/fees) - Solana RPC endpoint — set `SOLANA_RPC_URL` env var or use the default public RPC (see ../common/rpc-discovery.md) ## Why a Manual Flow? The OWS CLI does not have a dedicated `signAndSend` subcommand for Solana (`signAndSend` is an optional feature in the OWS spec and is not exposed as a CLI command). Additionally, `ows sign tx` signs whatever bytes you pass — it does not extract the Solana message portion automatically. For Solana V0 versioned transactions, the signature must cover only the message bytes (offset 65+), not the full serialized transaction including signature placeholders. The solution: use `ows sign message --encoding hex` on the message bytes only (offset 65+), then broadcast the assembled transaction as base64 yourself. All steps must run in a single script because blockhashes expire in ~60–90 seconds. ## Step 1: Get a deBridge Quote Call `mcp__debridge__create_tx` with Solana as the source chain (chainId `7565164`). The response `tx.data` is a hex-encoded Solana V0 versioned transaction with a placeholder blockhash (all zeros). ## Step 2: Sign and Broadcast ⚠️ CAUTION: This executes a real transaction. Run everything in one script. The flow: 1. Fetch a fresh blockhash from Solana RPC 2. Insert the blockhash into the transaction (before signing — the signature covers the blockhash) 3. Sign the message bytes (offset 65+) with OWS 4. Insert the signature at bytes 1–64 5. Broadcast the full transaction as base64 ### Option A: Node.js (preferred) Zero external dependencies — uses only Node.js built-ins (`Buffer`, `fetch`, `child_process`) plus an inline base58 decoder. ```js const { execSync } = require('child_process'); // -- CONFIG: set these from deBridge response -- const txHex = ''; import { Connection } from '@solana/web3.js'; import bs58 from 'bs58'; const wallet = 'agent-treasury'; // OWS wallet name const rpcUrl = process.env.SOLANA_RPC_URL || 'https://api.mainnet-beta.solana.com'; const connection = new Connection(rpcUrl, 'confirmed'); const tx = Buffer.from(txHex, 'hex'); // Parse V0 transaction: // Byte 0: 01 (1 sig), Bytes 1-64: sig placeholder, Byte 65: 0x80 (V0), // Bytes 66-68: header, Byte 69: num_account_keys const numKeys = tx[69]; const bhOffset = 70 + numKeys * 32; // Step 1: Fresh blockhash const { blockhash } = await connection.getLatestBlockhash('confirmed'); // Step 2: Insert blockhash BEFORE signing const bhBytes = bs58.decode(blockhash); Buffer.from(bhBytes).copy(tx, bhOffset); // Step 3: Sign message bytes (offset 65+) with OWS const messageHex = tx.subarray(65).toString('hex'); const sigJson = execSync( `ows sign message --chain solana --wallet ${wallet} --encoding hex --message ${messageHex} --json`, { encoding: 'utf-8' } ); const { signature } = JSON.parse(sigJson); // Step 4: Insert signature at bytes 1-64 Buffer.from(signature, 'hex').copy(tx, 1); // Step 5: Broadcast const txSignature = await connection.sendRawTransaction(tx, { skipPreflight: false, preflightCommitment: 'confirmed', }); console.log('Transaction sent:', txSignature); ``` Run with: `node --experimental-vm-modules` or wrap in an async IIFE. ### Option B: Python (fallback) Requires `pip3 install base58`. ```python import base58, base64, json, os, subprocess, urllib.request tx_hex = "" wallet = "agent-treasury" rpc_url = os.environ.get("SOLANA_RPC_URL", "https://api.mainnet-beta.solana.com") tx = bytearray(bytes.fromhex(tx_hex)) num_keys = tx[69] bh_offset = 70 + num_keys * 32 # Fresh blockhash req = urllib.request.Request(rpc_url, data=json.dumps({"jsonrpc":"2.0","id":1,"method":"getLatestBlockhash", "params":[{"commitment":"confirmed"}]}).encode(), headers={"Content-Type":"application/json"}) bh_b58 = json.loads(urllib.request.urlopen(req).read())["result"]["value"]["blockhash"] tx[bh_offset:bh_offset+32] = base58.b58decode(bh_b58) # Sign message (offset 65+) sig = json.loads(subprocess.run( ["ows","sign","message","--chain","solana","--wallet",wallet, "--encoding","hex","--message",tx[65:].hex(),"--json"], capture_output=True, text=True).stdout)["signature"] tx[1:65] = bytes.fromhex(sig) # Broadcast as base64 resp = urllib.request.urlopen(urllib.request.Request(rpc_url, data=json.dumps({"jsonrpc":"2.0","id":1,"method":"sendTransaction", "params":[base64.b64encode(bytes(tx)).decode(), {"encoding":"base64","skipPreflight":False,"preflightCommitment":"confirmed"}]}).encode(), headers={"Content-Type":"application/json"})) print(json.loads(resp.read())) ``` ## Example Prompts Cross-chain from Solana: - "Bridge 10 USDC from Solana to Arbitrum" - "Swap 2 SOL from Solana to ETH on Ethereum" Quote only: - "Get a deBridge quote for 100 USDC from Solana to Base, don't execute yet" ## Security Notes - OWS wallet keys are encrypted locally and decrypted only in-process during signing — never exposed in script output. - Use `confirmed` commitment (not `finalized`) for the freshest blockhash. - For testing, use small amounts to minimize risk from blockhash expiry or failed broadcasts. - deBridge MCP is read-only by itself — it generates tx data but cannot sign or broadcast. - Account for ~0.024 SOL in rent/fees on top of the bridge amount when funding the wallet. ## Troubleshooting | Issue | Fix | |-------|-----| | No `ows sign send-tx` for Solana | `signAndSend` is optional in the OWS spec and not available as a CLI command. Use the manual sign + broadcast script above | | `ows sign tx` produces invalid signature | Signs the exact bytes you pass without extracting Solana message portion. Use `ows sign message --encoding hex` on offset 65+ only | | Blockhash expired | All steps must run in one script. Blockhashes last ~60–90s. Re-run the full script | | Transaction simulation failed | Check wallet has enough SOL for rent/fees (~0.024 SOL) on top of the bridge amount | | Signature verification failed | Ensure blockhash is inserted BEFORE signing — the signature covers the blockhash | --- ## Source: skills/wallets/privy-embedded.md --- title: Privy Embedded Wallet Setup impact: HIGH impactDescription: "Server-side wallet for zero-UI agent trading via Privy MCP" tags: privy, embedded-wallet, mcp, tee, signing, agent-trading --- # Privy Embedded Wallet Server-side wallets managed by Privy (keys secured in TEEs). The agent routes trades via deBridge MCP and signs/broadcasts via Privy MCP — no browser, no dApp, no wallet popup. ``` User prompt → deBridge MCP (route + tx data) → Privy MCP (sign + broadcast) → On-chain ``` Works for cross-chain bridges, same-chain swaps, and cross-chain swap combos. ## Prerequisites - Node.js 18+ - deBridge MCP configured (see ../common/mcp-setup.md) ## Step 1: Create Privy Account This is the only step that requires a browser. 1. Open [dashboard.privy.io](https://dashboard.privy.io) and sign up. 2. Click "Create new app" (e.g., "deBridge Agent"). 3. Navigate to **Settings → Basics → API Keys**. 4. Copy two values: - **App ID** — public, safe to expose. - **App Secret** — private. Copy immediately — Privy does not store it. If lost, regenerate. ⚠️ CAUTION: Never commit App Secret to git or include in skill content. ## Step 2: Install Privy MCP ### From source (current) ```bash git clone https://github.com/privy-io/privy-mcp-server.git cd privy-mcp-server npm install && npm run build ``` Add to Claude Code from inside the cloned directory: ```bash claude mcp add privy node -- dist/index.js \ --env PRIVY_APP_ID= \ --env PRIVY_APP_SECRET= ``` ### From npm (when available) ```bash claude mcp add privy npx -- @privy-io/mcp-server \ --env PRIVY_APP_ID= \ --env PRIVY_APP_SECRET= ``` ### For Claude Desktop Add to Claude Desktop config (see ../common/mcp-setup.md for config file location): ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" }, "privy": { "command": "node", "args": ["/dist/index.js"], "env": { "PRIVY_APP_ID": "", "PRIVY_APP_SECRET": "" } } } } ``` ### Verify ```bash claude mcp list ``` Both `debridge` and `privy` should show connected status. ## Step 3: Create Wallets Ask the agent to create wallets via Privy MCP: ``` Using the Privy MCP, create wallets for me on Ethereum and Solana. Show me the addresses. ``` Privy creates embedded server-side wallets (keys managed in TEEs, never exposed). Record the wallet addresses. ## Step 4: Fund the Wallet Send tokens to the Privy wallet address on the source chain: - The swap/bridge amount in the source token (e.g., USDC) - Native token for gas (e.g., ETH on Arbitrum) Use an L2 chain (Arbitrum, Base, BSC) to minimize gas costs for testing. ## How the Handoff Works deBridge MCP's `create_tx` returns standard EVM transaction data: ```json { "to": "0xeF4fB24aD0916217251F553c0596F8Edc630EB66", "value": "1000000000000000", "data": "0xb9303701..." } ``` Privy MCP's `eth_sendTransaction` accepts the same format: ```json { "to": "0xeF4fB24aD0916217251F553c0596F8Edc630EB66", "value": "1000000000000000", "data": "0xb9303701...", "chain_id": 42161 } ``` The agent passes `create_tx` output directly to Privy's `eth_sendTransaction`. No format conversion needed. The full flow: 1. `mcp__debridge__create_tx` → returns tx data + order ID 2. If approval needed → `mcp__privy__eth_sendTransaction` with approval tx, wait for confirmation 3. `mcp__privy__eth_sendTransaction` with bridge/swap tx 4. Track order via monitoring (see ../swap/monitoring.md) ## Example Prompts Cross-chain: - "Swap 50 USDC from Base to Solana" - "Bridge 0.1 ETH from Ethereum to Arbitrum" Same-chain: - "Swap 0.05 ETH to USDC on Arbitrum" - "Trade 100 USDC for USDT on Base" Cross-chain + swap combo: - "Swap my ETH on Ethereum into USDC on Solana" Utility: - "Check my Privy wallet balances across all chains" - "Get a deBridge quote for 500 USDC from Polygon to Solana, don't execute yet" ## Security Notes - Privy wallet keys are managed in TEEs (Trusted Execution Environments) and never exposed. - App Secret must not be committed to version control. - For testing, use small amounts on L2 chains. - Privy supports wallet policies and transaction limits for production use. - deBridge MCP is read-only by itself — it generates tx data but cannot sign or broadcast. ## Troubleshooting | Issue | Fix | |-------|-----| | Privy MCP disconnected | Verify App ID and App Secret. Remove and re-add: `claude mcp remove privy` then re-add | | Insufficient funds | Wallet needs both swap token AND native gas token on source chain | | Transaction not confirmed | Cross-chain orders settle in seconds. Check status via deBridge MCP or ../swap/monitoring.md | | High price impact | Use L2 chains (Arbitrum, Base) instead of Ethereum mainnet for small amounts | --- ## Source: setup/agents/aider.md # Aider Aider supports custom instructions via conventions files. For full MCP and skills support, use AiderDesk (https://github.com/hotovo/aider-desk). AiderDesk: 1. Open AiderDesk and go to Settings, MCP Servers. Add server with name `debridge` and URL `https://agents.debridge.com/mcp`. 2. Load deBridge skills: ```shell npx skill debridge-finance/debridge-skills ``` 3. Restart AiderDesk. The deBridge tools will be available in the session. Aider CLI (without AiderDesk): 1. Add deBridge context to your project's CONVENTIONS.md by referencing `https://agents.debridge.com/SKILL.md`. 2. Start Aider with the conventions file: ```shell aider --read CONVENTIONS.md ``` --- ## Source: setup/agents/amazon-q.md # Amazon Q Developer Works in VS Code, JetBrains IDEs, and the Q Developer CLI. IDE: 1. Open your IDE with the Amazon Q extension. Go to Amazon Q Settings, MCP Servers. Add: ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 2. Load deBridge skills from the terminal: ```shell npx skill debridge-finance/debridge-skills ``` 3. Reload the IDE. The deBridge tools will be available in Amazon Q chat. CLI: 1. Edit `~/.aws/amazonq/mcp.json`: ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 2. Load deBridge skills: ```shell npx skill debridge-finance/debridge-skills ``` 3. Start a new Q Developer CLI session to verify. --- ## Source: setup/agents/amp.md # Amp by Sourcegraph 1. Open Amp and navigate to the MCP settings panel. Add a new server with name `debridge` and URL `https://agents.debridge.com/mcp`. 2. Load deBridge skills from the terminal: ```shell npx skill debridge-finance/debridge-skills ``` 3. Save and restart the session. --- ## Source: setup/agents/antigravity.md # Antigravity 1. Open Antigravity and go to the MCP settings panel. Add a new MCP server: ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 2. Load deBridge skills from the terminal: ```shell npx skill debridge-finance/debridge-skills ``` 3. Save the configuration and reload. --- ## Source: setup/agents/chatgpt.md # ChatGPT Desktop Requires ChatGPT Plus or Pro subscription with Developer Mode enabled. 1. Open ChatGPT Desktop and enable Developer Mode in Settings. 2. Go to Settings, Apps (or MCP Connectors). Click Add and enter name `debridge` with URL `https://agents.debridge.com/mcp`. 3. The deBridge tools and skills are loaded automatically via the MCP server. Start a new conversation to begin. --- ## Source: setup/agents/claude-code.md # Anthropic Claude Code CLI 1. Add the deBridge MCP server: ```shell claude mcp add --transport http debridge https://agents.debridge.com/mcp ``` 2. Load deBridge skills: ```shell npx skill debridge-finance/debridge-skills ``` 3. Restart the Claude Code session. Type `/mcp` to confirm the deBridge server is connected. --- ## Source: setup/agents/claude-web.md # Claude Web & Desktop by Anthropic Claude.ai (Web): 1. Go to claude.ai and create a new Project. 2. Under project knowledge, add the deBridge skills URL: `https://agents.debridge.com/SKILL.md` 3. Start a conversation in the project. Claude will use the deBridge skills as context. Claude Desktop: 1. Open Settings, Developer, Edit Config. This opens `claude_desktop_config.json` located at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows. 2. Add the deBridge MCP server: ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 3. Save and restart Claude Desktop completely (quit and reopen). --- ## Source: setup/agents/cline.md # Cline VS Code Extension 1. Open VS Code, click the Cline icon in the sidebar, then click the MCP Servers button (server icon). 2. Click Add MCP Server, select Streamable HTTP. Enter the name `debridge` and the URL: ``` https://agents.debridge.com/mcp ``` 3. Load deBridge skills from the terminal: ```shell npx skill debridge-finance/debridge-skills ``` 4. Click Save. The deBridge tools will appear in the MCP Servers panel. --- ## Source: setup/agents/codex.md # OpenAI Codex CLI 1. Add the deBridge MCP server to your Codex configuration: ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 2. Load deBridge skills: ```shell npx skill debridge-finance/debridge-skills ``` 3. Start a new Codex session. The deBridge tools will be available automatically. --- ## Source: setup/agents/continue.md # Continue.dev 1. Open `~/.continue/config.yaml` (or create it). Add the deBridge MCP server: ```yaml mcpServers: - name: debridge type: streamable-http url: https://agents.debridge.com/mcp ``` Or use `~/.continue/config.json`: ```json { "mcpServers": [ { "name": "debridge", "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } ] } ``` 2. Load deBridge skills from the terminal: ```shell npx skill debridge-finance/debridge-skills ``` 3. Save and reload your editor. --- ## Source: setup/agents/copilot.md # GitHub Copilot in VS Code 1. Open Settings (`Ctrl+,`), search for `chat.mcp.enabled`, and make sure it is checked. 2. Create `.vscode/mcp.json` in your project root: ```json { "servers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 3. Load deBridge skills from the terminal: ```shell npx skill debridge-finance/debridge-skills ``` 4. Reload the VS Code window. A Start button will appear above the server entry — click it, or Copilot will start it automatically. --- ## Source: setup/agents/cursor.md # Cursor by Anysphere 1. Create or edit `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` for global): ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 2. Load deBridge skills from the terminal: ```shell npx skill debridge-finance/debridge-skills ``` 3. Restart Cursor. The deBridge server should show a green status indicator in Settings, MCP. --- ## Source: setup/agents/databricks.md # Databricks (Genie Code) 1. Add the deBridge MCP server to your Databricks agent configuration: ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 2. Load deBridge skills from the terminal: ```shell npx skill debridge-finance/debridge-skills ``` 3. The deBridge tools will be available in your Databricks agent workflows. --- ## Source: setup/agents/devin.md # Devin by Cognition 1. Open the Devin dashboard. Go to Settings, MCP Servers and add server with name `debridge` and URL `https://agents.debridge.com/mcp`. 2. Add deBridge skills to your project's `AGENTS.md` or Devin knowledge by referencing: ``` https://agents.debridge.com/SKILL.md ``` 3. Start a new Devin session. The deBridge MCP tools will be available for autonomous workflows. --- ## Source: setup/agents/factory.md # Factory 1. Open your Factory workspace and navigate to MCP integration settings. Add the deBridge server: ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 2. Factory's Droids will detect the deBridge tools and can invoke them as part of autonomous workflows. --- ## Source: setup/agents/gemini-cli.md # Google Gemini CLI 1. Open or create `~/.gemini/settings.json`. Add the deBridge MCP server: ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 2. Load deBridge skills: ```shell npx skill debridge-finance/debridge-skills ``` 3. Start a new session and verify: ```shell gemini tools list ``` --- ## Source: setup/agents/goose.md # Goose by Block 1. Edit `~/.config/goose/config.yaml` and add the deBridge MCP server: ```yaml mcp_servers: debridge: type: streamable-http uri: https://agents.debridge.com/mcp ``` 2. Load deBridge skills: ```shell npx skill debridge-finance/debridge-skills ``` 3. Start a new Goose session. Type `/tools` to confirm the deBridge tools are listed. --- ## Source: setup/agents/jetbrains-ai.md # JetBrains AI Assistant Works in any JetBrains IDE (IntelliJ IDEA, PyCharm, WebStorm, etc.). 1. Open Settings, Tools, AI Assistant, MCP Servers. Click Add and select Streamable HTTP. Enter name `debridge` and URL `https://agents.debridge.com/mcp`. 2. Load deBridge skills from the terminal: ```shell npx skill debridge-finance/debridge-skills ``` 3. Restart the IDE. The deBridge tools will appear in the AI Assistant MCP panel. --- ## Source: setup/agents/junie.md # Junie by JetBrains Works in any JetBrains IDE (IntelliJ IDEA, PyCharm, WebStorm, etc.) and as a standalone CLI. IDE: 1. Open Settings, Tools, AI Assistant, MCP Servers. Click Add and select Streamable HTTP. Enter name `debridge` and URL `https://agents.debridge.com/mcp`. 2. Load deBridge skills from the terminal: ```shell npx skill debridge-finance/debridge-skills ``` 3. Restart the IDE. The deBridge tools will appear in the MCP Servers list. CLI: 1. Create or edit `~/.junie/config.json`: ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 2. Load deBridge skills: ```shell npx skill debridge-finance/debridge-skills ``` 3. Start a Junie session to verify. --- ## Source: setup/agents/kilo-code.md # Kilo Code 1. Open VS Code, click the Kilo Code icon in the sidebar, then open the MCP Servers panel. 2. Click Add MCP Server, select Streamable HTTP. Enter the name `debridge` and the URL: ``` https://agents.debridge.com/mcp ``` 3. Load deBridge skills from the terminal: ```shell npx skill debridge-finance/debridge-skills ``` 4. Click Save. The deBridge tools will appear in the MCP Servers panel. --- ## Source: setup/agents/kiro.md # Kiro by Amazon 1. Open Kiro and go to Settings, MCP Servers. Click Add and paste: ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 2. Load deBridge skills from the terminal: ```shell npx skill debridge-finance/debridge-skills ``` 3. Save and restart Kiro. The deBridge tools will appear in the tools panel. --- ## Source: setup/agents/letta.md # Letta (formerly MemGPT) 1. Add the deBridge MCP server to your Letta agent configuration: ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 2. Load deBridge skills: ```shell npx skill debridge-finance/debridge-skills ``` 3. Restart the Letta server. The deBridge tools will be available to all agents with MCP access. --- ## Source: setup/agents/lmstudio.md # LM Studio 1. Load a model that supports tool use (Llama 3.x 8B+, Mistral/Mixtral, or other function-calling capable models). 2. Go to Settings, MCP Servers and add: ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 3. Save and restart LM Studio. The deBridge tools will appear in the tools panel. --- ## Source: setup/agents/mistral-vibe.md # Mistral Vibe 1. Edit `~/.config/mistral-vibe/config.json` (or create it): ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 2. Load deBridge skills: ```shell npx skill debridge-finance/debridge-skills ``` 3. Start a new Vibe session. The deBridge tools will be available automatically. --- ## Source: setup/agents/mux.md # Mux by Coder 1. Add the deBridge MCP server to your Mux configuration: ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 2. Load deBridge skills: ```shell npx skill debridge-finance/debridge-skills ``` 3. Start a new Mux session. The deBridge tools will be available for parallel agentic workflows. --- ## Source: setup/agents/openclaw.md # OpenClaw 1. Open your OpenClaw project configuration file. Add the deBridge MCP server: ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 2. Load deBridge skills: ```shell npx skill debridge-finance/debridge-skills ``` 3. Start or restart the OpenClaw agent. It will connect to the deBridge server and register all available tools on startup. --- ## Source: setup/agents/opencode.md # opencode 1. Open `~/.opencode/config.json` (or project-level config). Add the deBridge MCP server: ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 2. Load deBridge skills: ```shell npx skill debridge-finance/debridge-skills ``` 3. Start a new opencode session and verify: ```shell opencode tools ``` --- ## Source: setup/agents/qodo.md # Qodo Gen 1. Open your editor (VS Code or JetBrains) with the Qodo Gen extension. Go to Qodo Gen settings, MCP server configuration. Add: ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 2. Load deBridge skills from the terminal: ```shell npx skill debridge-finance/debridge-skills ``` 3. Save and reload the editor. --- ## Source: setup/agents/replit.md # Replit Agent 1. Open your Repl and go to the Integrations pane (or Tools, MCP). 2. Click Add MCP Server and enter name `debridge` with URL `https://agents.debridge.com/mcp`. 3. The deBridge tools and skills are loaded automatically via the MCP server. Start a conversation with Replit Agent to begin. --- ## Source: setup/agents/roo-code.md # Roo Code 1. Open VS Code, click the Roo Code icon in the sidebar, then click the MCP Servers button. 2. Click Add MCP Server, select Streamable HTTP. Enter the name `debridge` and the URL: ``` https://agents.debridge.com/mcp ``` 3. Load deBridge skills from the terminal: ```shell npx skill debridge-finance/debridge-skills ``` 4. Click Save. The deBridge tools will appear in the MCP Servers panel. --- ## Source: setup/agents/tabnine.md # Tabnine 1. Open your IDE (VS Code or JetBrains) with the Tabnine extension. Go to Tabnine Settings, MCP. Add: ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 2. Load deBridge skills from the terminal: ```shell npx skill debridge-finance/debridge-skills ``` 3. Reload the editor. The deBridge tools will be available in Tabnine agent chat. --- ## Source: setup/agents/trae.md # Trae by ByteDance 1. Open Trae and go to Settings, MCP Servers. Click Add and enter name `debridge`, type Streamable HTTP, URL `https://agents.debridge.com/mcp`. Or create `.trae/mcp.json` in your project root: ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 2. Load deBridge skills from the terminal: ```shell npx skill debridge-finance/debridge-skills ``` 3. Reload the window. The deBridge tools will be available in Builder Mode and chat. --- ## Source: setup/agents/vscode.md # Visual Studio Code 1. Make sure you have an AI extension installed (Copilot, Cline, Continue, etc.). 2. Create `.vscode/mcp.json` in your project root: ```json { "servers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 3. Load deBridge skills from the terminal: ```shell npx skill debridge-finance/debridge-skills ``` 4. Reload the VS Code window. The deBridge server will start automatically when an MCP-compatible agent needs it. --- ## Source: setup/agents/warp.md # Warp AI Terminal 1. Open Warp and go to Settings, AI, MCP. Click Add Server and enter name `debridge` with URL `https://agents.debridge.com/mcp`. 2. Load deBridge skills: ```shell npx skill debridge-finance/debridge-skills ``` 3. Save the configuration. Warp will connect to the deBridge server automatically. --- ## Source: setup/agents/windsurf.md # Windsurf by Codeium 1. Open `~/.windsurf/mcp.json` (or create it) and add the deBridge server: ```json { "mcpServers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 2. Load deBridge skills from the terminal: ```shell npx skill debridge-finance/debridge-skills ``` 3. Save and reload Windsurf. The hammer icon in the Cascade panel should show the deBridge tools. --- ## Source: setup/agents/zed.md # Zed by Zed Industries 1. Open Settings (`Cmd+,` on macOS, `Ctrl+,` on Linux). Add the deBridge MCP server: ```json { "context_servers": { "debridge": { "type": "streamable-http", "url": "https://agents.debridge.com/mcp" } } } ``` 2. Load deBridge skills from the terminal: ```shell npx skill debridge-finance/debridge-skills ``` 3. Save settings and open the AI assistant panel (`Cmd+?`) to confirm deBridge tools are loaded. --- ## Source: setup/wallets/foundry.md # Foundry (Cast Keystore) Encrypted keystore wallet using Foundry's `cast` CLI. Keys are encrypted at rest with a password. EVM chains only. 1. Install Foundry if not already available: ```bash curl -L https://foundry.paradigm.xyz | bash && foundryup ``` 2. Create a new wallet or import an existing key: ```bash # Create new cast wallet new ~/.foundry/keystores/debridge # Or import an existing private key cast wallet import debridge --interactive ``` 3. Verify your wallet: ```bash cast wallet list ``` 4. Fund the wallet on the source chain before bridging. Foundry supports EVM chains only. For multi-chain support (EVM, Solana, Tron), use [OWS](../private-key/SKILL.md) instead. --- ## Source: setup/wallets/metamask.md # MetaMask (Browser Extension) MetaMask integration is currently under development. Stay tuned for updates. In the meantime, use [OWS](../private-key/SKILL.md) for local self-custody signing or [Privy](../privy/SKILL.md) for server-side embedded wallets. --- ## Source: setup/wallets/ows.md # OWS (Open Wallet Standard) — Recommended Local self-custody wallet with encrypted key storage. Works with all deBridge chains (EVM, Solana, Tron) from a single wallet. Create a new private key or import an existing one. 1. Install OWS: ```bash curl -fsSL https://docs.openwallet.sh/install.sh | bash ``` 2. Create a new wallet or import an existing key: ```bash # Create new (generates keys for all supported chains) ows wallet create # Or import an existing private key ows wallet import ``` 3. Verify your wallet and addresses: ```bash ows wallet list ``` This shows your EVM, Solana, and other chain addresses, all derived from a single wallet. 4. Fund the wallet on the source chain before bridging. Keys are encrypted at rest on your machine, decrypted only during signing, then wiped from memory. No plaintext keys in environment variables or config files. --- ## Source: setup/wallets/phantom.md # Phantom Phantom integration is currently under development. Stay tuned for updates. In the meantime, use [OWS](../private-key/SKILL.md) for local self-custody signing (supports Solana, EVM, and Tron) or [Privy](../privy/SKILL.md) for server-side embedded wallets. --- ## Source: setup/wallets/private-key.md # OWS (Open Wallet Standard) Local self-custody wallet with encrypted key storage. Works with all deBridge chains — EVM, Solana, and Tron — from a single wallet. 1. Install OWS: ```bash curl -fsSL https://docs.openwallet.sh/install.sh | bash ``` 2. Create a new wallet or import an existing key: ```bash # Create new (generates keys for all supported chains) ows wallet create # Or import an existing private key ows wallet import ``` 3. Verify your wallet and addresses: ```bash ows wallet list ``` This shows your EVM, Solana, and other chain addresses — all derived from a single wallet. 4. Fund the wallet on the source chain before bridging. Security: Keys are encrypted at rest on your machine, decrypted only during signing, then wiped from memory. No plaintext keys in environment variables or config files. --- ## Source: setup/wallets/privy.md # Privy (Embedded Wallet) Server-side wallets managed by Privy with keys secured in TEEs (Trusted Execution Environments). The agent routes trades via deBridge MCP and signs via Privy MCP. No browser, no wallet popup, no local keys. ``` User prompt → deBridge MCP (quote + tx data) → Privy MCP (sign + broadcast) → On-chain ``` 1. Sign up at dashboard.privy.io and create an app. 2. Go to Settings, Basics, API Keys and copy your App ID and App Secret. The App Secret is shown once — copy it immediately. If lost, regenerate it. 3. Install Privy MCP server: ```bash git clone https://github.com/privy-io/privy-mcp-server.git cd privy-mcp-server npm install && npm run build ``` 4. Add Privy MCP to your agent (example for Claude Code): ```bash claude mcp add privy node -- dist/index.js \ --env PRIVY_APP_ID= \ --env PRIVY_APP_SECRET= ``` For other environments, add to your MCP server configuration: ```json { "mcpServers": { "privy": { "command": "node", "args": ["/dist/index.js"], "env": { "PRIVY_APP_ID": "", "PRIVY_APP_SECRET": "" } } } } ``` 5. Create wallets via Privy MCP and fund them on the source chain. The agent passes deBridge create_tx output directly to Privy's eth_sendTransaction — no format conversion needed. Never commit App Secret to git. Keys are managed in TEEs and never exposed. --- ## Source: setup/wallets/rabby.md # Rabby Rabby integration is currently under development. Stay tuned for updates. In the meantime, use [OWS](../private-key/SKILL.md) for local self-custody signing or [Privy](../privy/SKILL.md) for server-side embedded wallets. --- ## Source: setup/wallets/walletconnect.md # WalletConnect WalletConnect integration is currently under development. Stay tuned for updates. In the meantime, use [OWS](../private-key/SKILL.md) for local self-custody signing or [Privy](../privy/SKILL.md) for server-side embedded wallets.