| DOCSGuideReferenceGlossaryLog into Console

Direct Wallet Transfer

The Create Direct Wallet Transfer endpoint enables you to initiate blockchain-to-blockchain transfers where the source funds come from an external wallet (not yours) and are deposited directly into one of your Bridge wallets. This endpoint creates a dynamic transfer that provides source deposit instructions for the sender to follow.

Endpoint DetailsCopied!

  • Method: POST

  • URL: /api/v0/transfers/direct-wallet

  • Content-Type: application/json

AuthenticationCopied!

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 BodyCopied! 

{
  "walletId": "550e8400-e29b-41d4-a716-446655440000",
  "network": "solana",
  "stableCoinCurrency": "usdc",
  "amount": 1000.50
}

Parameters

Parameter

Type

Required

Description

walletId

string

Yes

The ID of your wallet to receive the transfer

network

string

Yes

Source blockchain network (solana, base, ethereum, polygon, arbitrum, etc.)

stableCoinCurrency

string

Yes

Source stablecoin currency (usdc, eurc)

amount

number

No

Transfer amount (optional for flexible amount transfers)

Supported Networks

  • Solana (solana)

  • Base (base)

  • Ethereum (ethereum)

  • Polygon (polygon)

  • Arbitrum (arbitrum)

  • Optimism (optimism)

  • Avalanche C-Chain (avalanche_c_chain)

Supported Stablecoin Currencies

  • USDC (usdc) - Available on all networks

  • EURC (eurc) - Currently only available on Solana

ResponseCopied!

Success Response (201 Created)

{
  "id": "tr_1234567890abcdef",
  "state": "awaiting_funds",
  "amount": "1000.50",
  "developer_fee": "200.10",
  "on_behalf_of": "cus_bridge123abc",
  "source": {
    "payment_rail": "solana",
    "currency": "usdc",
    "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": "solana",
    "currency": "usdc",
    "amount": "1000.50",
    "to_address": "7xKXKRoBrJgCXVb2KhxZZzPHxYMJ4DpHWGQ8RvxS6JEq",
    "deposit_message": "Transfer ID: tr_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 transfer identifier

state

string

Transfer state (awaiting_funds, processing, completed, failed)

amount

string

Transfer amount (if fixed)

developer_fee

string

Developer fee amount (20% of transfer amount)

source

object

Source endpoint information

destination

object

Destination endpoint information

source_deposit_instructions

object

Critical: Instructions for the sender

receipt

object

Transfer receipt (available when completed)

created_at

string

Transfer creation timestamp

updated_at

string

Last update timestamp

Understanding Source Deposit InstructionsCopied!

The source_deposit_instructions object is the most important part of the response. It contains the exact information that the external sender needs to complete the transfer.

For Blockchain Networks (Solana, Base, Ethereum, etc.)

{
  "source_deposit_instructions": {
    "payment_rail": "solana",
    "currency": "usdc",
    "amount": "1000.50",
    "to_address": "7xKXKRoBrJgCXVb2KhxZZzPHxYMJ4DpHWGQ8RvxS6JEq",
    "deposit_message": "Transfer ID: tr_1234567890abcdef"
  }
}
Key Fields for Blockchain Instructions

Field

Description

Usage

to_address

Destination address

Sender must send funds TO this address

currency

Token to send

Sender must send this specific stablecoin

amount

Amount to send

Exact amount required (if fixed amount)

deposit_message

Transfer reference

Include as memo/note if supported by network

For Bank/Wire Transfers (ACH, WIRE, SEPA)

{
  "source_deposit_instructions": {
    "payment_rail": "wire",
    "currency": "usd",
    "amount": "1000.50",
    "bank_name": "JPMorgan Chase Bank, N.A.",
    "bank_address": "270 Park Avenue, New York, NY 10017",
    "bank_routing_number": "021000021",
    "bank_account_number": "1234567890",
    "bank_beneficiary_name": "Bridge Network Inc",
    "bank_beneficiary_address": "123 Bridge Street, San Francisco, CA 94105",
    "deposit_message": "Transfer ID: tr_1234567890abcdef"
  }
}
Key Fields for Bank Instructions

Field

Description

Usage

bank_name

Receiving bank name

For wire transfer forms

bank_routing_number

Bank routing/SWIFT code

Required for transfers

bank_account_number

Account number

Destination account

bank_beneficiary_name

Account holder name

Beneficiary information

deposit_message

Critical reference

Must be included in transfer memo

How Source Deposit Instructions WorkCopied!

1. Dynamic Transfer Creation

When you create a direct wallet transfer, the system:

  • Generates a unique temporary receiving address/account

  • Creates deposit instructions for the sender

  • Sets up monitoring for incoming funds

2. Sender Instructions

You provide the

source_deposit_instructions

to the external sender, who must:

  • Send the exact currency and amount (specified)

  • Send TO the provided to_address (blockchain) or bank details

  • Include the deposit_message as memo/reference

3. Automatic Processing

Once funds are received:

  • System detects the incoming deposit

  • Automatically converts and transfers to your destination wallet

  • Updates transfer state to completed

  • Provides final receipt with all fees and amounts

Transfer StatesCopied!

State

Description

Next Action

awaiting_funds

Waiting for sender to deposit funds

Provide deposit instructions to sender

funds_received

Funds detected, processing conversion

Wait for completion

processing

Converting and transferring to destination

Monitor for completion

completed

Transfer successful

Check receipt for final amounts

failed

Transfer failed

Check failure reason, may need retry

Example RequestsCopied!

cURL

curl -X POST "https://api.yourplatform.com/api/v0/transfers/direct-wallet" \
  -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",
    "network": "solana", 
    "stableCoinCurrency": "usdc",
    "amount": 1000.50
  }'

JavaScript (Node.js)

const transferData = {
  walletId: '550e8400-e29b-41d4-a716-446655440000',
  network: 'solana',
  stableCoinCurrency: 'usdc',
  amount: 1000.50
};

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

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

const transfer = await response.json();

// Extract deposit instructions for the sender
const instructions = transfer.source_deposit_instructions;
console.log('Sender should send', instructions.amount, instructions.currency);
console.log('To address:', instructions.to_address);
console.log('Include memo:', instructions.deposit_message);

Python

import requests
import json

url = "https://api.yourplatform.com/api/v0/transfers/direct-wallet"
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',
    'network': 'solana',
    'stableCoinCurrency': 'usdc', 
    'amount': 1000.50
}

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

