> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cow.bleu.builders/llms.txt
> Use this file to discover all available pages before exploring further.

# Cross-Chain Bridging

> Enable seamless token transfers across different blockchain networks using the CoW Protocol SDK

# Cross-Chain Bridging

The CoW Protocol SDK provides seamless cross-chain token transfers through integration with multiple bridge providers. This enables you to swap tokens across different blockchain networks in a single transaction.

## Installation

```bash theme={null}
npm install @cowprotocol/sdk-bridging
```

## Basic Usage

### Initialize the BridgingSdk

<CodeGroup>
  ```typescript Standalone theme={null}
  import {
    SupportedChainId,
    BridgingSdk,
    QuoteBridgeRequest,
    OrderKind,
    assertIsBridgeQuoteAndPost,
  } from '@cowprotocol/sdk-bridging'
  import { EthersV6Adapter } from '@cowprotocol/sdk-ethers-v6-adapter'
  import { JsonRpcProvider, Wallet } from 'ethers'

  // Configure the adapter
  const provider = new JsonRpcProvider('YOUR_RPC_URL')
  const wallet = new Wallet('YOUR_PRIVATE_KEY', provider)
  const adapter = new EthersV6Adapter({ provider, signer: wallet })

  // Initialize bridging SDK
  const bridging = new BridgingSdk(adapter, options)
  ```

  ```typescript With CoW SDK theme={null}
  import {
    CowSdk,
    SupportedChainId,
    QuoteBridgeRequest,
    OrderKind,
    assertIsBridgeQuoteAndPost,
  } from '@cowprotocol/cow-sdk'
  import { EthersV6Adapter } from '@cowprotocol/sdk-ethers-v6-adapter'
  import { JsonRpcProvider, Wallet } from 'ethers'

  // Configure the adapter
  const provider = new JsonRpcProvider('YOUR_RPC_URL')
  const wallet = new Wallet('YOUR_PRIVATE_KEY', provider)
  const adapter = new EthersV6Adapter({ provider, signer: wallet })

  // Initialize the unified SDK
  const sdk = new CowSdk({
    chainId: SupportedChainId.ARBITRUM_ONE, // Source chain
    adapter,
  })
  ```
</CodeGroup>

### Get a Cross-Chain Quote

```typescript theme={null}
const parameters: QuoteBridgeRequest = {
  // Cross-chain orders are always SELL orders (BUY not supported yet)
  kind: OrderKind.SELL,

  // Sell token (and source chain)
  sellTokenChainId: SupportedChainId.ARBITRUM_ONE,
  sellTokenAddress: '0xfff9976782d46cc05630d1f6ebab18b2324d6b14',
  sellTokenDecimals: 18,

  // Buy token (and target chain)
  buyTokenChainId: SupportedChainId.BASE,
  buyTokenAddress: '0x0625afb445c3b6b7b929342a04a22599fd5dbb59',
  buyTokenDecimals: 18,

  // Amount to sell
  amount: '120000000000000000',

  signer: adapter.signer,

  // Optional parameters
  appCode: 'YOUR_APP_CODE',
}

// Get a quote (and the post callback) for a cross-chain swap
const quoteResult = await sdk.getQuote(parameters)
// Assert that the quote result is of type BridgeQuoteAndPost
// (type for cross-chain quotes, as opposed to QuoteAndPost for single-chain quotes).
assertIsBridgeQuoteAndPost(quoteResult)
const { swap, bridge, postSwapOrderFromQuote } = quoteResult

// Display all data related to the swap (costs, amounts, appData including the bridging hook, etc.)
console.log('Swap info', swap)

// Display all data related to the bridge (costs, amounts, provider info, hook, and the bridging quote)
console.log('Bridge info', bridge)

// Get the buy amount after slippage in the target chain
const { buyAmount } = bridge.amountsAndCosts.afterSlippage

if (confirm(`You will get at least: ${buyAmount}, ok?`)) {
  const orderId = await postSwapOrderFromQuote()
  console.log('Order created, id: ', orderId)
}
```

