Transfer

Send cryptocurrency from a customer's wallet to any address on supported blockchain networks.

Endpoint

POST /api/v1/wallet/customer/:customerID/transfer

Authentication

Requires API key authentication via X-API-Key header.

Path Parameters

Parameter	Type	Description
customerID	string	Customer identifier

Request Body

Field	Type	Required	Description
network	string	Yes	Blockchain network (BTC, ETH, BSC, POL, TRX, SOL, etc.)
currency	string	Yes	Currency to send (BTC, ETH, USDT, USDC, etc.)
to_address	string	Yes	Recipient's blockchain address
amount	string	Yes	Amount in smallest unit (satoshis, wei, lamports)
index	integer	No	Address index to send from (default: 0)

Amount Units by Network

Network	Native Currency	Smallest Unit	Decimals	Example
Bitcoin	BTC	satoshi	8	1 BTC = 100,000 ,000 satoshis
Ethereum	ETH	wei	18	1 ETH = 1,000,000,000,000,000,000 wei
BSC	BNB	wei	18	1 BNB = 1,000,000,000,000,000,000 wei
Polygon	POL	wei	18	1 POL = 1,000,000,000,000,000,000 wei
Tron	TRX	sun	6	1 TRX = 1,000,000 sun
Solana	SOL	lamport	9	1 SOL = 1,000,000,000 lamports

Example Request

JavaScript

// Send 0.01 BTC
const response = await fetch(
  'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/transfer',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      network: 'BTC',
      currency: 'BTC',
      to_address: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
      amount: '1000000', // 0.01 BTC in satoshis
      index: 0
    })
  }
);

const transfer = await response.json();
console.log('Transaction Hash:', transfer.txn_hash);
console.log('Status:', transfer.status);

Python

import requests

# Send 50 USDT on BSC
response = requests.post(
    'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/transfer',
    headers={
        'X-API-Key': 'your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'network': 'BSC',
        'currency': 'USDT',
        'to_address': '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
        'amount': '50000000',  # 50 USDT (6 decimals)
        'index': 0
    }
)

transfer = response.json()
print(f"Transaction: {transfer['txn_hash']}")
print(f"Gas Fee: {transfer['gas_fee']}")

cURL

curl -X POST https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/transfer \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "ETH",
    "currency": "ETH",
    "to_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "amount": "100000000000000000",
    "index": 0
  }'

Response

Success Response (200 OK)

Field	Type	Description
txn_hash	string	Transaction hash/ID
network	string	Blockchain network
currency	string	Currency sent
from_address	string	Sender address
to_address	string	Recipient address
amount	string	Amount sent (in smallest unit)
gas_fee	string	Transaction fee paid
status	string	Transaction status (pending/confirmed/failed)
timestamp	string	Transaction timestamp

{
  "txn_hash": "0x1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2v3w4x5y6z7a8b9c0d1e2f",
  "network": "ETH",
  "currency": "ETH",
  "from_address": "0x8B3192f2f0f0D7E4F5C3A1B9E2D7A6C5B4D3E2F1",
  "to_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "amount": "100000000000000000",
  "gas_fee": "630000000000000",
  "status": "pending",
  "timestamp": "2026-01-03T04:18:00Z"
}

Error Responses

400 Bad Request

{
  "error": "invalid amount: insufficient balance"
}

404 Not Found

{
  "error": "Wallet not found"
}

500 Internal Server Error

{
  "error": "failed to broadcast transaction: network error"
}

Transaction Status

After initiating a transfer, track its status:

Status	Description	Action
pending	Broadcast to network, awaiting confirmation	Wait for confirmation
confirmed	Included in block, transfer complete	No action needed
failed	Transaction failed (insufficient gas, etc.)	Retry or investigate

Use Cases

Withdrawal Flow

Complete withdrawal with validation and confirmation:

async function processWithdrawal(customerId, withdrawal) {
  // 1. Validate address format
  if (!isValidAddress(withdrawal.to_address, withdrawal.network)) {
    throw new Error('Invalid recipient address');
  }
  
  // 2. Estimate gas
  const estimate = await estimateGas(withdrawal);
  
  // 3. Check balance
  const balance = await getBalance(customerId, withdrawal.network);
  const total = parseFloat(withdrawal.amount) + parseFloat(estimate.estimated_fee);
  
  if (balance < total) {
    throw new Error('Insufficient balance for amount + gas fee');
  }
  
  // 4. Show confirmation
  const confirmed = confirm(
    `Send ${formatAmount(withdrawal.amount)} ${withdrawal.currency}\n` +
    `To: ${withdrawal.to_address}\n` +
    `Fee: ${estimate.estimated_fee}\n` +
    `Total: ${total}\n\n` +
    `Confirm withdrawal?`
  );
  
  if (!confirmed) return null;
  
  // 5. Execute transfer
  const response = await fetch(
    `https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/${customerId}/transfer`,
    {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(withdrawal)
    }
  );
  
  const transfer = await response.json();
  
  // 6. Save to database
  await saveWithdrawal({
    customer_id: customerId,
    txn_hash: transfer.txn_hash,
    amount: withdrawal.amount,
    status: transfer.status
  });
  
  return transfer;
}

Batch Transfers

Send to multiple recipients:

async function batchTransfer(customerId, recipients, network, currency) {
  const results = [];
  
  for (const recipient of recipients) {
    try {
      const response = await fetch(
        `https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/${customerId}/transfer`,
        {
          method: 'POST',
          headers: {
            'X-API-Key': process.env.API_KEY,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            network,
            currency,
            to_address: recipient.address,
            amount: recipient.amount,
            index: 0
          })
        }
      );
      
      const transfer = await response.json();
      results.push({
        recipient: recipient.address,
        txn_hash: transfer.txn_hash,
        status: 'success'
      });
      
      // Wait 1 second between transfers to avoid nonce conflicts
      await new Promise(resolve => setTimeout(resolve, 1000));
      
    } catch (error) {
      results.push({
        recipient: recipient.address,
        error: error.message,
        status: 'failed'
      });
    }
  }
  
  return results;
}

Best Practices

Transfer Safety

• Validate addresses: Always validate recipient address format before transfer
• Estimate first: Use estimate-gas before transfer
• Check balance: Ensure sufficient balance for amount + gas fee
• Confirm with user: Show clear confirmation with amount, address, and fees
• Save txn_hash: Store transaction hash for tracking and support
• Monitor status: Poll or use webhooks to track transaction confirmation
• Handle errors: Implement retry logic for network failures
• Test on testnet: Always test with testnet addresses first

Block Explorers

View transactions on block explorers:

Network	Explorer	URL Format
Bitcoin	Blockchain.com	https://www.blockchain.com/btc/tx/{txn_hash}
Ethereum	Etherscan	https://etherscan.io/tx/{txn_hash}
BSC	BscScan	https://bscscan.com/tx/{txn_hash}
Polygon	PolygonScan	https://polygonscan.com/tx/{txn_hash}
Tron	Tronscan	https://tronscan.org/#/transaction/{txn_hash}
Solana	Solscan	https://solscan.io/tx/{txn_hash}

Related Endpoints

• Estimate Gas - Estimate fees before transfer
• Get Transactions - View transfer history
• List Addresses - Check balances