| DOCSGuideReferenceGlossaryLog into Console

Stablecoin Conversion

Overview

The Create Stablecoin Conversion endpoint enables you to convert between different stablecoins within the Bridge ecosystem. This endpoint supports converting from various stablecoins (DAI, PYUSD, USDT) to primary stablecoins (USDC, EURC) and facilitates cross-network stablecoin transfers with automatic conversion and settlement.

Endpoint Details

  • Method: POST

  • URL: /api/v0/transfers/stablecoin-conversion

  • Content-Type: application/json

Authentication

This endpoint requires API key authentication using both:

  • x-client-key: Your application's client key

  • x-client-secret: Your application's client secret

Request Body 

{
  "walletId": "550e8400-e29b-41d4-a716-446655440000",
  "sourceNetwork": "ethereum",
  "sourceCurrency": "dai",
  "destinationCurrency": "usdc",
  "amount": 1000.50
}

Parameters

Parameter

Type

Required

Description

walletId

string

Yes

The ID of your Bridge wallet to receive the converted funds

sourceNetwork

string

Yes

Source blockchain network where you'll send the original stablecoin

sourceCurrency

string

Yes

Source stablecoin to convert from (dai, pyusd, usdt)

destinationCurrency

string

Yes

Target stablecoin to convert to (usdc, eurc)

amount

number

Yes

Amount to convert in source currency

Supported Source Networks

  • Ethereum (ethereum)

  • Polygon (polygon)

  • Arbitrum (arbitrum)

  • Optimism (optimism)

  • Base (base)

  • Avalanche C-Chain (avalanche_c_chain)

  • Solana (solana)

Supported Conversion Pairs

Source Currency

Destination Currency

Networks

Description

dai

usdc

All supported networks

DAI to USD Coin

dai

eurc

All supported networks

DAI to Euro Coin

pyusd

usdc

All supported networks

PayPal USD to USD Coin

pyusd

eurc

All supported networks

PayPal USD to Euro Coin

usdt

usdc

All supported networks

Tether to USD Coin

usdt

eurc

All supported networks

Tether to Euro Coin

Important Currency Limitations

  • EURC destination is only available on Solana network for the final settlement

  • Source currencies (DAI, PYUSD, USDT) are for conversion only - they cannot be held long-term

  • Destination currencies (USDC, EURC) are the primary stablecoins for wallet balances

Response

Success Response (201 Created) 

{
  "id": "tr_conv_1234567890abcdef",
  "state": "awaiting_funds",
  "amount": "1000.50",
  "developer_fee": "200.10",
  "on_behalf_of": "cus_bridge123abc",
  "source": {
    "payment_rail": "ethereum",
    "currency": "dai",
    "to_address": null,
    "external_account_id": null
  },
  "destination": {
    "payment_rail": "base",
    "currency": "usdc",
    "to_address": "0x742d35Cc6Ff82a8C2D8D1Da9da17c7eDfD5bE0a3",
    "external_account_id": null
  },
  "source_deposit_instructions": {
    "payment_rail": "ethereum",
    "currency": "dai",
    "amount": "1000.50",
    "to_address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
    "deposit_message": "Conversion ID: tr_conv_1234567890abcdef",
    "from_address": null,
    "bank_name": null,
    "bank_address": null,
    "bank_routing_number": null,
    "bank_account_number": null,
    "bank_beneficiary_name": null,
    "bank_beneficiary_address": null
  },
  "receipt": null,
  "created_at": "2024-01-20T10:30:00Z",
  "updated_at": "2024-01-20T10:30:00Z"
}

Response Fields

Main Transfer Object

Field

Type

Description

id

string

Unique conversion transfer identifier

state

string

Conversion state (awaiting_funds, processing, completed, failed)

amount

string

Amount to convert in source currency

developer_fee

string

Developer fee amount (20% of conversion amount)

on_behalf_of

string

Bridge customer ID

source

object

Source stablecoin and network information

destination

object

Destination stablecoin and wallet information

source_deposit_instructions

object

Critical: Deposit instructions for source stablecoin

receipt

object

Conversion receipt with rates and fees (available when completed)

created_at

string

Conversion creation timestamp

updated_at

string

Last update timestamp

Understanding Stablecoin Conversion Process

1. Conversion Setup

When you create a stablecoin conversion:

  • System generates a temporary receiving address for the source stablecoin

  • Creates deposit instructions for sending the source currency

  • Sets up automatic conversion to your desired destination currency

  • Prepares settlement to your specified Bridge wallet

