Swap & Bridge

In a nutshell
Blockradar’s Swap API lets you exchange assets on the same chain (swap) or move assets between different chains (bridge) using a single unified endpoint.

Prerequisites

Before using the Swap API, ensure you have:

API Key

Get your API key from the Blockradar Dashboard. Navigate to Developers to generate one.

Wallet Created

Create a wallet via the Create Wallet API or dashboard. You’ll need the walletId for swap operations.

Asset IDs

Get the assetId for your source and destination assets from Assets in the dashboard or via the Get Assets API.

Sufficient Balance

Ensure your wallet has enough balance of the source asset to cover the swap amount plus network fees.

How It Works

Blockradar automatically determines whether your transaction is a swap or a bridge based on your asset selection:

Swap

Exchange different assets on the same blockchain.Example: USDC → USDT on Base

Bridge

Move assets between different blockchains.Example: USDC on BSC → USDC on Optimism

You don’t need to specify whether it’s a swap or bridge—the API handles this automatically based on the fromAssetId and toAssetId you provide.

Supported Assets & Chains

The Swap API supports major stablecoins across Blockradar-supported chains:

Stablecoin	Description
USDT	Tether USD
USDC	USD Coin
DAI	Dai Stablecoin
BUSD	Binance USD
cNGN	Naira Stablecoin
EURC	Euro Coin
IDRX	Indonesian Stablecoin
JPYC	Japanese Yen Stablecoin

Asset availability varies by chain. Always use the Get Assets API to fetch the current list of supported assets and their assetId values for your target chains.

See Integrations for the complete list of supported networks and stablecoins.

Master Wallet vs Child Address

The Swap API is available at two levels:

Master Wallet

Execute swaps directly from your master wallet. Ideal for treasury operations.

Child Address

Execute swaps from individual child addresses. Perfect for user-specific operations.

Endpoints

Operation	Master Wallet	Child Address
Get Quote	`POST /v1/wallets/{walletId}/swaps/quote`	`POST /v1/wallets/{walletId}/addresses/{addressId}/swaps/quote`
Execute	`POST /v1/wallets/{walletId}/swaps/execute`	`POST /v1/wallets/{walletId}/addresses/{addressId}/swaps/execute`

Step 1: Get a Quote

Always fetch a quote before executing a swap to show users the expected outcome.

Request Parameters

Parameter	Type	Required	Description
`fromAssetId`	string	Yes	The asset ID to swap from
`toAssetId`	string	Yes	The asset ID to swap to
`amount`	string	Yes	The amount to swap
`order`	string	No	Quote preference: `FASTEST`, `CHEAPEST`, `RECOMMENDED`, `NO_SLIPPAGE`
`recipientAddress`	string	No	External wallet address (for sending to non-Blockradar wallets)

Quote Example

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/swaps/quote \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "fromAssetId": "asset_usdc_base_mainnet",
    "toAssetId": "asset_usdt_bsc_mainnet",
    "amount": "100",
    "order": "RECOMMENDED"
  }'

const quote = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/swaps/quote`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      fromAssetId: 'asset_usdc_base_mainnet',
      toAssetId: 'asset_usdt_bsc_mainnet',
      amount: '100',
      order: 'RECOMMENDED'
    })
  }
).then(r => r.json());

console.log('Quote:', quote.data);

Quote Response

{
  "message": "Swap quote fetched successfully",
  "statusCode": 200,
  "data": {
    "amount": "99.45",
    "minAmount": "98.95",
    "rate": "0.9945",
    "impact": "0.12",
    "slippage": "0.5",
    "networkFee": "0.002",
    "networkFeeInUSD": "0.15",
    "estimatedArrivalTime": 180
  }
}

Understanding Quote Fields

Field	Description
`amount`	Estimated amount you’ll receive after the swap
`minAmount`	Minimum guaranteed amount (accounting for slippage)
`rate`	Effective exchange rate (toAmount / fromAmount)
`impact`	Price impact percentage
`slippage`	Maximum allowed price movement percentage
`networkFee`	Gas fee in native token units
`networkFeeInUSD`	Gas fee converted to USD
`estimatedArrivalTime`	Expected completion time in seconds

Always display at minimum: amount to receive, estimated arrival time, and fees before the user confirms the swap.

Step 2: Execute the Swap

Once the user confirms the quote, execute the swap.

Request Parameters

Parameter	Type	Required	Description
`fromAssetId`	string	Yes	The asset ID to swap from
`toAssetId`	string	Yes	The asset ID to swap to
`amount`	string	Yes	The amount to swap
`order`	string	No	Quote preference: `FASTEST`, `CHEAPEST`, `RECOMMENDED`, `NO_SLIPPAGE`
`recipientAddress`	string	No	External wallet address (for sending to non-Blockradar wallets)
`reference`	string	No	Your internal tracking ID
`metadata`	object	No	Custom data passed through webhooks

Execute Example

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/swaps/execute \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "fromAssetId": "asset_usdc_base_mainnet",
    "toAssetId": "asset_usdt_bsc_mainnet",
    "amount": "100",
    "order": "RECOMMENDED",
    "reference": "swap-order-12345",
    "metadata": {
      "userId": "user_abc123",
      "orderId": "order_xyz789"
    }
  }'

const swap = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/swaps/execute`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      fromAssetId: 'asset_usdc_base_mainnet',
      toAssetId: 'asset_usdt_bsc_mainnet',
      amount: '100',
      order: 'RECOMMENDED',
      reference: 'swap-order-12345',
      metadata: {
        userId: 'user_abc123',
        orderId: 'order_xyz789'
      }
    })
  }
).then(r => r.json());

