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

# Making a bridge & swap

> This guide walks you through integrating our bridge API into your application. By following these steps, you’ll be able to transfer and swap assets between chains using our API and smart contract interactions.

## Quickstart

The whole process consists of:

<Steps>
  <Step title="Authentication">
    Get a JWT to authenticate your requests.
  </Step>

  <Step title="Fetching bridge configs">
    Retrieve supported chains and tokens.
  </Step>

  <Step title="Getting a quote">
    Obtain transaction details, including fees.
  </Step>

  <Step title="Committing the quote">
    Confirm the transaction.
  </Step>

  <Step title="Executing the bridge transaction">
    Interact with the smart contract to complete the transfer.
  </Step>
</Steps>

***

### 1. Authentication

All non-public API endpoints are authenticated using a JSON Web Token. To authenticate your requests, include the token in the `Authorization` header. [Learn about API authentication](/api-integration/authentication).

### 2. Fetch Bridge Configs

Retrieve available chains to ensure your transaction uses the correct parameters.

```javascript getBridgeConfigs.js theme={null}
export const getBridgeConfigs = async () => {
  const request = await fetch('https://api.rhino.fi/bridge/configs')
  return request.json()
}
```

For the exact response format and more details, see the [API Reference](/api-reference/configs).

### 3. Fetch Swap token config

Retrieve available tokens for swap transactions.

```javascript theme={null}
export const getSwapTokenConfig = async () => {
  const request = await fetch('https://api.rhino.fi/bridge/bridge-swap-token-configs')
  return request.json()
}
```

For the exact response format and more details, see the [API Reference](/api-reference/configs/get-all-token-configs-for-bridge-and-swap).

### 4. Get a Bridge & Swap Quote

Before executing a bridge transaction, you must generate a quote that provides transaction details, including fees and amounts.

```javascript getBridgeSwapUserQuote.js theme={null}
export const getBridgeSwapUserQuote = async (payload, jwt) => {
  const request = await fetch(`https://api.rhino.fi/bridge/quote/bridge-swap/user`, {
    headers: {
      "content-type": "application/json",
      "authorization": jwt
    },
    method: "POST",
    body: JSON.stringify(payload)
  })

  return request.json()
}

```

For the exact request / response format and more details, see the [API Reference](/api-reference/quote/user-quote-for-bridge-&-swap).

### 5. Commit the Quote

Once you have a quote, you must commit it to confirm the transaction before execution.

```javascript commitBridgeSwapUserQuote.js theme={null}
export const commitBridgeSwapUserQuote = async (quoteId, jwt) => {
  const request = await fetch(`https://api.rhino.fi/bridge/quote/commit/${quoteId}`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'authorization': jwt
    }
  })

  return request.json()
}
```

For the exact request / response format and more details, see the [API Reference](/api-reference/quote/commit-quote).

### 6. Execute the Bridge & Swap Transaction

Now, you can execute the bridge transaction by interacting with the smart contract.

See [examples](/contracts/contract-examples) for interacting with the bridge smart contracts across different blockchain environments.

### 7. Full Example

Here’s the complete implementation combining all the steps above:

```javascript index.js theme={null}
import { getBridgeSwapUserQuote } from "./getBridgeSwapUserQuote";
import { getBridgeConfigs } from "./getBridgeConfigs";
import { getSwapTokenConfig } from "./getSwapTokenConfig";
import { commitBridgeSwapUserQuote } from "./commitBridgeSwapUserQuote";

const JWT = 'YOUR_JWT'; // Replace with your JWT generated from our API

const amount = '1';
const chainIn = 'BASE';
const chainOut = 'ARBITRUM';
const tokenIn = 'USDT';
const tokenOut = 'USDC';
const depositorAddress = '0x0000000000000000000000000000000000000000'; // Replace with your depositor address
const recipientAddress = '0x0000000000000000000000000000000000000000'; // Replace with your recipient address