2. Source Deposit Instructions

The sender (you or your user) must send the source stablecoin to the provided address:

{
  "source_deposit_instructions": {
    "payment_rail": "ethereum",
    "currency": "dai",
    "amount": "1000.50",
    "to_address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
    "deposit_message": "Conversion ID: tr_conv_1234567890abcdef"
  }
}

3. Automatic Conversion Flow

Once source funds are received:

  1. Detection: System detects incoming source stablecoin

  2. Conversion: Automatically converts at current market rates

  3. Settlement: Transfers converted stablecoin to your Bridge wallet

  4. Confirmation: Updates conversion state to completed

Conversion States

State

Description

Timeline

Next Action

awaiting_funds

Waiting for source stablecoin deposit

Immediate

Send source stablecoin to provided address

funds_received

Source funds detected, starting conversion

1-5 minutes

System processing conversion

processing

Converting between stablecoins

2-10 minutes

Wait for conversion completion

payment_submitted

Sending converted funds to wallet

1-5 minutes

Wait for blockchain confirmation

completed

Conversion successful

N/A

Check receipt for final amounts and rates

failed

Conversion failed

N/A

Check failure reason, retry if needed

Example Requests

DAI to USDC Conversion 

curl -X POST "https://api.yourplatform.com/api/v0/transfers/stablecoin-conversion" \
  -H "Content-Type: application/json" \
  -H "x-client-key: your_client_key_here" \
  -H "x-client-secret: your_client_secret_here" \
  -d '{
    "walletId": "550e8400-e29b-41d4-a716-446655440000",
    "sourceNetwork": "ethereum",
    "sourceCurrency": "dai",
    "destinationCurrency": "usdc",
    "amount": 1000.50
  }'

USDT to EURC Conversion 

curl -X POST "https://api.yourplatform.com/api/v0/transfers/stablecoin-conversion" \
  -H "Content-Type: application/json" \
  -H "x-client-key: your_client_key_here" \
  -H "x-client-secret: your_client_secret_here" \
  -d '{
    "walletId": "550e8400-e29b-41d4-a716-446655440000",
    "sourceNetwork": "polygon",
    "sourceCurrency": "usdt",
    "destinationCurrency": "eurc",
    "amount": 2500.75
  }'

PYUSD to USDC Conversion 

curl -X POST "https://api.yourplatform.com/api/v0/transfers/stablecoin-conversion" \
  -H "Content-Type: application/json" \
  -H "x-client-key: your_client_key_here" \
  -H "x-client-secret: your_client_secret_here" \
  -d '{
    "walletId": "550e8400-e29b-41d4-a716-446655440000",
    "sourceNetwork": "ethereum",
    "sourceCurrency": "pyusd",
    "destinationCurrency": "usdc",
    "amount": 5000.00
  }'

JavaScript (Node.js) 

const conversionData = {
  walletId: '550e8400-e29b-41d4-a716-446655440000',
  sourceNetwork: 'ethereum',
  sourceCurrency: 'dai',
  destinationCurrency: 'usdc',
  amount: 1000.50
};

const response = await fetch('https://api.yourplatform.com/api/v0/transfers/stablecoin-conversion', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-client-key': 'your_client_key_here',
    'x-client-secret': 'your_client_secret_here'
  },
  body: JSON.stringify(conversionData)
});

if (!response.ok) {
  throw new Error(`HTTP error! status: ${response.status}`);
}

const conversion = await response.json();

// Extract deposit instructions
const instructions = conversion.source_deposit_instructions;

console.log('=== STABLECOIN CONVERSION INSTRUCTIONS ===');
console.log(`Send ${instructions.amount} ${instructions.currency.toUpperCase()}`);
console.log(`From Network: ${conversion.source.payment_rail}`);
console.log(`To Address: ${instructions.to_address}`);
console.log(`Will Convert To: ${conversion.destination.currency.toUpperCase()}`);
console.log(`Final Network: ${conversion.destination.payment_rail}`);
console.log(`Reference: ${instructions.deposit_message}`);