console.log('Swap initiated:', swap.data);

Execute Response

{
  "message": "Swap transaction created successfully",
  "statusCode": 200,
  "data": {
    "id": "swap-uuid-123",
    "type": "SWAP",
    "status": "PENDING",
    "fromAsset": {
      "symbol": "USDC",
      "amount": "100",
      "blockchain": "base"
    },
    "toAsset": {
      "symbol": "USDT",
      "amount": "99.45",
      "blockchain": "bsc"
    },
    "reference": "swap-order-12345",
    "metadata": {
      "userId": "user_abc123",
      "orderId": "order_xyz789"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Swap operations are asynchronous. The initial response shows PENDING status. Listen for the swap.success or swap.failed webhook to confirm completion.

Order Types

Choose the right order type based on your use case:

Order Type	Description	Best For
`FASTEST`	Prioritizes speed over cost	Time-sensitive transactions
`CHEAPEST`	Minimizes fees	Cost-sensitive operations
`RECOMMENDED`	Balanced approach (default)	Most use cases
`NO_SLIPPAGE`	Exact amount or fail	Precise amount requirements

Webhook Events

Monitor swap completion through webhooks:

Event	Description
`swap.success`	Swap completed successfully
`swap.failed`	Swap failed

Webhook Payload

{
  "event": "swap.success",
  "data": {
    "id": "swap-uuid-123",
    "type": "SWAP",
    "status": "SUCCESS",
    "fromAsset": {
      "symbol": "USDC",
      "amount": "100",
      "blockchain": "base",
      "hash": "0xabc..."
    },
    "toAsset": {
      "symbol": "USDT",
      "amount": "99.45",
      "blockchain": "bsc",
      "hash": "0xdef..."
    },
    "reference": "swap-order-12345",
    "metadata": {
      "userId": "user_abc123",
      "orderId": "order_xyz789"
    },
    "completedAt": "2024-01-15T10:33:00Z"
  }
}

Complete Flow Example

Here’s a full implementation showing the quote → confirm → execute flow:

async function executeSwap(walletId, fromAssetId, toAssetId, amount) {
  const apiKey = process.env.BLOCKRADAR_API_KEY;
  const baseUrl = 'https://api.blockradar.co/v1';

  // Step 1: Get quote
  const quote = await fetch(
    `${baseUrl}/wallets/${walletId}/swaps/quote`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        fromAssetId,
        toAssetId,
        amount,
        order: 'RECOMMENDED'
      })
    }
  ).then(r => r.json());

  // Step 2: Display quote to user
  console.log(`You will receive: ${quote.data.amount}`);
  console.log(`Minimum amount: ${quote.data.minAmount}`);
  console.log(`Network fee: $${quote.data.networkFeeInUSD}`);
  console.log(`Estimated time: ${quote.data.estimatedArrivalTime}s`);

  // Step 3: Execute swap (after user confirmation)
  const swap = await fetch(
    `${baseUrl}/wallets/${walletId}/swaps/execute`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        fromAssetId,
        toAssetId,
        amount,
        order: 'RECOMMENDED',
        reference: `swap-${Date.now()}`
      })
    }
  ).then(r => r.json());

  console.log('Swap initiated:', swap.data.id);
  console.log('Status:', swap.data.status);

  // Step 4: Listen for webhook to confirm completion
  return swap.data;
}