if response.status_code == 201:
    transfer = response.json()
    instructions = transfer['source_deposit_instructions']
    
    print(f"Sender should send {instructions['amount']} {instructions['currency']}")
    print(f"To address: {instructions['to_address']}")
    print(f"Include memo: {instructions['deposit_message']}")
else:
    print(f"Error: {response.status_code}")
    print(response.text)

PHP

<?php
$data = [
    'walletId' => '550e8400-e29b-41d4-a716-446655440000',
    'network' => 'solana',
    'stableCoinCurrency' => 'usdc',
    'amount' => 1000.50
];

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.yourplatform.com/api/v0/transfers/direct-wallet',
    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) {
    $transfer = json_decode($response, true);
    $instructions = $transfer['source_deposit_instructions'];
    
    echo "Sender should send {$instructions['amount']} {$instructions['currency']}\n";
    echo "To address: {$instructions['to_address']}\n";
    echo "Include memo: {$instructions['deposit_message']}\n";
} else {
    echo "Error: $httpCode\n";
    echo $response;
}
?>

Error ResponsesCopied!

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid network or currency combination",
  "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 is only supported on Solana network",
  "error": "Unprocessable Entity"
}

Important NotesCopied!

Developer Fees

  • 0.8% developer fee is automatically applied to all transfers

  • Fee is calculated on the total transfer amount

  • Fee is deducted from the final amount received

Flexible vs Fixed Amount

  • With amount: Creates fixed amount transfer with specific deposit instructions

  • Without amount: Creates flexible amount transfer allowing variable amounts

Network Compatibility

  • EURC is currently only supported on Solana network

  • USDC is supported on all networks

  • Cross-network transfers are automatically handled

Security & Monitoring

  • All transfers are monitored in real-time

  • Deposit instructions expire after a set period

  • Failed transfers can be retried or refunded

Use CasesCopied!

  1. Customer Deposits: Allow customers to deposit from their external wallets

  2. Cross-Platform Integration: Accept funds from other platforms/exchanges

  3. B2B Payments: Receive payments from business partners

  4. Remittances: International money transfers via stablecoins

  5. DeFi Integration: Receive funds from DeFi protocols

Next StepsCopied!

After creating a direct wallet transfer:

  1. Provide Instructions: Share source_deposit_instructions with the sender

  2. Monitor Status: Poll transfer status or use webhooks for updates

  3. Handle Completion: Process successful transfers in your application

  4. Error Handling: Implement retry logic for failed transfers

Related EndpointsCopied!

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

  • GET /api/v0/transfers/{id} - Check transfer status

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