// Monitor conversion status
const checkStatus = async () => {
  const statusResponse = await fetch(`/api/v0/transfers/${conversion.id}`, {
    headers: {
      'x-client-key': 'your_client_key_here',
      'x-client-secret': 'your_client_secret_here'
    }
  });
  
  const currentStatus = await statusResponse.json();
  console.log(`Conversion Status: ${currentStatus.state}`);
  
  if (currentStatus.state === 'completed' && currentStatus.receipt) {
    console.log('Conversion completed!');
    console.log(`Final Amount: ${currentStatus.receipt.final_amount} ${conversion.destination.currency.toUpperCase()}`);
    console.log(`Exchange Rate Applied: ${currentStatus.receipt.exchange_rate || 'See receipt'}`);
  }
};

Python 

import requests
import json
import time

url = "https://api.yourplatform.com/api/v0/transfers/stablecoin-conversion"
headers = {
    'Content-Type': 'application/json',
    'x-client-key': 'your_client_key_here',
    'x-client-secret': 'your_client_secret_here'
}

data = {
    'walletId': '550e8400-e29b-41d4-a716-446655440000',
    'sourceNetwork': 'polygon',
    'sourceCurrency': 'usdt',
    'destinationCurrency': 'usdc',
    'amount': 2500.75
}

response = requests.post(url, headers=headers, data=json.dumps(data))

if response.status_code == 201:
    conversion = response.json()
    instructions = conversion['source_deposit_instructions']
    
    print("=== STABLECOIN CONVERSION INSTRUCTIONS ===")
    print(f"Send: {instructions['amount']} {instructions['currency'].upper()}")
    print(f"From Network: {conversion['source']['payment_rail']}")
    print(f"To Address: {instructions['to_address']}")
    print(f"Will Convert To: {conversion['destination']['currency'].upper()}")
    print(f"Final Network: {conversion['destination']['payment_rail']}")
    print(f"Reference: {instructions['deposit_message']}")
    
    # Function to monitor conversion status
    def check_conversion_status(conversion_id):
        status_url = f"https://api.yourplatform.com/api/v0/transfers/{conversion_id}"
        status_response = requests.get(status_url, headers=headers)
        
        if status_response.status_code == 200:
            status_data = status_response.json()
            print(f"Conversion Status: {status_data['state']}")
            
            if status_data['state'] == 'completed' and status_data.get('receipt'):
                print("Conversion completed!")
                receipt = status_data['receipt']
                print(f"Final Amount: {receipt['final_amount']} {conversion['destination']['currency'].upper()}")
                print(f"Developer Fee: {receipt['developer_fee']}")
                print(f"Exchange Fee: {receipt.get('exchange_fee', 'N/A')}")
                return True
        
        return False
    
    # Monitor status every 30 seconds
    conversion_id = conversion['id']
    print(f"\nMonitoring conversion {conversion_id}...")
    
else:
    print(f"Error: {response.status_code}")
    print(response.text)

PHP 

<?php
$data = [
    'walletId' => '550e8400-e29b-41d4-a716-446655440000',
    'sourceNetwork' => 'ethereum',
    'sourceCurrency' => 'dai',
    'destinationCurrency' => 'usdc',
    'amount' => 1000.50
];

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.yourplatform.com/api/v0/transfers/stablecoin-conversion',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'x-client-key: your_client_key_here',
        'x-client-secret: your_client_secret_here'
    ],
]);

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

if ($httpCode === 201) {
    $conversion = json_decode($response, true);
    $instructions = $conversion['source_deposit_instructions'];
    
    echo "=== STABLECOIN CONVERSION INSTRUCTIONS ===\n";
    echo "Send: {$instructions['amount']} " . strtoupper($instructions['currency']) . "\n";
    echo "From Network: {$conversion['source']['payment_rail']}\n";
    echo "To Address: {$instructions['to_address']}\n";
    echo "Will Convert To: " . strtoupper($conversion['destination']['currency']) . "\n";
    echo "Final Network: {$conversion['destination']['payment_rail']}\n";
    echo "Reference: {$instructions['deposit_message']}\n";
} else {
    echo "Error: $httpCode\n";
    echo $response;
}
?>

Conversion Receipt

When the conversion completes, you'll receive a detailed receipt:

{
  "receipt": {
    "initial_amount": "1000.50",
    "exchange_fee": "5.00",
    "developer_fee": "200.10",
    "gas_fee": "2.50",
    "subtotal_amount": "792.90",
    "final_amount": "792.90"
  }
}

Receipt Fields

Field

Description

initial_amount

Original amount in source currency

exchange_fee

Fee for currency conversion

developer_fee

0.6% developer fee

gas_fee

Blockchain transaction fees

subtotal_amount

Amount after all fees

final_amount

Final amount received in destination currency