// Usage
executeSwap(
  'wallet-uuid',
  'asset_usdc_base_mainnet',
  'asset_usdt_bsc_mainnet',
  '100'
);

Error Responses

Insufficient Balance

{
  "message": "Insufficient balance for swap",
  "statusCode": 400,
  "error": "INSUFFICIENT_BALANCE",
  "data": {
    "required": "100",
    "available": "50.25",
    "asset": "USDC"
  }
}

Invalid Asset ID

{
  "message": "Asset not found",
  "statusCode": 404,
  "error": "ASSET_NOT_FOUND",
  "data": {
    "assetId": "invalid_asset_id"
  }
}

Swap Route Not Available

{
  "message": "No swap route available for this pair",
  "statusCode": 400,
  "error": "NO_ROUTE_AVAILABLE",
  "data": {
    "fromAsset": "USDC",
    "toAsset": "CUSTOM_TOKEN"
  }
}

Amount Too Low

{
  "message": "Amount below minimum swap threshold",
  "statusCode": 400,
  "error": "AMOUNT_TOO_LOW",
  "data": {
    "minimum": "10",
    "provided": "1"
  }
}

Slippage Exceeded

{
  "message": "Price moved beyond slippage tolerance",
  "statusCode": 400,
  "error": "SLIPPAGE_EXCEEDED",
  "data": {
    "expectedAmount": "99.45",
    "actualAmount": "97.00",
    "slippageTolerance": "0.5%"
  }
}

Best Practices

User Experience

Always show quotes: Display amount, fees, and estimated time before execution
Handle slippage: Inform users about potential price variations
Show progress: Use webhooks to update users on swap status

Security

Validate amounts: Ensure swap amounts are within acceptable ranges
Use references: Track swaps with unique reference IDs
Monitor webhooks: Always verify swap completion via webhooks

Performance

Cache asset IDs: Store asset IDs locally to avoid repeated lookups
Use appropriate order types: Choose FASTEST for time-sensitive, CHEAPEST for cost-sensitive
Implement retries: Handle transient failures with exponential backoff

API Reference

Endpoint	Description
Master Wallet Get Quote	Get swap quote from master wallet
Master Wallet Execute	Execute swap from master wallet
Child Address Get Quote	Get swap quote from child address
Child Address Execute	Execute swap from child address

Support

Email: [email protected]
Documentation: API Reference
Blog: How to Swap or Bridge Assets with Blockradar

The Swap API provides a unified interface for both same-chain swaps and cross-chain bridges. Start with small test amounts on testnets before moving to production.

Get Started

Wallets

Receive Payments

Send Payments

Convert & Manage

Compliance & Recovery

Integrations

Prerequisites

How It Works

Swap

Bridge

Supported Assets & Chains

Master Wallet vs Child Address

Master Wallet

Child Address

Endpoints

Step 1: Get a Quote

Request Parameters

Quote Example

Quote Response

Understanding Quote Fields

Step 2: Execute the Swap

Request Parameters

Execute Example

Execute Response

Order Types

Webhook Events

Webhook Payload

Complete Flow Example

Error Responses

Best Practices

User Experience

Security

Performance

API Reference

Support

​Prerequisites

​How It Works

Swap

Bridge

​Supported Assets & Chains

​Master Wallet vs Child Address

Master Wallet

Child Address

​Endpoints

​Step 1: Get a Quote

​Request Parameters

​Quote Example

​Quote Response

​Understanding Quote Fields

​Step 2: Execute the Swap

​Request Parameters

​Execute Example

​Execute Response

​Order Types

​Webhook Events

​Webhook Payload

​Complete Flow Example

​Error Responses

​Best Practices

​User Experience

​Security

​Performance

​API Reference

​Support

Prerequisites

How It Works

Supported Assets & Chains

Master Wallet vs Child Address

Endpoints

Step 1: Get a Quote

Request Parameters

Quote Example

Quote Response

Understanding Quote Fields

Step 2: Execute the Swap

Request Parameters

Execute Example

Execute Response

Order Types

Webhook Events

Webhook Payload

Complete Flow Example

Error Responses

Best Practices

User Experience

Security

Performance

API Reference

Support