const bridgeAndSwap = async () => {
  // Get bridge configs to determine supported chains and tokens or later use for the contract call
  const configs = await getBridgeConfigs();
  const swapTokenConfig = await getSwapTokenConfig();

  // Get a bridge quote for the transaction
  const quote = await getBridgeSwapUserQuote({
    amount,
    chainIn,
    chainOut,
    tokenIn,
    tokenOut,
    mode: 'pay',
    depositor: depositorAddress,
    recipient: recipientAddress,
    amountNative: '0'
  }, JWT);

  if (!quote?.quoteId) throw new Error('Failed to generate user quote.');

  // Commit the quote to confirm the transaction when you are ready to send on-chain
  const commitResult = await commitBridgeSwapUserQuote(quote.quoteId, JWT);

  if (!commitResult?.quoteId) throw new Error('Failed to commit user quote.');

  const chainConfig = configs[chainIn];
  const swapConfig = swapTokenConfig[chainIn][tokenIn];

  // Execute the bridge transaction by interacting with the smart contract -- see contract examples section on exact implementation
  await callBridgeContract({
    chainConfig,
    swapConfig,
    amount: quote.payAmount,
    tokenIn,
    commitmentId: commitResult.quoteId,
    callback: (hash) => console.info('Transaction hash:', hash)
  });
};

bridgeAndSwap();
```

For a detailed breakdown of API endpoints and parameters, check the [API Reference](/api-reference/introduction).

## Same-chain swaps

When `chainIn === chainOut`, the quote response is flagged as an **atomic same-chain swap** (`isAtomicSwap: true`). These go through a separate contract and a different transaction format than a regular bridge deposit — broadcasting a `depositWithId` / `depositNativeWithId` for an atomic same-chain swap commitment will be rejected by the deposit watcher.

Same-chain swaps are **EVM-only**.

The flow is identical up to step 5 (commit), then diverges:

### Detect the case

After fetching the quote in step 4, check the response:

```javascript theme={null}
const isSameChainSwap =
  quote.chainIn === quote.chainOut && quote.isAtomicSwap === true
```

### Use a different approval target

For ERC-20 same-chain swaps, the approval target is the chain's `sameChainSwapsAddress` (returned in `GET /bridge/configs` under the chain entry) — **not** the regular `contractAddress`. Native-token swaps don't require an approval.

### Fetch the swap calldata instead of building a deposit tx

Instead of calling the deposit contract, fetch the prepared calldata. The `commitmentId` is the `quoteId` you committed.

```javascript getSwapCalldata.js theme={null}
export const getSwapCalldata = async (commitmentId, jwt) => {
  const request = await fetch(`https://api.rhino.fi/bridge/swap/calldata/${commitmentId}`, {
    headers: { 'authorization': jwt }
  })

  return request.json()
}
```

The response contains a JSON-stringified transaction object:

```json theme={null}
{
  "calldata": "{\"to\":\"0x...\",\"data\":\"0x...\",\"value\":\"...\"}"
}
```

Parse it and submit it as a raw EVM transaction from the depositor wallet:

<CodeGroup>
  ```javascript ethers theme={null}
  import { ethers } from 'ethers'

  const { calldata } = await getSwapCalldata(commitResult.quoteId, JWT)
  const { to, data, value } = JSON.parse(calldata)

  const tx = await wallet.sendTransaction({ to, data, value: BigInt(value ?? 0) })
  await tx.wait()
  ```

  ```javascript viem theme={null}
  const { calldata } = await getSwapCalldata(commitResult.quoteId, JWT)
  const { to, data, value } = JSON.parse(calldata)

  const hash = await walletClient.sendTransaction({ to, data, value: BigInt(value ?? 0) })
  await publicClient.waitForTransactionReceipt({ hash })
  ```
</CodeGroup>

<Warning>
  Do **not** call `depositWithId` / `depositNativeWithId` on the regular deposit contract for same-chain swaps.
</Warning>

## Next steps

For the smart contract integration see - [contract examples](/contracts/contract-examples)

To track your bridge transaction status, see [Bridge Status & History](/api-integration/status-history).