Error Responses

400 Bad Request 

{
  "statusCode": 400,
  "message": "Invalid source currency for conversion",
  "error": "Bad Request"
}

404 Not Found 

{
  "statusCode": 404,
  "message": "Bridge wallet not found with ID: 550e8400-e29b-41d4-a716-446655440000",
  "error": "Not Found"
}

422 Unprocessable Entity 

{
  "statusCode": 422,
  "message": "EURC destination is only supported on Solana network",
  "error": "Unprocessable Entity"
}

Unsupported Conversion 

{
  "statusCode": 400,
  "message": "Conversion from USDC to DAI is not supported. DAI can only be used as source currency.",
  "error": "Bad Request"
}

Fee Structure & Exchange Rates

Developer Fees

  • 0.6% developer fee applied to all conversions

  • Fee calculated on the source amount before conversion

  • Example: 1000 DAI conversion = 60 DAI developer fee

Exchange Rates

  • Real-time market rates applied at conversion time

  • Rate displayed in final receipt for transparency

Network Fees

  • Gas fees for blockchain transactions included

  • Fees vary by network congestion and transaction complexity

  • Optimized routing for lowest fees when possible

Conversion Timeframes

Source Network

Typical Processing Time

Blockchain Confirmations

Ethereum

5-15 minutes

12 confirmations

Polygon

2-5 minutes

50 confirmations

Arbitrum

3-8 minutes

1 confirmation

Optimism

3-8 minutes

1 confirmation

Base

2-5 minutes

1 confirmation

Avalanche

2-5 minutes

1 confirmation

Solana

1-3 minutes

32 confirmations

Important Notes

Currency Restrictions

  • DAI, PYUSD, USDT, USDC, EURC can ONLY be used as source currencies for conversion

  • These currencies cannot be held in wallets long-term

  • USDC and EURC are the only supported destination currencies for wallet balances

EURC Limitations

  • EURC as destination currency is only available on Solana network

  • Cross-network EURC conversions will settle on Solana regardless of source network

Network Optimization

  • System automatically selects optimal paths for lowest fees

  • Cross-network conversions may route through multiple networks

  • Final settlement always reaches your specified Bridge wallet

Slippage Protection

  • Large conversions may be subject to slippage limits

  • System will reject conversions with excessive slippage

  • Consider breaking large conversions into smaller batches

Use Cases

  1. DeFi Integration: Convert DeFi tokens (DAI, USDT) to Bridge-compatible stablecoins

  2. Multi-Currency Support: Accept various stablecoins while maintaining USDC/EURC wallets

  3. Arbitrage Opportunities: Take advantage of rate differences between stablecoins

  4. Payment Processing: Convert customer payments from any supported stablecoin

  5. Treasury Management: Consolidate various stablecoin holdings into preferred currencies

Monitoring and Webhooks

Webhook Events

Set up webhooks to receive real-time conversion updates:

  • conversion.awaiting_funds

  • conversion.funds_received

  • conversion.processing

  • conversion.completed

  • conversion.failed

Status Polling 

const pollConversionStatus = async (conversionId) => {
  const response = await fetch(`/api/v0/transfers/${conversionId}`, {
    headers: {
      'x-client-key': 'your_client_key_here',
      'x-client-secret': 'your_client_secret_here'
    }
  });
  
  const conversion = await response.json();
  
  if (conversion.state === 'completed') {
    console.log('Conversion completed!');
    console.log('Receipt:', conversion.receipt);
    return conversion;
  } else if (conversion.state === 'failed') {
    console.log('Conversion failed:', conversion.failure_reason);
    throw new Error(`Conversion failed: ${conversion.failure_reason}`);
  }
  
  console.log(`Current state: ${conversion.state}`);
  return null;
};

Next Steps

After creating a stablecoin conversion:

  1. Send Source Funds: Transfer the source stablecoin to the provided address

  2. Monitor Progress: Track conversion status through webhooks or polling

  3. Verify Completion: Check final receipt for conversion rates and fees

  4. Update Balances: Refresh wallet balances to see converted funds

  5. Handle Errors: Implement retry logic for failed conversions

Related Endpoints

  • GET /api/v0/wallets - List your Bridge wallets and balances

  • GET /api/v0/transfers/{id} - Check conversion status and receipt

  • POST /api/v0/transfers/direct-wallet - Create wallet-to-wallet transfers

  • POST /api/v0/transfers/direct-bank - Create bank-to-wallet transfers