<Info>
  Cross-chain orders are always SELL orders. BUY orders are not yet supported for cross-chain swaps.
</Info>

## Multi-Provider Quotes

### Get Quotes from All Providers

The `getMultiQuotes()` method allows you to get quotes from multiple bridge providers simultaneously:

```typescript theme={null}
import { MultiQuoteRequest } from '@cowprotocol/sdk-bridging'

const multiQuoteRequest: MultiQuoteRequest = {
  quoteBridgeRequest: parameters, // Same parameters as above
  providerDappIds: ['provider1', 'provider2'], // Optional: specify which providers to query
  advancedSettings: {
    slippageBps: 100, // 1% slippage tolerance
  },
  options: {
    totalTimeout: 15000,        // 15 seconds total timeout
    providerTimeout: 8000, // 8 seconds per provider timeout
  }
}

// Get quotes from all providers
const results = await bridgingSdk.getMultiQuotes(multiQuoteRequest)

results.forEach((result) => {
  if (result.quote) {
    console.log(`Quote from ${result.providerDappId}:`, result.quote)
  } else {
    console.log(`Error from ${result.providerDappId}:`, result.error?.message)
  }
})
```

### Progressive Quote Results

Receive quotes progressively as each provider responds:

```typescript theme={null}
const progressiveResults: MultiQuoteResult[] = []

const multiQuoteRequest: MultiQuoteRequest = {
  quoteBridgeRequest: parameters,
  options: {
    // Receive quotes as they arrive
    onQuoteResult: (result) => {
      progressiveResults.push(result)

      if (result.quote) {
        console.log(`✅ Quote received from ${result.providerDappId}`)
        // Update UI immediately with the new quote
        displayQuoteInUI(result)
      } else {
        console.log(`❌ Error from ${result.providerDappId}: ${result.error?.message}`)
      }
    },
    totalTimeout: 20000,       // 20 seconds total timeout
    providerTimeout: 5000 // 5 seconds per provider timeout
  }
}

// This will return all results once completed (or timed out)
const finalResults = await bridgingSdk.getMultiQuotes(multiQuoteRequest)

console.log(`Received ${finalResults.filter(r => r.quote).length} successful quotes out of ${finalResults.length} providers`)
```

## Best Quote Selection

Use `getBestQuote()` to get only the best quote from all available providers:

```typescript theme={null}
// Get the best quote from all available providers
const bestQuote = await bridgingSdk.getBestQuote({
  quoteBridgeRequest: parameters,
  providerDappIds: ['provider1', 'provider2'], // Optional: specify which providers to query
  advancedSettings: {
    slippageBps: 100, // 1% slippage tolerance
  },
  options: {
    totalTimeout: 15000,       // 15 seconds total timeout
    providerTimeout: 8000,     // 8 seconds per provider timeout
  }
})

if (bestQuote?.quote) {
  console.log(`Best quote from ${bestQuote.providerDappId}:`, bestQuote.quote)
  const { buyAmount } = bestQuote.quote.bridge.amountsAndCosts.afterSlippage
  console.log(`You will receive: ${buyAmount} tokens`)
} else if (bestQuote?.error) {
  console.log('All providers failed, first error:', bestQuote.error.message)
}
```

### Progressive Best Quote Updates

```typescript theme={null}
let currentBest: MultiQuoteResult | null = null

const bestQuote = await bridgingSdk.getBestQuote({
  quoteBridgeRequest: parameters,
  options: {
    // Called whenever a better quote is found
    onQuoteResult: (result) => {
      currentBest = result
      console.log(`🚀 New best quote from ${result.providerDappId}!`)

      if (result.quote) {
        const buyAmount = result.quote.bridge.amountsAndCosts.afterSlippage.buyAmount
        console.log(`Better quote found: ${buyAmount} tokens`)

        // Update UI immediately with the new best quote
        updateBestQuoteInUI(result)
      }
    },
    totalTimeout: 20000,      // 20 seconds total timeout
    providerTimeout: 5000     // 5 seconds per provider timeout
  }
})

console.log('Final best quote:', bestQuote)
```

