# Bridged Finance - Full Technical Documentation
> Non-custodial any-to-any cross-chain liquidity, bridge, and swap protocol.
> Canonical website: https://bridged.finance
> LLM index: https://bridged.finance/llms.txt
---
## Table of Contents
### 1. Getting Started
- [1.1 Protocol Overview](#getting-started-overview)
- [1.2 Developer Quickstart Guide](#getting-started-quickstart)
### 2. Bridged Cross-Chain API
- [2.1 API Endpoints Reference](#api-endpoints)
- [2.2 Swap Workflow & Execution Lifecycle](#api-swap-workflow)
- [2.3 Calldata & Token Approvals](#api-calldata-and-approvals)
- [2.4 Token Address Formats Across Chains](#api-token-address-formats)
- [2.5 Partner Fees & Attribution](#api-partner-fees)
- [2.6 Model Context Protocol (MCP) Server](#api-mcp-server)
### 3. Guides & Architecture
- [3.1 Cross-Chain Routing Engine Architecture](#guides-cross-chain-swaps)
- [3.2 Native Bitcoin Cross-Chain Routing](#guides-bitcoin-routing)
- [3.3 Slippage Tolerance & Distribution](#guides-slippage-tolerance)
- [3.4 Security Audits & Threat Model](#guides-security-and-audits)
- [3.5 Smart Contract Registry](#guides-contract-registry)
### 4. Support & FAQ
- [4.1 Frequently Asked Questions (FAQ)](#faq-general-faq)
- [4.2 Error Codes & Status Resolution](#faq-error-codes-and-status)
---
## Protocol Overview
*Category: Getting Started | Canonical URL: https://bridged.finance/docs/getting-started/overview*
# Protocol Overview
**Bridged Finance** is a decentralized, non-custodial cross-chain interoperability protocol designed to move liquidity and execute arbitrary asset swaps across independent blockchain networks.
---
## 1. What is Bridged Finance?
Bridged Finance eliminates the fragmented liquidity barriers that isolate blockchains. Traditional cross-chain bridging often requires users to wrap tokens into synthetic representations (such as WBTC or BTCB) or deposit collateral into centralized custodians.
Bridged Finance solves this by pairing decentralized automated market maker (AMM) liquidity pools with a threshold-signature relayer network. This allows any user or smart contract to execute **any-to-any** asset swaps:
- Exchange an arbitrary token on Chain A (e.g. USDC on Arbitrum)
- Receive any arbitrary token on Chain B (e.g. SOL on Solana or Native BTC on Bitcoin)
- Settle the entire transaction in a single automated workflow
---
## 2. Core Protocol Architecture
The protocol is composed of four foundational layers:
```
+-------------------------------------------------------------+
| Bridged Client Apps |
| Bridged DApp | Bridged Explorer | Bridged API |
+-------------------------------------------------------------+
|
v
+-------------------------------------------------------------+
| Smart Contracts & Gateways |
| MetaRouterGateway | MetaRouter | Bridge Proxy |
+-------------------------------------------------------------+
|
v
+-------------------------------------------------------------+
| Decentralized Relayer Network |
| Multi-Party Computation (MPC) | Consensus Engine |
+-------------------------------------------------------------+
|
v
+-------------------------------------------------------------+
| Cross-Chain Liquidity Engine |
| Octopools (Unified Pools) | DEX Aggregator Hops |
+-------------------------------------------------------------+
```
### 1. Smart Contract Layer (MetaRouter & Gateway)
When initiating a swap on an EVM network, the user approves their tokens to the `metaRouterGateway` contract. The gateway forwards the tokens to the `metaRouter`, which routes local swaps through native decentralized exchanges (such as Uniswap, PancakeSwap, or Trader Joe) before handing the intermediate asset to the bridge contract.
### 2. Cross-Chain Liquidity Engine (Octopools)
Rather than maintaining disjointed pairs for thousands of token combinations, Bridged Finance utilizes unified multi-asset liquidity pools known as **Octopools**. These pools hold major stablecoins and gas assets across chains, allowing efficient cross-chain conversions with minimal slippage.
### 3. Decentralized Relayer Network
A distributed network of independent relayer nodes monitors transaction events across all supported blockchains. When a cross-chain transfer event is emitted on the source network, the relayers validate the transaction using a threshold signature scheme (TSS) and sign the corresponding execution instruction on the destination blockchain.
### 4. Developer Tools & REST API
The protocol exposes high-speed REST endpoints that calculate optimal swap routes, budget gas and fees, and generate ready-to-sign transaction calldata for integrators.
---
## 3. Supported Ecosystems
Bridged Finance supports cross-chain swaps across 57+ blockchains:
| Category | Chains Included |
| :--- | :--- |
| **Major EVM Networks** | Ethereum, BNB Smart Chain, Arbitrum One, Base, Polygon, Optimism, Avalanche C-Chain, Linea, Scroll, zkSync Era |
| **High-Growth EVM & L2s** | Blast, Berachain, Manta Pacific, Taiko, Sonic, Abstract, Mode, Fraxtal, Metis, Mantle, Rootstock, Sei v2 |
| **Non-EVM Networks** | Bitcoin (Native BTC), Solana (SOL & SPL tokens), TRON (TRX & TRC-20), TON (The Open Network) |
To inspect live blockchain configurations, visit the [API Endpoints Reference](/api/endpoints) or open the [Bridged Explorer](/explorer).
---
## 4. Key Security Invariants
1. **Non-Custodial Escrow:** At no point does Bridged Finance or any operator take custody of user private keys or discretionary control of assets.
2. **Deterministic Calldata:** Transaction calldata generated by the API contains strict destination address bounds and minimum output limits (`amountOutMin`).
3. **Slippage Protection:** If market fluctuations cause the received amount to fall below the user's configured slippage threshold during transit, the transaction protects user funds by delivering the transit asset safely to the user's destination address for manual redemption.
4. **Independent Audits:** Protocol smart contracts have undergone rigorous third-party security audits from industry-leading security firms including Zokyo, Omniscia, SlowMist, and Hacken.
---
## 5. Next Steps
- Proceed to the [Quickstart Guide](/getting-started/quickstart) to run your first cross-chain swap via the API.
- Explore the [API Endpoints Reference](/api/endpoints) for complete request and response schemas.
---
## Developer Quickstart Guide
*Category: Getting Started | Canonical URL: https://bridged.finance/docs/getting-started/quickstart*
# Developer Quickstart Guide
This guide walks you through integrating the **Bridged Finance API** to perform a cross-chain swap from start to finish.
In this tutorial, we will execute a swap of **100 USDC on Arbitrum** (Chain ID: `42161`) to **USDT on BNB Chain** (Chain ID: `56`).
---
## Prerequisites
- Node.js v18+ or any HTTP client (such as `curl` or `fetch`)
- An Ethereum/EVM wallet (MetaMask, Rabby, or an Ethers.js / Viem signer)
- Arbitrum RPC access with test funds
---
## Step 1: Configure Your Partner Identifier
Every request to the Bridged Finance API should include the `X-Partner-Id` header. This custom identifier attributes swaps to your platform for analytics and optional partner fee collection.
```http
X-Partner-Id: your-organization-name
```
No registration or API key generation is required. Simply select a distinct string for your integration.
---
## Step 2: Fetch Supported Networks
Query the `/v1/chains` endpoint to verify network availability and obtain internal chain identifiers:
```bash
curl -X 'GET' \
'https://api.symbiosis.finance/crosschain/v1/chains' \
-H 'accept: application/json' \
-H 'X-Partner-Id: your-organization-name'
```
### Response Example:
```json
[
{
"id": 42161,
"name": "Arbitrum One",
"rpc": "https://arb1.arbitrum.io/rpc",
"explorer": "https://arbiscan.io"
},
{
"id": 56,
"name": "BNB Smart Chain",
"rpc": "https://bsc-dataseed.binance.org",
"explorer": "https://bscscan.com"
}
]
```
---
## Step 3: Request a Quote and Transaction Calldata
To swap 100 USDC (`0xaf88d065e77c8cC2239327C5EDb3A432268e5831`) on Arbitrum to USDT (`0x55d398326f99059fF775485246999027B3197955`) on BNB Chain, send a `POST` request to `/v2/quote`:
```bash
curl -X 'POST' \
'https://api.symbiosis.finance/crosschain/v2/quote' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-Partner-Id: your-organization-name' \
-d '{
"tokenAmountIn": {
"chainId": 42161,
"address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
"amount": "100000000",
"decimals": 6,
"symbol": "USDC"
},
"tokenOut": {
"chainId": 56,
"address": "0x55d398326f99059fF775485246999027B3197955",
"decimals": 18,
"symbol": "USDT"
},
"from": "0xYourWalletAddressHere",
"to": "0xYourRecipientAddressHere",
"slippage": 100
}'
```
> **Note on Decimals:**
> The `amount` parameter must be provided in the token's smallest unit (atomic units). 100 USDC with 6 decimals is `100000000`. Slippage `100` corresponds to `1.0%`.
### Key Fields in the Quote Response:
- `tokenAmountOut.amount`: Estimated token amount received on destination chain.
- `tx.to`: Smart contract address to call on the source chain (the `metaRouterGateway` or `metaRouter`).
- `tx.data`: Encoded execution calldata.
- `tx.value`: Native gas value (in wei) that must be passed with the transaction (for gas fees or native currency swaps).
- `approveTo`: Smart contract address that the user must approve to spend the input ERC-20 token.
---
## Step 4: Approve the Smart Contract
Before sending the transaction, the user must approve the `approveTo` address returned in the quote response (the `metaRouterGateway` on Arbitrum).
Using Ethers.js v6:
```typescript
import { ethers } from "ethers";
const ERC20_ABI = [
"function approve(address spender, uint256 amount) public returns (bool)",
"function allowance(address owner, address spender) public view returns (uint256)"
];
async function ensureAllowance(
signer: ethers.Signer,
tokenAddress: string,
spenderAddress: string,
amount: bigint
) {
const tokenContract = new ethers.Contract(tokenAddress, ERC20_ABI, signer);
const ownerAddress = await signer.getAddress();
const currentAllowance = await tokenContract.allowance(ownerAddress, spenderAddress);
if (currentAllowance < amount) {
console.log("Approving token spending for metaRouterGateway...");
const tx = await tokenContract.approve(spenderAddress, amount);
await tx.wait(1);
console.log("Token approval confirmed on-chain.");
}
}
```
---
## Step 5: Submit the Cross-Chain Swap Transaction
Once approved, transmit the `tx` payload returned from `/v2/quote` to the source blockchain:
```typescript
async function executeSwap(signer: ethers.Signer, quoteTx: any) {
console.log("Submitting cross-chain swap transaction...");
const txResponse = await signer.sendTransaction({
to: quoteTx.to,
data: quoteTx.data,
value: BigInt(quoteTx.value || "0"),
});
console.log(`Transaction broadcast: ${txResponse.hash}`);
const receipt = await txResponse.wait(1);
console.log(`Confirmed in block: ${receipt.blockNumber}`);
return txResponse.hash;
}
```
---
## Step 6: Monitor Cross-Chain Settlement
After the transaction confirms on Arbitrum, query the transaction status endpoint:
```bash
curl -X 'GET' \
'https://api.symbiosis.finance/crosschain/v2/tx/42161/0xYourTxHashHere' \
-H 'accept: application/json' \
-H 'X-Partner-Id: your-organization-name'
```
### Status Lifecycles:
- `pending`: Relayers are observing confirmation on the source chain.
- `in-progress`: Relayers have signed the MPC transaction and sent execution to the destination network.
- `success`: Destination chain transaction confirmed. Funds have arrived at the recipient's wallet.
- `reverted`: Transaction was safely refunded to the sender or delivered in transit asset.
Alternatively, users can paste the transaction hash directly into the [Bridged Explorer](/explorer) for real-time visual tracking.
---
## API Endpoints Reference
*Category: Bridged Cross-Chain API | Canonical URL: https://bridged.finance/docs/api/endpoints*
# API Endpoints Reference
The **Bridged Finance API** provides high-performance, non-custodial cross-chain quote calculation, calldata generation, and transaction monitoring across 57+ blockchains.
---
## Production Base URL
```
https://api.symbiosis.finance/crosschain
```
### Standard Request Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `Accept` | `string` | Yes | Must be `application/json` |
| `Content-Type` | `string` | For POST | Must be `application/json` |
| `X-Partner-Id` | `string` | Recommended | Integrator identifier for analytics and custom fee attribution (e.g. `your-app-name`) |
---
## 1. Supported Chains (GET /v1/chains)
Retrieves the catalog of all blockchains currently supported by the Bridged routing engine.
```http
GET /v1/chains HTTP/1.1
Host: api.symbiosis.finance
Accept: application/json
X-Partner-Id: your-partner-id
```
### Response Attributes:
- `id` (number): Numeric chain identifier (EVM Chain ID or protocol internal ID for non-EVM networks).
- `name` (string): Human-readable network name (e.g. `Arbitrum One`, `BNB Smart Chain`, `Solana`).
- `rpc` (string): Public RPC URL used for state reading.
- `explorer` (string): Block explorer base URL.
---
## 2. Token Catalog (GET /v2/tokens)
Returns all tokens indexed by the protocol across supported networks, including native assets, stablecoins, and decentralized exchange liquidity tokens.
```http
GET /v2/tokens HTTP/1.1
Host: api.symbiosis.finance
Accept: application/json
X-Partner-Id: your-partner-id
```
### Response Example:
```json
[
{
"chainId": 1,
"address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
"symbol": "USDT",
"name": "Tether USD",
"decimals": 6,
"icon": "https://assets.coingecko.com/coins/images/325/large/Tether.png"
},
{
"chainId": 56,
"address": "0x55d398326f99059fF775485246999027B3197955",
"symbol": "USDT",
"name": "Tether USD",
"decimals": 18,
"icon": "https://assets.coingecko.com/coins/images/325/large/Tether.png"
}
]
```
---
## 3. Swap Quote & Calldata (POST /v2/quote)
Calculates the optimal swap route, fee breakdown, and generates executable calldata for EVM and smart-contract-based networks.
```http
POST /v2/quote HTTP/1.1
Host: api.symbiosis.finance
Content-Type: application/json
Accept: application/json
X-Partner-Id: your-partner-id
```
### Request Payload:
```json
{
"tokenAmountIn": {
"chainId": 42161,
"address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
"amount": "500000000",
"decimals": 6,
"symbol": "USDC"
},
"tokenOut": {
"chainId": 1,
"address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
"decimals": 6,
"symbol": "USDT"
},
"from": "0xUserSourceAddress",
"to": "0xRecipientDestinationAddress",
"slippage": 100
}
```
### Request Parameters:
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `tokenAmountIn.chainId` | `number` | Yes | Source network ID |
| `tokenAmountIn.address` | `string` | Yes | Source token contract address (`0x...`) |
| `tokenAmountIn.amount` | `string` | Yes | Raw atomic token amount (e.g. `500000000` for 500 USDC) |
| `tokenAmountIn.decimals` | `number` | Yes | Source token decimals |
| `tokenAmountIn.symbol` | `string` | Yes | Source token symbol |
| `tokenOut.chainId` | `number` | Yes | Destination network ID |
| `tokenOut.address` | `string` | Yes | Destination token contract address (`0x...`) |
| `tokenOut.decimals` | `number` | Yes | Destination token decimals |
| `tokenOut.symbol` | `string` | Yes | Destination token symbol |
| `from` | `string` | Yes | Address of the sender wallet on the source chain |
| `to` | `string` | Yes | Recipient address on the destination chain |
| `slippage` | `number` | Yes | Max slippage tolerance in basis points (`100` = 1.0%) |
### Key Response Fields:
```json
{
"tokenAmountOut": {
"chainId": 1,
"address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
"amount": "498850000",
"decimals": 6,
"symbol": "USDT"
},
"tokenAmountOutMin": {
"amount": "493861500"
},
"fee": {
"amount": "1150000",
"symbol": "USDC"
},
"approveTo": "0x444b7D47385942f9b23b49e17b8f05CE8a176214",
"tx": {
"chainId": 42161,
"to": "0x444b7D47385942f9b23b49e17b8f05CE8a176214",
"data": "0x2e0618060000...",
"value": "0"
}
}
```
---
## 4. Bitcoin Deposit Swap (POST /v2/swap)
Used specifically for **Native Bitcoin to Any Chain** transfers. Returns an authoritative BTC deposit address monitored by protocol relayers.
```http
POST /v2/swap HTTP/1.1
Host: api.symbiosis.finance
Content-Type: application/json
Accept: application/json
X-Partner-Id: your-partner-id
```
### Request Example (BTC to Arbitrum USDC):
```json
{
"tokenAmountIn": {
"chainId": 0,
"address": "",
"amount": "5000000",
"decimals": 8,
"symbol": "BTC"
},
"tokenOut": {
"chainId": 42161,
"address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
"decimals": 6,
"symbol": "USDC"
},
"to": "0xYourArbitrumAddress",
"slippage": 100
}
```
### Response Example:
```json
{
"address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
"tokenAmountOut": {
"amount": "3450250000",
"symbol": "USDC"
},
"validUntil": 1730000000
}
```
When user sends `0.05 BTC` to `bc1qxy2...`, the relayer network detects the transaction upon block confirmation and executes the swap to the destination address.
---
## 5. Transaction Status Tracker (GET /v2/tx)
Monitors the real-time settlement status of a cross-chain swap.
```http
GET /v2/tx/{chainID}/{txHash} HTTP/1.1
Host: api.symbiosis.finance
Accept: application/json
X-Partner-Id: your-partner-id
```
### Response Schema:
```json
{
"status": "success",
"hash": "0xDestinationTxHash",
"sourceChainId": 42161,
"destinationChainId": 1,
"amountIn": "500000000",
"amountOut": "498850000",
"timestamp": 1729000000
}
```
### Possible Status Values:
- `pending`: Transaction submitted to source blockchain, awaiting required block confirmations.
- `in-progress`: Relayers have received event proofs and are processing the destination transaction.
- `success`: Destination transaction confirmed on-chain.
- `reverted`: Transaction encountered an error or slippage breach, and refund sequence was dispatched.
---
## 6. Swap Duration Estimator (GET /v1/swap-durations)
Returns historical moving-average settlement times (in seconds) between network pairs.
```http
GET /v1/swap-durations HTTP/1.1
Host: api.symbiosis.finance
Accept: application/json
```
---
## 7. Engine Health Check (GET /health-check)
Provides status information for RPC connectivity and core contract indexing.
```http
GET /health-check HTTP/1.1
Host: api.symbiosis.finance
Accept: application/json
```
---
## OpenAPI / Swagger Interactive Playground
The underlying engine schemas can be explored in the [Official Swagger Documentation](https://api.symbiosis.finance/crosschain/docs/).
*(Note: A native in-app Swagger explorer at `api.bridged.finance/docs` will be introduced in an upcoming release).*
---
## Swap Workflow & Execution Lifecycle
*Category: Bridged Cross-Chain API | Canonical URL: https://bridged.finance/docs/api/swap-workflow*
# Swap Workflow & Execution Lifecycle
This document describes the complete technical lifecycle of a cross-chain swap executed via the **Bridged Finance API**.
---
## 1. Standard EVM to EVM Swap Lifecycle
The majority of cross-chain swaps between Ethereum Virtual Machine (EVM) compatible networks follow a 6-step deterministic lifecycle:
```
[ User Wallet ] [ Bridged API ] [ Source Chain ] [ Relayer Network ] [ Destination Chain ]
| | | | |
| 1. Request Quote | | | |
|------------------------>| | | |
| 2. Calldata & ApproveTo | | | |
|<------------------------| | | |
| | | |
| 3. Approve Token (if ERC20) | | |
|------------------------------------------------>| | |
| | | |
| 4. Submit Calldata | | |
|------------------------------------------------>| | |
| | 5. Emit Cross-Chain | |
| | Transfer Event | |
| |----------------------->| |
| | | 6. MPC Consensus & |
| | | Execute Delivery |
| | |------------------------>|
| | | |
| 7. Query /v2/tx Status | | |
|------------------------>| | | |
| Status: "success" | | | |
|<------------------------| | | |
```
### Detailed Steps:
1. **Quote Request:** The application calls `POST /v2/quote` with the source chain, source token, destination chain, destination token, amount, and recipient address.
2. **Route Generation:** The engine computes the optimal route (local source DEX swap -> cross-chain transit pool -> destination DEX swap) and returns the transaction payload (`tx.to`, `tx.data`, `tx.value`) and `approveTo`.
3. **ERC-20 Approval:** If the source token is an ERC-20 token, the application verifies the user's allowance for `approveTo` (`metaRouterGateway`). If insufficient, an on-chain `approve()` transaction is submitted.
4. **Transaction Dispatch:** The application transmits `tx.data` to `tx.to` with the specified `tx.value` using the user's wallet signer.
5. **Event Emission:** The source smart contract locks/burns the asset and emits a cryptographic log event containing swap parameters and recipient details.
6. **Relayer Attestation & Execution:** Distributed relayer nodes observe the block confirmation, execute threshold signature verification (TSS/MPC), and submit the fulfillment transaction to the destination network.
7. **Settlement:** The destination contract executes the local swap (if needed) and transfers the target tokens directly to the recipient wallet address.
---
## 2. EVM to Non-EVM Swaps (Solana, TRON, TON)
When swapping from an EVM network to a non-EVM destination:
- The request is submitted to `POST /v2/quote` as usual.
- The `to` parameter must contain the recipient's native non-EVM address (e.g. a Solana base58 address, TRON base58 address, or TON friendly address).
- The Bridged engine verifies recipient address checksums and passes the native target destination to the relayer execution layer.
- Once source confirmations pass, the relayer network dispatches a native transfer on Solana/TRON/TON directly to the recipient.
---
## 3. Native Bitcoin to Any Chain (BTC -> Any)
Swaps from Bitcoin originate from the Bitcoin blockchain, which lacks smart contracts. Therefore, the workflow utilizes secure threshold-signed deposit vaults:
1. **Request Deposit Address:** The application calls `POST /v2/swap` specifying source chain as Bitcoin (`chainId: 0` or `"btc"`), source asset as BTC, and target network/token.
2. **Receive Deposit Details:** The API returns:
- A single-use native Bitcoin deposit address (`bc1q...`).
- The quoted output amount.
- An expiration timestamp (`validUntil`).
3. **User Transfers BTC:** The user sends the specified BTC amount from any standard Bitcoin wallet (Xverse, Unisat, Electrum, Ledger, or exchange) to the deposit address.
4. **Confirmation Monitoring:** Protocol relayers track the Bitcoin mempool and await required block confirmations (typically 1 to 2 confirmations).
5. **Destination Execution:** Once confirmed, the relayer network triggers the cross-chain execution on the target chain, delivering target tokens to the user's wallet.
---
## 4. Any Chain to Native Bitcoin (Any -> BTC)
Swapping from any chain to native Bitcoin uses the standard `POST /v2/quote` endpoint:
- Set `tokenOut.chainId: 0` (or the internal BTC chain ID).
- Pass a valid native Bitcoin recipient address in the `to` field (e.g. Native SegWit `bc1q...`, Taproot `bc1p...`, or Legacy `1...`).
- The user executes the source transaction on their connected wallet.
- The relayer network releases native BTC directly from protocol liquidity vaults to the recipient's Bitcoin address.
---
## 5. Critical Integration Rules
### Refresh Calldata Every 30-60 Seconds
DeFi liquidity and automated market maker rates fluctuate continuously. Calldata received from `/v2/quote` includes time-sensitive price parameters and minimum output bounds. Integrators should refresh quotes every 30 to 60 seconds if the user has not yet signed the transaction.
### Never Alter API Calldata
Do not attempt to decode, modify, or append parameters to the `tx.data` returned by the API. Any alteration invalidates cryptographic signatures and will cause contract revert on-chain.
### Validate Address Compatibility
Always verify that the `to` address matches the cryptographic address format of the destination blockchain before submitting quotes. Refer to [Token Address Formats](/api/token-address-formats) for formatting specifications.
---
## Calldata & Token Approvals
*Category: Bridged Cross-Chain API | Canonical URL: https://bridged.finance/docs/api/calldata-and-approvals*
# Calldata & Token Approvals
This document outlines the security invariants, approval protocols, and calldata rules required for safely executing transactions with the **Bridged Finance Protocol**.
---
## Pre-Production Security Checklist
Before deploying any integration with real user assets to Mainnet, verify the following security requirements:
> **Important Security Invariant:**
> If any of these checks fail, user assets could be put at risk. You must never deploy to Mainnet without validating these items.
1. **Strict ERC-20 Approval Target:**
Always approve ERC-20 tokens solely for the `metaRouterGateway` contract on each blockchain. Never approve arbitrary addresses returned by external sources.
2. **Contract Address Verification:**
Ensure that the contract addresses in your integration match the official deployment addresses published in the [Smart Contract Registry](/guides/contract-registry).
3. **Calldata Immutability:**
Never modify, manipulate, slice, or cache calldata returned from `/v2/quote`.
4. **Freshness Guarantee:**
Because on-chain liquidity pool reserves update with every block, calldata must be regenerated if more than 60 seconds have elapsed before user signing.
5. **Mainnet Canary Testing:**
Prior to full production release, execute at least one end-to-end small test transaction on Mainnet to verify end-to-end gas budgeting and execution paths.
---
## 1. The `metaRouterGateway` Architecture
To protect users against rogue contract allowances, Bridged Finance enforces a segregated gateway architecture:
```
[ User Wallet ]
|
| 1. approve(metaRouterGateway, amount)
v
+-------------------------------+
| metaRouterGateway | <--- The ONLY contract that holds user allowance
+-------------------------------+
|
| 2. pull tokens & delegate call
v
+-------------------------------+
| metaRouter | <--- Performs multi-hop routing & DEX aggregations
+-------------------------------+
|
| 3. transfer to Bridge
v
+-------------------------------+
| Bridge Proxy | <--- Emits cross-chain MPC event
+-------------------------------+
```
### Why Only `metaRouterGateway`?
- **Isolation:** If routing logic or third-party DEX adapters are upgraded, the gateway contract remains unchanged. Users do not need to revoke and grant new allowances.
- **Safety:** The gateway performs strict sanity checks on the caller and calldata before transferring any token.
---
## 2. Managing ERC-20 Approvals
When the input token is an ERC-20 (or equivalent non-native token):
1. Check the user's current allowance for `metaRouterGateway`:
```typescript
const allowance = await tokenContract.allowance(userAddress, metaRouterGatewayAddress);
```
2. If `allowance < amountIn`:
- Prompt the user to sign an `approve` transaction.
- For maximum security and minimal attack surface, approve the **exact required amount** or an explicit user-selected limit.
3. Wait for `1 confirmation` on the source blockchain before attempting to execute the swap calldata.
### Ethers.js v6 Example:
```typescript
import { ethers } from "ethers";
const ERC20_ABI = [
"function allowance(address owner, address spender) view returns (uint256)",
"function approve(address spender, uint256 amount) returns (bool)"
];
export async function checkAndApproveToken(
signer: ethers.Signer,
tokenAddress: string,
gatewayAddress: string,
requiredAmount: bigint
): Promise {
const token = new ethers.Contract(tokenAddress, ERC20_ABI, signer);
const owner = await signer.getAddress();
const currentAllowance = await token.allowance(owner, gatewayAddress);
if (currentAllowance < requiredAmount) {
console.log(`Current allowance (${currentAllowance}) < required (${requiredAmount}). Requesting approval...`);
const tx = await token.approve(gatewayAddress, requiredAmount);
await tx.wait(1);
console.log("Approval confirmed.");
} else {
console.log("Sufficient allowance exists.");
}
}
```
---
## 3. Handling Native Gas Tokens (`ETH`, `BNB`, `AVAX`, `MATIC`)
When the source token is a native blockchain currency:
- **No ERC-20 approval is required.**
- The required native token amount must be passed in the `tx.value` field of the transaction.
- The API's `/v2/quote` response provides `tx.value` in wei.
- Ensure the user's wallet has sufficient balance for **both** `tx.value` and the gas fee of the source chain.
---
## 4. Calldata Execution
The `tx` object returned by `/v2/quote` provides all necessary parameters for transaction broadcasting:
```json
{
"tx": {
"chainId": 1,
"to": "0x444b7D47385942f9b23b49e17b8f05CE8a176214",
"data": "0x2e061806000000000000000000...",
"value": "0"
}
}
```
### Dispatching with Viem / Wagmi:
```typescript
import { useSendTransaction } from "wagmi";
export function useExecuteSwap() {
const { sendTransactionAsync } = useSendTransaction();
const execute = async (quoteTx: any) => {
return await sendTransactionAsync({
to: quoteTx.to as `0x${string}`,
data: quoteTx.data as `0x${string}`,
value: BigInt(quoteTx.value || "0"),
});
};
return { execute };
}
```
---
## Token Address Formats Across Chains
*Category: Bridged Cross-Chain API | Canonical URL: https://bridged.finance/docs/api/token-address-formats*
# Token Address Formats Across Chains
Except for native gas assets and Bitcoin, token addresses submitted to the **Bridged Finance API** are represented in standard EVM-style `0x...` hexadecimal format.
This document details how addresses on non-EVM blockchains (TON, TRON, and Solana) are encoded and formatted when constructing API payloads.
---
## 1. EVM Networks (Ethereum, BNB Chain, Arbitrum, Base, etc.)
For all EVM-compatible networks, token addresses use their standard 20-byte contract addresses:
```json
{
"tokenAmountIn": {
"chainId": 1,
"address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"amount": "1000000000",
"decimals": 6,
"symbol": "USDC"
}
}
```
---
## 2. TON (The Open Network)
On TON, token addresses are derived from their 32-byte hash and represented as an EVM-length identifier in `address`. The full native TON friendly address is supplied in the `attributes.ton` field:
```json
{
"tokenAmountIn": {
"chainId": 85918,
"address": "0x9328ED75956C38a25f59028B146Fecd3621Dfe",
"amount": "1000000000",
"decimals": 6,
"symbol": "USDT",
"attributes": {
"ton": "EQCxE6mUtQJKFngfaROTKOt11ZbDiX1kCixRv7Nw2Id_sDS"
}
}
}
```
When receiving assets on TON, provide the user's friendly TON address (`EQ...` or `UQ...`) in the top-level `to` field or `tokenOut.attributes`.
---
## 3. TRON
TRON uses Base58Check addresses (starting with `T`). These addresses correspond directly to a 21-byte hex string (starting with `41`):
- **Base58 format:** `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` (USDT on TRON)
- **Hex format:** `41a614f803b6fd780986a42c78ec9c7f77e6ded13c`
- **EVM-style format:** `0xa614f803b6fd780986a42c78ec9c7f77e6ded13c`
The mapping is fully deterministic and reversible. In payload requests, you may submit the EVM `0x...` hex form.
---
## 4. Solana
Solana uses 32-byte Base58 public keys for SPL token mints (e.g. `Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB` for USDT).
Because Solana public keys cannot be compressed into 20-byte EVM addresses without collisions, the Bridged protocol assigns unique sequential hexadecimal identifiers for Solana tokens (e.g. `0x000...0001`), and maps the actual SPL mint in the `attributes.solana` field:
```json
{
"tokenAmountIn": {
"chainId": 5426,
"address": "0x0000000000000000000000000000000000000001",
"amount": "1000000000",
"decimals": 6,
"symbol": "USDT",
"attributes": {
"solana": "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB"
}
}
}
```
To fetch all configured Solana token identifiers, query `GET /v2/tokens` and filter by `chainId: 5426`.
---
## 5. Verifying Payload Formats Live
Integrators can verify the exact JSON payload for any token pair by inspecting the network traffic in the [Bridged DApp](/app):
1. Open [Bridged DApp](/app).
2. Select the source network and token, and the destination network and token.
3. Open your browser Developer Tools (`F12`) and switch to the **Network** tab.
4. Filter for `quote`.
5. Inspect the **Payload** and **Response** tabs to view the exact JSON structures used in production.
---
## Partner Fees & Attribution
*Category: Bridged Cross-Chain API | Canonical URL: https://bridged.finance/docs/api/partner-fees*
# Partner Fees & Attribution
The **Bridged Finance API** includes built-in mechanisms for integrators, wallets, and decentralized applications to track transaction volume and collect custom protocol fees on swaps.
---
## 1. Setting Up Partner Identification (X-Partner-Id)
Every application integrating Bridged Finance can specify an identifier in the request header:
```http
X-Partner-Id: your-organization-id
```
### Characteristics of the Partner Identifier:
- **Zero Registration Needed:** You do not need to register an account or request API tokens. Choose a unique, permanent string for your team (such as `mywallet-mobile` or `dex-aggregator`).
- **Analytics & Volume Attribution:** All transactions originating from your requests are attributed to your identifier.
- **Reporting:** Transaction metrics can be queried and analyzed in the [Bridged Explorer](/explorer).
---
## 2. Protocol Fee Breakdown
During cross-chain operations, the protocol collects standard operational fees:
1. **Destination Network Gas Fee:**
The relayer network pays native gas on the destination blockchain to deliver your tokens. This cost is calculated dynamically in real-time and deducted transparently from the swap amount.
2. **Bridge Liquidity Fee:**
A micro-fee (typically 0.1% or lower depending on the route) that compensates liquidity providers in the multi-asset Octopools.
---
## 3. Custom Partner Fee Collection
Integrators have the option to apply a custom fee (e.g. 0.1% to 0.5%) on top of the standard protocol rates to monetize their integration.
### Cross-Chain Operations
For cross-chain transfers, the protocol provides dedicated on-chain **Fee Collector Contracts**:
- **General Fee Collector:** Deployed on the protocol host chain. Used for all cross-chain swaps except those involving Bitcoin.
- **BTC Fee Collectors:** Deployed on **BNB Smart Chain, Ethereum, Rootstock, and Citrea**. Used specifically for swaps to and from the Bitcoin network.
### How Partner Fees Work:
1. When generating a quote with partner fees enabled, the engine calculates the fee in the transit asset.
2. The fee portion is routed directly into the Partner Fee Collector smart contract.
3. The partner wallet retains ownership and withdrawal authority over the accrued balances in the fee collector contract.
4. Partners can withdraw their accumulated revenue in stablecoins or native assets at any time via standard Web3 calls.
---
## 4. On-Chain Swaps Fee Handling
For pure on-chain single-network swaps (e.g. swapping tokens purely within Arbitrum without crossing chains), fees are managed via local router contracts.
If your application requires charging custom affiliate fees on purely local single-chain swaps, you can pass your custom referral recipient address into the router calldata or deploy an independent fee collector wrapper.
---
## 5. Implementation Recommendations
- **Transparency:** Always display the estimated fee breakdown (bridge fee + network gas) clearly to users before they sign transactions in your UI.
- **Consistency:** Use the same `X-Partner-Id` across all client platforms (iOS, Android, Web, Bot) to aggregate volume under a single analytics umbrella.
- **Assistance:** For high-volume integrators wishing to deploy a custom fee collector contract, consult the [Smart Contract Registry](/guides/contract-registry) or contact the core protocol engineering team.
---
## Model Context Protocol (MCP) Server
*Category: Bridged Cross-Chain API | Canonical URL: https://bridged.finance/docs/api/mcp-server*
# Model Context Protocol (MCP) Server
The **Bridged Model Context Protocol (MCP) Server** connects AI agents, LLM applications, and coding assistants directly to 50+ blockchains and 6,000+ tokens. Through standard JSON-RPC over `stdio` or HTTP/SSE, agents can inspect token liquidity, calculate optimal cross-chain routes, verify balances, and autonomously execute swaps.
---
## Architecture & Transport
Bridged MCP operates primarily over standard I/O (`stdio`), running locally on developer machines alongside clients such as **Claude Desktop**, **Cursor IDE**, **Windsurf**, and **Claude Code CLI**.
```
+-----------------------------------------------------------+
| AI Client / Agent |
| (Claude Desktop, Cursor, Windsurf, LangChain) |
+-----------------------------------------------------------+
|
Standard I/O (stdio)
|
+-----------------------------------------------------------+
| Bridged MCP Server (Local) |
| `bridged-public-mcp` |
+-----------------------------------------------------------+
|
HTTPS JSON-RPC / REST
|
+-----------------------------------------------------------+
| Bridged Protocol Routing Engine |
| (50+ Blockchains, Octopool, Aggregated AMMs) |
+-----------------------------------------------------------+
```
---
## Installation & Quickstart
### 1. Instant Run via NPX
```bash
npx -y bridged-public-mcp
```
### 2. Docker Container
```bash
docker run -i --rm -e PRIVATE_KEY=0x... bridgedfinance/bridged-public-mcp:latest
```
### 3. Hosted Endpoint
For remote agent systems or containerized runners, connect directly to the hosted SSE gateway:
```
https://mcp.bridged.finance/mcp
```
---
## Execution Modes
| Mode | Key Requirement | Capabilities |
| :--- | :--- | :--- |
| **Read-Only Mode** | None (Zero keys) | Token search, quote calculation, route discovery, gas estimation, balance checks, transaction tracking, and pre-filled web app URLs. |
| **Autonomous Execution Mode** | `PRIVATE_KEY` set in `.env` | Everything in Read-Only, plus transaction calldata signing and direct on-chain broadcasting. |
---
## Complete Tools Reference
The Bridged MCP Server exposes 10 standardized tools:
### 1. get_quote
Calculates optimal cross-chain routing, estimated output amounts, protocol fees, and price impact between any token pair.
#### Input Schema:
```json
{
"token_in": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
"token_out": "0x8c3C1c6F9715642512967151048b61D1535492d2",
"amount_in": "100.0",
"from_chain_id": 1,
"to_chain_id": 42161,
"from_address": "0xUserWalletAddress",
"to_address": "0xRecipientAddress",
"slippage": 1.0
}
```
#### Returns:
- `amount_out` (string): Expected destination amount in human-readable units.
- `fees` (object): Relayer, liquidity pool, and gas fees.
- `estimated_time` (number): Estimated completion time in seconds.
- `price_impact` (number): Slippage and liquidity impact percentage.
- `route` (array): Multi-hop DEX and cross-chain bridge steps.
---
### 2. search_tokens
Fuzzy search across 6,000+ indexed tokens by symbol, name, or contract address.
#### Input Schema:
```json
{
"query": "USDC",
"chain_id": 1,
"limit": 10
}
```
#### Returns:
- Array of matching tokens with `name`, `symbol`, `decimals`, `address`, `chainId`, and `iconUrl`.
---
### 3. get_supported_chains
Retrieves all blockchains supported by the Bridged protocol.
#### Input Schema:
`{}` (no parameters)
#### Returns:
- Array of chains with `id`, `name`, `type` (`evm` or `non-evm`), `native_currency`, and `explorer_url`.
---
### 4. get_swap_calldata
Builds execution payload with allowance verification and gas parameters.
#### Input Schema:
```json
{
"token_in": "0x...",
"token_out": "0x...",
"amount_in": "100.0",
"from_chain_id": 1,
"to_chain_id": 42161,
"from_address": "0x...",
"to_address": "0x...",
"slippage": 1.0
}
```
#### Returns:
- `to` (string): Target smart contract address.
- `data` (string): Hex-encoded calldata.
- `value` (string): Native gas value to send with the transaction.
- `approve_required` (boolean): Whether an ERC-20 approve call is required first.
- `approve_address` (string): Spender contract address for approval.
---
### 5. get_swap_url
Generates a pre-filled Bridged web app URL for human-in-the-loop signing.
#### Input Schema:
```json
{
"token_in": "USDT",
"token_out": "ETH",
"from_chain_id": 56,
"to_chain_id": 1,
"amount_in": "250.0"
}
```
#### Returns:
- `url` (string): Deep link URL for browser execution.
---
### 6. get_balances
Retrieves token balances for a wallet address across one or all supported chains.
#### Input Schema:
```json
{
"address": "0xYourWalletAddress",
"chain_id": 1
}
```
#### Returns:
- Array of token balances with symbol, token address, balance, and USD value.
---
### 7. get_tx_status
Tracks the progress and status of a cross-chain transfer by origin transaction hash.
#### Input Schema:
```json
{
"tx_hash": "0x123...",
"chain_id": 1
}
```
#### Returns:
- `status` (`pending` | `success` | `reverted`)
- `source_tx` (object): Origin block and confirmation status.
- `destination_tx` (object): Destination block, hash, and delivery status.
---
### 8. get_rpcs
Returns verified public RPC endpoints for a chain, sorted by real-time latency.
#### Input Schema:
```json
{
"chain_id": 1
}
```
#### Returns:
- Array of validated RPC URLs with ping latency in milliseconds.
---
### 9. get_instructions
Provides system instructions and routing rules for AI models to understand protocol conventions and decimals.
#### Input Schema:
`{}` (no parameters)
#### Returns:
- System prompt and tool chaining guidelines.
---
### 10. get_swap_calldata_and_sign_and_broadcast
All-in-one autonomous execution. Calculates quote, checks allowance, generates calldata, signs with `PRIVATE_KEY`, and broadcasts on-chain.
#### Input Schema:
```json
{
"token_in": "0x...",
"token_out": "0x...",
"amount_in": "50.0",
"from_chain_id": 1,
"to_chain_id": 42161,
"to_address": "0x...",
"slippage": 1.0
}
```
#### Returns:
- `tx_hash` (string): Broadcasted transaction hash.
- `tracking_url` (string): Explorer status link.
---
## Client Configuration Examples
### Claude Desktop (`claude_desktop_config.json`)
```json
{
"mcpServers": {
"bridged": {
"command": "npx",
"args": ["-y", "bridged-public-mcp"]
}
}
}
```
### Cursor IDE (`.cursor/mcp.json`)
```json
{
"mcpServers": {
"bridged": {
"command": "npx",
"args": ["-y", "bridged-public-mcp"]
}
}
}
```
### Windsurf IDE (`mcp_config.json`)
```json
{
"mcpServers": {
"bridged": {
"command": "npx",
"args": ["-y", "bridged-public-mcp"]
}
}
}
```
---
## Cross-Chain Routing Engine Architecture
*Category: Guides & Architecture | Canonical URL: https://bridged.finance/docs/guides/cross-chain-swaps*
# Cross-Chain Routing Engine Architecture
The **Bridged Finance Cross-Chain Routing Engine** coordinates liquidity across isolated blockchains to deliver arbitrary token swaps in a single non-custodial transaction.
---
## 1. The 3-Hop Execution Model
When a user initiates an arbitrary swap (for example, PEPE on Ethereum to SOL on Solana), the protocol breaks the execution down into three interconnected phases:
```
[ Step 1: Source Hop ] [ Step 2: Bridge Transit ] [ Step 3: Destination Hop ]
User Token (PEPE) Transit Asset (USDC) Target Asset (SOL)
| | |
v v v
+------------------+ +-------------------+ +------------------+
| Local DEX Swap | ===========> | Bridged Octopool | ============> | Local DEX Swap |
| (Uniswap v3) | Lock/Burn | & Relayer Network | Mint/Unlock | (Raydium / DEX) |
+------------------+ +-------------------+ +------------------+
Ethereum Mainnet Bridged Relayers Solana Network
```
### Step 1: Source Network Execution
- The user approves and submits the transaction to the `metaRouterGateway` on the source blockchain.
- The `metaRouter` executes a local swap on a top-tier decentralized exchange (such as Uniswap, PancakeSwap, or Curve) to convert the input token into a canonical bridge transit asset (such as USDC or USDT).
- The transit asset is locked in the source `Portal` smart contract.
### Step 2: Relayer Network Attestation
- Decentralized relayer nodes monitor the source `Portal` contract for cross-chain transfer events.
- Nodes verify block depth and finalize cryptographic consensus using a Multi-Party Computation (MPC) Threshold Signature Scheme (TSS).
- The relayers generate an aggregated signature authorizing the release or minting of transit liquidity on the destination network.
### Step 3: Destination Network Delivery
- The destination `Synthesis` / `Bridge` contract validates the relayer signature.
- If the target asset is the transit asset itself, the tokens are transferred directly to the user's wallet.
- If the target asset is another token, the destination `metaRouter` immediately executes a local swap on the destination network's decentralized exchanges and delivers the resulting tokens to the user.
---
## 2. Octopools: Multi-Chain Unified Liquidity
Traditional cross-chain protocols create fragmented liquidity pairs (such as `TokenA-Chain1` paired with `TokenA-Chain2`). This leads to high slippage, capital inefficiency, and frequent liquidity drought.
Bridged Finance solves this with **Octopools**:
- An Octopool is a concentrated AMM liquidity pool holding primary stablecoins and gas tokens across multiple blockchains.
- Virtual representations of assets move efficiently between chains without requiring redundant external liquidity pools for every token pair.
- The AMM utilizes constant-sum and constant-product invariant curves to maximize capital efficiency and provide deep liquidity with minimal price impact.
---
## 3. Relayers Network & Cryptographic Consensus
Cross-chain state transitions are secured by an independent network of relayer nodes:
- **Threshold Signature Scheme (TSS):** No single relayer holds the private key required to authorize destination transactions. A cryptographic quorum (e.g. $t$-of-$n$) must sign together.
- **Slashing & Economic Security:** Malicious behavior or signing of invalid state transitions is mathematically verifiable on-chain and leads to immediate node disqualification.
- **Asynchronous Fault Tolerance:** The relayer network continues processing transactions smoothly even if individual node operators experience network latency or outages.
---
## 4. Safety Failures & Reversion Protections
Cryptocurrency markets can experience rapid volatility during the few minutes a cross-chain swap is in flight. Bridged Finance includes built-in safeguards to ensure user capital is never lost:
- **Slippage Enforcement:** The destination swap enforces a strict `amountOutMin` computed from the user's initial slippage tolerance.
- **Fallback Delivery:** If the final local DEX swap fails (for example, if price impact exceeds the user's maximum slippage), the destination contract **does not revert the bridge operation**. Instead, it transfers the valuable transit token (such as USDC or USDT) directly into the user's destination wallet. The user retains their full capital and can swap it manually at their leisure.
---
## Native Bitcoin Cross-Chain Routing
*Category: Guides & Architecture | Canonical URL: https://bridged.finance/docs/guides/bitcoin-routing*
# Native Bitcoin Cross-Chain Routing
**Bridged Finance** provides genuine, non-custodial swaps to and from **Native Bitcoin (BTC)**. Users can exchange assets on Ethereum, Arbitrum, BNB Chain, Solana, and 50+ other networks directly for real satoshis on the Bitcoin blockchain without relying on synthetic or wrapped representations (such as WBTC, BTCB, or tBTC).
---
## 1. The Challenge of Bitcoin Cross-Chain Interoperability
The Bitcoin network utilizes the Unspent Transaction Output (UTXO) accounting model and lacks a Turing-complete smart contract virtual machine (like the EVM). As a result:
- Bitcoin cannot run automated market maker contracts.
- Smart contracts on EVM chains cannot directly parse Bitcoin blocks without heavy cryptographic verifiers.
Bridged Finance solves this architectural divergence through **Multi-Party Computation (MPC) Threshold Vaults** managed by the decentralized relayer network.
---
## 2. Swapping TO Native Bitcoin (Any -> BTC)
When exchanging any token (such as USDT on BNB Chain or ETH on Arbitrum) for native Bitcoin:
```
[ User Wallet ]
|
| 1. Submit Swap Transaction on Source Chain
v
[ Source MetaRouter ]
|
| 2. Swaps Token to Transit Asset & Locks in Bridge Portal
v
[ Bridged Relayer Network ]
|
| 3. TSS Quorum signs a native Bitcoin release transaction
v
[ Bitcoin Mainnet ]
|
| 4. Native BTC broadcast to recipient's Bitcoin address
v
[ User's Bitcoin Wallet ] (e.g. Ledger, Trezor, Xverse, Unisat)
```
### Supported Bitcoin Address Formats:
The protocol supports all standard Bitcoin address types:
- **Native SegWit (Bech32):** Starts with `bc1q...` (Recommended for lowest transaction fees).
- **Taproot (Bech32m):** Starts with `bc1p...` (Modern, privacy-enhanced).
- **Nested SegWit (P2SH):** Starts with `3...` (Compatible with older wallets).
- **Legacy (P2PKH):** Starts with `1...` (Universal compatibility).
---
## 3. Swapping FROM Native Bitcoin (BTC -> Any)
When swapping native Bitcoin into any destination network (such as BTC -> USDC on Base):
### Step 1: Request Ephemeral Deposit Address
The client application calls `POST /v2/swap`:
- Specifies input asset as `BTC` and input amount.
- Specifies destination network, token, and recipient wallet address.
- The API returns a single-use threshold-managed Bitcoin deposit address (`bc1q...`) along with the guaranteed quote.
### Step 2: Broadcast Bitcoin Transaction
The user sends the exact BTC amount to the returned deposit address from any Bitcoin wallet or centralized exchange account.
### Step 3: Block Confirmation & Fulfillment
- The Bridged relayer network tracks the Bitcoin mempool and monitors the deposit address.
- Once the deposit transaction achieves the required network depth (typically 1 to 2 confirmations on Bitcoin mainnet), the relayer network signs and submits the corresponding destination chain transaction.
- The destination contract dispenses the requested tokens directly to the user's destination wallet.
---
## 4. Key Advantages Over Wrapped Bitcoin Tokens
| Feature | Bridged Native BTC | Wrapped Bitcoin (WBTC, BTCB) |
| :--- | :--- | :--- |
| **Asset Authenticity** | Real, genuine Bitcoin on Bitcoin mainnet | Synthetic ERC-20 / BEP-20 IOU token |
| **Custody Risk** | Decentralized TSS/MPC node network | Centralized custodial merchant (BitGo, etc.) |
| **Wallet Compatibility** | Works with cold storage (Ledger, Trezor, Coldcard) | Confined to EVM Web3 wallet extensions |
| **De-peg Exposure** | Zero de-peg risk (holds real satoshis) | Subject to smart contract and bridge de-pegging |
---
## 5. Settlement Time Expectations
Because transactions on the Bitcoin network depend on Bitcoin's 10-minute block interval:
- **Any -> BTC Swaps:** Typically complete in 5 to 15 minutes.
- **BTC -> Any Swaps:** Typically complete in 20 to 35 minutes (allowing for 1-2 Bitcoin block confirmations plus destination finality).
Users can track the real-time status of their Bitcoin swaps at any time in the [Bridged Explorer](/explorer).
---
## Slippage Tolerance & Distribution
*Category: Guides & Architecture | Canonical URL: https://bridged.finance/docs/guides/slippage-tolerance*
# Slippage Tolerance & Distribution
In decentralized finance, **slippage** is the difference between the expected price of a trade and the actual execution price when the transaction confirms on-chain.
Because cross-chain swaps often involve multiple transaction legs across different blockchains, understanding how slippage tolerance is managed and distributed is critical for reliable execution.
---
## 1. Multi-Leg Slippage Dynamics
A typical cross-chain swap consists of three separate execution legs:
1. **Leg 1: Source Chain Swap:** Input Token -> Transit Asset (e.g. PEPE to USDC on Uniswap).
2. **Leg 2: Cross-Chain Octopool Transit:** Asset transfer through protocol liquidity pools.
3. **Leg 3: Destination Chain Swap:** Transit Asset -> Target Token (e.g. USDC to SOL on Raydium).
During the minutes between the source transaction confirmation and destination fulfillment, market volatility on the destination DEX can shift pool ratios.
To safeguard the user's principal, the Bridged Finance routing engine algorithmically **distributes** the overall slippage budget across these legs:
```
Total User Slippage Budget (e.g. 1.0%)
|
+----------+----------+
| |
v v
Source Leg (0.3%) Destination Leg (0.7%)
```
---
## 2. Recommended Slippage Configurations
When submitting quotes to the API via the `slippage` parameter (specified in basis points, where `100 = 1.0%`):
| Asset Pair Category | Recommended Slippage | Parameter Value |
| :--- | :--- | :--- |
| **Stablecoin to Stablecoin** (e.g. USDC -> USDT) | `0.3%` to `0.5%` | `30` - `50` |
| **Major Gas Assets** (e.g. ETH -> BNB, SOL -> AVAX) | `0.5%` to `1.0%` | `50` - `100` |
| **Volatile or Low-Liquidity Tokens** (e.g. Memecoins) | `1.5%` to `3.0%` | `150` - `300` |
| **Congested Network Periods** | `1.0%` to `2.0%` | `100` - `200` |
---
## 3. The Minimum Output (amountOutMin) Protection Invariant
Every quote generated by `POST /v2/quote` calculates a deterministic minimum output:
$$\text{amountOutMin} = \text{amountOut} \times \left(1 - \frac{\text{slippage}}{10000}\right)$$
This minimum output value is cryptographically encoded directly into the destination execution calldata. If the destination DEX pool price has moved adversely such that the trade would return fewer tokens than `amountOutMin`, the smart contract strictly **refuses** to execute the bad trade.
---
## 4. Mitigating Transit Token Outcomes
If a destination DEX swap cannot be fulfilled due to a slippage breach or sudden pool imbalance:
### The Problem With Traditional Bridges:
Many bridges revert the entire cross-chain transaction, stranding funds in cross-chain limbo or requiring complex manual refund claims with high gas penalties.
### The Bridged Finance Solution:
The Bridged protocol implements an automated **safe-landing mechanism**:
- Instead of reverting, the destination smart contract detects the DEX failure.
- The contract automatically deposits the valuable **transit asset** (such as USDC, USDT, or native gas token) directly into the user's destination wallet.
- The user retains 100% of their capital, which arrived safely on the target network.
- The user can then swap the transit asset into their desired target token whenever liquidity normalizes, or bridge it elsewhere.
---
## Security Audits & Threat Model
*Category: Guides & Architecture | Canonical URL: https://bridged.finance/docs/guides/security-and-audits*
# Security Audits & Threat Model
Security is the foremost design requirement of **Bridged Finance**. The protocol combines multi-firm external audits, formal contract verification, and multi-party computation to protect user liquidity.
---
## 1. Third-Party Security Audits
The underlying cross-chain smart contract architecture and relayer cryptography have been audited by premier Web3 cybersecurity firms:
| Security Auditor | Audit Scope | Result |
| :--- | :--- | :--- |
| **Zokyo** | Core Cross-Chain Smart Contracts, Portal, Synthesis | Verified & Passed |
| **Omniscia** | MetaRouter, MetaRouterGateway, MulticallRouter | Verified & Passed |
| **SlowMist** | Cross-Chain Relayer Consensus & MPC TSS Mechanics | Verified & Passed |
| **Hacken** | Octopool AMM Liquidity Contracts & Math Invariants | Verified & Passed |
---
## 2. Threat Modeling & Attack Mitigations
### 1. Flash Loan & Oracle Manipulation Attacks
- **Vulnerability:** Attackers use flash loans to artificially distort automated market maker pool ratios within a single transaction block.
- **Mitigation:** The Bridged routing engine utilizes off-chain consensus price validation combined with Time-Weighted Average Price (TWAP) and decentralized liquidity depth filters. Cross-chain fulfillment transactions are verified across independent blocks, preventing intra-block single-transaction manipulation.
### 2. MEV & Front-Running / Sandwich Attacks
- **Vulnerability:** Searchers on public mempools observe large cross-chain swap transactions and attempt to sandwich the trades on source or destination decentralized exchanges.
- **Mitigation:** Calldata generated by `POST /v2/quote` enforces strict `amountOutMin` boundaries calculated directly from the user's slippage settings. Any transaction that would suffer an adverse price movement beyond the threshold is automatically blocked.
### 3. Reentrancy Exploits
- **Vulnerability:** Malicious recipient smart contracts attempt to re-enter bridge routing contracts during external token transfer calls.
- **Mitigation:** All state-modifying functions across the `metaRouter`, `metaRouterGateway`, and bridge contracts adhere to the Checks-Effects-Interactions pattern and are secured by non-reentrant mutex locks (`ReentrancyGuard`).
### 4. Relayer Key Compromise
- **Vulnerability:** An attacker gains access to an individual relayer node operator.
- **Mitigation:** Relayers operate using a distributed Threshold Signature Scheme (TSS). No individual node ever possesses the master signing key. Authorizing any cross-chain mint or transfer requires simultaneous cryptographic consensus from a supermajority of independent nodes.
---
## 3. Core Protocol Invariants
The protocol maintains five uncompromised invariants:
1. **Non-Custodial Guarantee:** Smart contracts never grant administrators or operators discretionary withdrawal rights over user assets in flight.
2. **Deterministic Output Bounds:** Transactions cannot execute on the destination network for an amount less than `amountOutMin`.
3. **Segregated Allowance Scope:** Users grant ERC-20 allowances solely to `metaRouterGateway`. Core bridge proxies and DEX routing contracts never request open user approvals.
4. **Transit Asset Preservation:** If destination market conditions prevent execution of the target DEX swap, the user is directly credited with the bridge transit asset. User capital is never burned or abandoned.
5. **Real-Time Verifiability:** Every transaction leg, proof, and relayer confirmation is fully visible on public block explorers and the [Bridged Explorer](/explorer).
---
## Smart Contract Registry
*Category: Guides & Architecture | Canonical URL: https://bridged.finance/docs/guides/contract-registry*
# Smart Contract Registry
This registry provides the authoritative smart contract addresses deployed across all supported EVM blockchains.
---
## 1. Gateway & Router Architecture
On EVM-compatible networks, the protocol utilizes deterministic `CREATE2` factory deployments to maintain consistent contract addresses across chains:
- **`metaRouterGateway`**: The single contract that user wallets approve to spend ERC-20 tokens.
- **`metaRouter`**: Internal routing contract that aggregates local decentralized exchanges and prepares bridge payloads.
- **`bridge`**: The proxy contract through which liquidity is locked, burned, or minted under relayer consensus.
---
## 2. Verified Contract Addresses Across Major Networks
| Blockchain | Chain ID | `metaRouterGateway` (User Approval Target) | Native Currency | Explorer |
| :--- | :--- | :--- | :--- | :--- |
| **Ethereum Mainnet** | `1` | `0x444b7D47385942f9b23b49e17b8f05CE8a176214` | ETH | [Etherscan](https://etherscan.io) |
| **BNB Smart Chain** | `56` | `0x444b7D47385942f9b23b49e17b8f05CE8a176214` | BNB | [BscScan](https://bscscan.com) |
| **Arbitrum One** | `42161` | `0x444b7D47385942f9b23b49e17b8f05CE8a176214` | ETH | [Arbiscan](https://arbiscan.io) |
| **Base** | `8453` | `0x444b7D47385942f9b23b49e17b8f05CE8a176214` | ETH | [Basescan](https://basescan.org) |
| **Polygon PoS** | `137` | `0x444b7D47385942f9b23b49e17b8f05CE8a176214` | POL / MATIC | [PolygonScan](https://polygonscan.com) |
| **Optimism (OP Mainnet)** | `10` | `0x444b7D47385942f9b23b49e17b8f05CE8a176214` | ETH | [Optimistic Etherscan](https://optimistic.etherscan.io) |
| **Avalanche C-Chain** | `43114` | `0x444b7D47385942f9b23b49e17b8f05CE8a176214` | AVAX | [Snowtrace](https://snowtrace.io) |
| **Linea** | `59144` | `0x444b7D47385942f9b23b49e17b8f05CE8a176214` | ETH | [Lineascan](https://lineascan.build) |
| **Scroll** | `534352` | `0x444b7D47385942f9b23b49e17b8f05CE8a176214` | ETH | [Scrollscan](https://scrollscan.com) |
| **zkSync Era** | `324` | `0x444b7D47385942f9b23b49e17b8f05CE8a176214` | ETH | [zkSync Explorer](https://explorer.zksync.io) |
| **Blast** | `81457` | `0x444b7D47385942f9b23b49e17b8f05CE8a176214` | ETH | [Blastscan](https://blastscan.io) |
| **Manta Pacific** | `169` | `0x444b7D47385942f9b23b49e17b8f05CE8a176214` | ETH | [Manta Explorer](https://pacific-explorer.manta.network) |
| **Berachain** | `80094` | `0x444b7D47385942f9b23b49e17b8f05CE8a176214` | BERA | [Berascan](https://berascan.com) |
| **Sonic** | `146` | `0x444b7D47385942f9b23b49e17b8f05CE8a176214` | S | [Sonicscan](https://sonicscan.org) |
| **Mantle** | `5000` | `0x444b7D47385942f9b23b49e17b8f05CE8a176214` | MNT | [Mantlescan](https://mantlescan.info) |
| **Gnosis Chain** | `100` | `0x444b7D47385942f9b23b49e17b8f05CE8a176214` | xDAI | [Gnosisscan](https://gnosisscan.io) |
| **Rootstock (RSK)** | `30` | `0x444b7D47385942f9b23b49e17b8f05CE8a176214` | RBTC | [RSK Explorer](https://explorer.rootstock.io) |
| **Taiko** | `167000` | `0x444b7D47385942f9b23b49e17b8f05CE8a176214` | ETH | [Taikoscan](https://taikoscan.io) |
---
## 3. Verifying Contracts On-Chain
To verify that a contract is genuine and active:
1. Open the corresponding block explorer link from the table above.
2. Search for the contract address: `0x444b7D47385942f9b23b49e17b8f05CE8a176214`.
3. Switch to the **Contract** tab.
4. Verify that the contract code is verified and matches the published open-source bytecode.
---
## 4. Planned In-App Features
A live, queryable Contract Explorer page at `/contracts` is currently in development to allow developers to query live balances, fee collector addresses, and contract parameters directly from the Bridged interface.
---
## Frequently Asked Questions (FAQ)
*Category: Support & FAQ | Canonical URL: https://bridged.finance/docs/faq/general-faq*
# Frequently Asked Questions (FAQ)
Find answers to common questions about using and integrating the **Bridged Finance** cross-chain protocol.
---
## General Protocol Questions
### What is Bridged Finance?
Bridged Finance is a non-custodial cross-chain interoperability protocol and decentralized application. It enables instant, any-to-any asset swaps across 57+ blockchains and thousands of cryptocurrency tokens without intermediaries or wrapped IOUs.
### Is Bridged Finance non-custodial?
Yes. The protocol is 100% non-custodial. At no point do operators, servers, or relayers hold private keys or have discretionary access to your funds. Swaps execute automatically via smart contracts and a decentralized threshold-signature relayer network.
### Do I need to create an account or complete KYC?
No. Bridged Finance is completely permissionless. There are no accounts, email requirements, or KYC verification steps. You connect your standard Web3 wallet (or submit requests directly via the REST API) to execute swaps immediately.
### Which wallets are supported?
The Bridged DApp supports all major Web3 wallet providers via EIP-1193 and EIP-6963 standards, including MetaMask, Rabby, Coinbase Wallet, Trust Wallet, Phantom (Solana), TronLink (TRON), and hardware wallets (Ledger, Trezor).
---
## Cross-Chain Swaps & Execution
### How long does a cross-chain swap take?
Settlement times depend primarily on the block confirmation times of the source and destination blockchains:
- **EVM to EVM (e.g. Arbitrum to Base):** 1 to 3 minutes.
- **EVM to High-Speed Chains (e.g. Solana / TRON):** 1 to 4 minutes.
- **Swaps involving Bitcoin (Any to BTC):** 5 to 15 minutes.
- **Swaps from Bitcoin (BTC to Any):** 20 to 35 minutes (allowing for 1-2 Bitcoin mainnet confirmations).
You can monitor the status of any transaction in real-time in the [Bridged Explorer](/explorer).
### What fees are charged?
There are two primary components in cross-chain swap fees:
1. **Network Gas Fee:** The gas cost required on the destination blockchain to deliver your tokens to your wallet. This is paid by the relayer network and deducted directly from the swap amount.
2. **Protocol Liquidity Fee:** A minimal fee (typically 0.1% or lower) that maintains liquidity depth in the protocol's Octopools.
All fees and expected received amounts are displayed transparently before you confirm any transaction.
### What happens if market volatility causes a slippage breach?
If liquidity pool prices on the destination decentralized exchange move beyond your configured slippage tolerance during the swap's transit:
- The destination contract **does not burn or lose your funds**.
- It halts the unfavorable DEX trade and immediately deposits the high-value **transit asset** (such as USDC or USDT) directly into your destination wallet.
- You keep your full principal and can swap or transfer it at your discretion.
### Where can I track my transactions?
Open the [Bridged Explorer](/explorer) and enter your transaction hash, wallet address, or token symbol to view live status updates, confirmations, and transaction proofs.
---
## Error Codes & Status Resolution
*Category: Support & FAQ | Canonical URL: https://bridged.finance/docs/faq/error-codes-and-status*
# Error Codes & Status Resolution
This guide provides error diagnostics, resolution steps, and status interpretations for integrating the **Bridged Finance API**.
---
## 1. HTTP Status Codes
| Code | Meaning | Typical Cause |
| :--- | :--- | :--- |
| `200 OK` | Success | The quote, swap parameters, or status payload was successfully generated. |
| `400 Bad Request` | Invalid Parameters | Missing required fields, unparsable addresses, or negative amounts. |
| `404 Not Found` | Resource Missing | Token, network ID, or transaction hash not indexed by the protocol. |
| `422 Unprocessable` | Route Unavailable | Liquidity depth insufficient for the requested amount, or limits breached. |
| `500 Server Error` | Node Failure | Upstream blockchain RPC timeout or node synchronization delay. |
---
## 2. Common API Error Responses
### 1. AMOUNT_TOO_LOW / SWAP_LIMIT_MIN
- **Cause:** The swap amount submitted is smaller than the minimum viable threshold required to cover destination gas fees.
- **Resolution:** Check minimum swap limits using `GET /v1/swap-limits` and ensure `tokenAmountIn.amount` meets the threshold.
### 2. NO_ROUTE_FOUND
- **Cause:** No decentralized exchange pool exists with sufficient liquidity between the requested tokens on either the source or destination chain.
- **Resolution:** Try swapping to a canonical stablecoin (USDC or USDT) first, or split the swap into smaller chunks.
### 3. INVALID_RECIPIENT_ADDRESS
- **Cause:** The `to` address fails cryptographic checksum or format validation for the selected destination chain (e.g. passing an EVM `0x...` address when bridging to Solana or Bitcoin).
- **Resolution:** Verify address format according to [Token Address Formats](/api/token-address-formats) before invoking `/v2/quote`.
### 4. SLIPPAGE_TOO_LOW
- **Cause:** The requested `slippage` parameter is too restrictive for the price volatility of the pair, causing simulated execution failure.
- **Resolution:** Increase slippage tolerance (e.g. from `50` to `100` or `150` basis points).
---
## 3. Transaction Status Meanings
When polling `GET /v2/tx/{chainId}/{txHash}`:
| Status Value | Meaning | Next Step |
| :--- | :--- | :--- |
| `pending` | Source transaction broadcast | Wait for additional block confirmations on the source blockchain. |
| `in-progress` | Relayers attesting | Relayers have verified source event logs and are dispatching destination transaction. |
| `success` | Complete | Tokens have arrived at the recipient wallet. Transaction is finalized. |
| `reverted` | Leg Reverted | Check if safe-landing transit token was delivered to the recipient address. |
---
## 4. Diagnosing In-Flight Swaps
If a transaction takes longer than estimated:
1. **Verify Source Confirmation:** Check the source blockchain explorer (e.g. Etherscan, Arbiscan, BscScan) to ensure the initial transaction did not run out of gas or revert locally.
2. **Inspect Bridged Explorer:** Enter your transaction hash in [Bridged Explorer](/explorer) to see which step of the transfer is currently executing.
3. **Check Wallet Balance:** If the transaction has completed with a status of `reverted`, inspect your destination wallet for the transit asset (USDC or USDT) which was delivered as a protective fallback.
---