<Tip>
  Use `getBestQuote()` when you only need the single best quote. Use `getMultiQuotes()` when you need to display all available options to users.
</Tip>

## Provider Management

### Get Available Providers

```typescript theme={null}
// Get all active providers
const providers = bridgingSdk.getAvailableProviders()

providers.forEach((provider) => {
  console.log(`Provider: ${provider.info.name}`)
  console.log(`Dapp ID: ${provider.info.dappId}`)
  console.log(`Networks: ${provider.info.supportedChains.join(', ')}`)
})
```

### Filter Active Providers

```typescript theme={null}
// Initially, all configured providers are available
const allProviders = bridgingSdk.getAvailableProviders()
console.log(`Total providers: ${allProviders.length}`)

// Filter to use only specific providers
bridgingSdk.setAvailableProviders(['across', 'hop-protocol'])

// Now only the specified providers will be used
const filteredProviders = bridgingSdk.getAvailableProviders()
console.log(`Active providers: ${filteredProviders.length}`)

// Reset to use all providers again
bridgingSdk.setAvailableProviders([])
const resetProviders = bridgingSdk.getAvailableProviders()
console.log(`Reset to all providers: ${resetProviders.length}`)
```

## Timeout Configuration

The multi-quote methods support two types of timeouts:

```typescript theme={null}
const results = await bridgingSdk.getMultiQuotes({
  quoteBridgeRequest: parameters,
  options: {
    // Global timeout: Maximum time to wait for all providers to complete
    totalTimeout: 30000,        // 30 seconds (default)

    // Individual provider timeout: Maximum time each provider has to respond
    providerTimeout: 15000, // 15 seconds (default)

    onQuoteResult: (result) => {
      // Handle progressive results
      console.log(`Received result from ${result.providerDappId}`);
    }
  }
});
```

**How timeouts work:**

* `providerTimeout`: Each provider has this amount of time to complete their quote request. If exceeded, that provider returns a timeout error.
* `totalTimeout`: The total time to wait for all providers. After this time, any remaining providers are marked as timed out.
* Providers that complete within their individual timeout but after the global timeout will still be included in the final results.

## Comparison Table

| Feature                   | `getBestQuote()`                  | `getMultiQuotes()`                   |
| ------------------------- | --------------------------------- | ------------------------------------ |
| **Returns**               | Single best result                | Array of all results                 |
| **Progressive Callbacks** | Only for better quotes            | For all results (success & error)    |
| **Error Handling**        | Returns first error if all fail   | Returns all errors in array          |
| **Performance**           | Optimized for best result only    | Returns complete data set            |
| **Use Case**              | When you only need the best quote | When you need to compare all options |

## Error Handling

```typescript theme={null}
try {
  const quoteResult = await bridgingSdk.getQuote(parameters)
  assertIsBridgeQuoteAndPost(quoteResult)
  const { swap, bridge, postSwapOrderFromQuote } = quoteResult

  // Post the order
  const orderId = await postSwapOrderFromQuote()
  console.log('Order created:', orderId)
} catch (error) {
  if (error.message.includes('No available providers')) {
    console.error('No bridge providers available for this route')
  } else if (error.message.includes('timeout')) {
    console.error('Quote request timed out')
  } else {
    console.error('Failed to get cross-chain quote:', error)
  }
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Programmatic Orders" icon="code" href="/cow-sdk/advanced/programmatic-orders">
    Learn about conditional and composable orders
  </Card>

  <Card title="Hooks" icon="webhook" href="/cow-sdk/advanced/hooks">
    Execute custom logic before and after orders
  </Card>
</CardGroup>