API Reference

Withdrawals

Manage your funds. Check your balance and request withdrawals to your preferred wallet address.

How Withdrawals Work

Accumulate Balance

When invoices are paid and confirmed, the funds are credited to your internal tenant balance.

Request Withdrawal

Use the API to request a withdrawal. You can withdraw USDT BEP-20 directly (internal transfer) or withdraw in 60+ cryptocurrencies with automatic conversion.

Fee Applied

For internal USDT BEP-20 transfers: a withdrawal fee is automatically calculated and deducted. For multi-currency withdrawals: exchange fees are included in the conversion rate.

Funds Transferred

The requested amount is sent to your destination address in the selected cryptocurrency.

Multi-Currency Withdrawals

Our platform supports withdrawals in multiple cryptocurrencies through our integrated exchange service.

USDT BEP-20 (Default & Recommended)

Internal transfers with minimal fees. Fastest processing time and lowest costs.

Minimum withdrawal: $0.01 USDT (dust protection)
Fee: Fixed rate established during account setup (typically 1-2%)
Gas cost: Auto-managed (~$0.01 per transaction)
Processing: Usually within minutes
Network: Binance Smart Chain (BSC/BEP-20)

Other Cryptocurrencies via Exchange Service

Withdraw in 70+ cryptocurrencies using our integrated exchange service.

Fees: Determined by exchange rates
Min/Max limits: Set per currency pair
Processing: Depends on network congestion
Availability: Requires exchange API credentials configured

Exchange Service API Rate Limits

Weight-Based Limit System

Our exchange service uses a weight-based rate limiting system to maintain service stability.

Rate Limit

250 weight units per minute

Request Costs

/api/v2/create (order creation): 50 units
All other endpoints: 1 unit each

Consequences of Exceeding Limits

Your API token will be temporarily blocked
Block duration increases with each subsequent violation
You'll receive HTTP 429 (Too Many Requests) responses

Best Practices

Monitor Usage: Track your request count to stay within limits
Implement Backoff: If you receive HTTP 429, pause and retry with exponential backoff
Cache Results: Cache currency lists and price quotes when possible
Batch Operations: Minimize unnecessary API calls by batching when appropriate

Check Balance

Retrieve your current available balance for withdrawals.

GET/v1/withdrawals/balance

Get current tenant balance

get-balance.js

const response = await fetch('https://api.fromchain.plus/v1/withdrawals/balance', {
  headers: {
    'Authorization': 'Bearer gw_live_...'
  }
});

const balance = await response.json();
// {
//   "available": "1500.00",
//   "currency": "USDT",
//   "network": "BSC"
// }

Calculate Maximum Withdrawal

Get the maximum amount you can withdraw considering your current balance and fee rate. This endpoint automatically calculates the max withdrawal so that amount + fee = available balance.

GET/v1/withdrawals/max

Get maximum withdrawal amount

get-max-withdrawal.js

const response = await fetch('https://api.fromchain.plus/v1/withdrawals/max', {
  headers: {
    'Authorization': 'Bearer gw_live_...'
  }
});

const maxData = await response.json();
// {
//   "maxAmount": "99.01",       // Maximum amount you can request
//   "balance": "100.00",        // Your current available balance
//   "feePercent": "0.01",       // Your fee rate (1%)
//   "estimatedFee": "0.99",     // Fee that will be charged
//   "minWithdrawal": "0.01"     // Minimum withdrawal amount (dust protection)
// }

// If you withdraw maxAmount (99.01):
// - You receive: 99.01 USDT
// - Fee charged: 0.99 USDT  
// - Total deducted: 100.00 USDT (your full balance)

Smart Calculation: The maximum withdrawal is calculated as balance / (1 + feePercent). This ensures the fee is always collected and you never exceed your available balance.

Request Withdrawal

Initiate a transfer of funds from your balance to an external wallet.

POST/v1/withdrawals

Request a new withdrawal

Request Body

amountstringAmount to receive

destinationAddressstringDestination wallet address (42 chars)

networkstringOptional. Default: BSC

tokenstringOptional. Default: USDT

postBackUrlstringOptional. HTTPS callback URL for this withdrawal only

request-withdrawal.js

const response = await fetch('https://api.fromchain.plus/v1/withdrawals', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer gw_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: "1000.00",
    destinationAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
  })
});

const withdrawal = await response.json();
// {
//   "id": "wd_123abc",
//   "amount": "1000.00",
//   "feeAmount": "10.00",
//   "netAmount": "1000.00",
//   "status": "PENDING",
//   "destinationAddress": "0x742d...",
//   "chain": "BSC",
//   "token": "USDT",
//   "createdAt": "2025-12-19T10:00:00Z"
// }

Important: Ensure the destination address is correct and on the correct network (BSC/BEP-20). Funds sent to incorrect addresses cannot be recovered.

PostBack URL: Use postBackUrl to receive notifications for this specific withdrawal at a custom HTTPS URL. When set, all status updates (created, completed, failed) are sent exclusively to this URL, ignoring your configured webhooks.

Withdrawal Fees & Costs

Withdrawal fees are set during your account setup and defined in your service contract. The fee is automatically calculated and deducted from your balance on top of the withdrawal amount.

📋 Fee Structure: Your withdrawal fee rate is established when your account is created. You can check your current fee rate using the GET /v1/tenants/me endpoint. The fee is applied as a percentage of the withdrawal amount (typically 1-2%).

Automatic Gas Management: BNB gas fees are automatically funded from our system wallet before each withdrawal. After the transaction completes, unused BNB is automatically returned. You don't need to manage gas yourself!

Withdrawal History

View your past withdrawal requests and their status.

GET/v1/withdrawals

List all withdrawals

list-withdrawals.js

const response = await fetch('https://api.fromchain.plus/v1/withdrawals?page=1&limit=10', {
  headers: {
    'Authorization': 'Bearer gw_live_...'
  }
});

const data = await response.json();
// {
//   "data": [
//     {
//       "id": "wd_123abc",
//       "amount": "1000.00",
//       "status": "COMPLETED",
//       "txHash": "0xabc...",
//       "createdAt": "2025-12-19T10:00:00Z"
//     }
//   ],
//   "meta": {
//     "total": 5,
//     "page": 1,
//     "lastPage": 1
//   }
// }

Exchange Service Integration (Multi-Currency)

Use exchange service endpoints to check available currencies, get exchange rates, and create orders for multi-currency withdrawals.

Check Exchange Service Availability

GET/v1/withdrawals/exchange/available

Check if exchange service is configured and available

check-exchange.js

const response = await fetch('https://api.fromchain.plus/v1/withdrawals/exchange/available', {
  headers: {
    'Authorization': 'Bearer gw_live_...'
  }
});

const data = await response.json();
// { "available": true }

List Available Currencies

GET/v1/withdrawals/exchange/currencies

Get list of supported cryptocurrencies from exchange service

list-currencies.js

const response = await fetch('https://api.fromchain.plus/v1/withdrawals/exchange/currencies', {
  headers: {
    'Authorization': 'Bearer gw_live_...'
  }
});

const data = await response.json();
// {
//   "code": 0,
//   "msg": "OK",
//   "data": [
//     {
//       "code": "BTC",
//       "coin": "BTC",
//       "network": "Bitcoin",
//       "name": "Bitcoin",
//       "send": true,
//       "recv": true
//     },
//     // ... 70+ more currencies
//   ]
// }

Get Exchange Rate and Limits

POST/v1/withdrawals/exchange/price

Calculate exchange rate, fees, and min/max limits for a currency pair

get-price.js

const response = await fetch('https://api.fromchain.plus/v1/withdrawals/exchange/price', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer gw_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: "float",           // "float" or "fixed"
    fromCcy: "USDTBSC",      // From currency code
    toCcy: "BTC",            // To currency code  
    direction: "from",       // "from" or "to"
    amount: 100              // Amount to exchange
  })
});

const data = await response.json();
// {
//   "code": 0,
//   "msg": "OK",
//   "data": {
//     "from": {
//       "code": "USDTBSC",
//       "coin": "USDT",
//       "network": "BEP20",
//       "amount": "100.00",
//       "rate": "0.000001544"
//     },
//     "to": {
//       "code": "BTC",
//       "coin": "BTC",  
//       "network": "Bitcoin",
//       "amount": "0.0001544",
//       "rate": "64766.83886"
//     },
//     "min": "50.00",
//     "max": "50000.00"
//   }
// }

Rate Limit: This endpoint costs 1 weight unit. You can make up to 250 price checks per minute.

Create Manual Exchange Order (Not Recommended)

POST/v1/withdrawals/exchange/order

Create a cryptocurrency exchange order (manual - you must send USDT yourself)

create-order.js

const response = await fetch('https://api.fromchain.plus/v1/withdrawals/exchange/order', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer gw_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: "float",
    fromCcy: "USDTBSC",
    toCcy: "BTC",
    direction: "from",
    amount: 100,
    toAddress: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"  // Destination BTC address
  })
});

const data = await response.json();
// {
//   "code": 0,
//   "msg": "OK",
//   "data": {
//     "id": "ABCDEFGH",
//     "type": "float",
//     "email": null,
//     "status": "NEW",
//     "time": {
//       "reg": "2025-12-20 12:00:00",
//       "start": null,
//       "finish": null,
//       "update": null
//     },
//     "from": { 
//       "code": "USDTBSC", 
//       "amount": "100.00",
//       "address": "0xABC..."  // YOU must send USDT to this address
//     },
//     "to": { 
//       "code": "BTC",
//       "amount": "0.0001544",
//       "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
//     },
//     "token": "secret_token_for_order_operations"
//   }
// }

Manual Process: This creates an order but you must manually send USDT to the deposit address. For automatic processing, use /exchange/withdrawal instead.

Rate Limit: Order creation costs 50 weight units. Maximum of 5 orders per minute. Save the token to check order status later.

Create Automatic Withdrawal (Recommended ⭐)

POST/v1/withdrawals/exchange/withdrawal

Create withdrawal with automatic order creation and USDT transfer to exchange service

create-withdrawal.js

const response = await fetch('https://api.fromchain.plus/v1/withdrawals/exchange/withdrawal', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer gw_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: "float",
    fromCcy: "USDTBSC",
    toCcy: "SOLSOL",         // Target currency (e.g., SOL on Solana)
    direction: "from",
    amount: 2,                // Amount in USDT
    toAddress: "98GWnpCm1eFSEYjAzfMXYrcMq21wotokNfed3MnLuKsg"  // Destination address
  })
});

const data = await response.json();
// {
//   "success": true,
//   "data": {
//     "withdrawal": {
//       "id": "349f2f18-3553-4d39-8ce2-ccf973603830",
//       "amount": "2.00",
//       "feeAmount": "0.31",           // Exchange service fee
//       "netAmount": "2.00",           // Your requested amount
//       "destinationAddress": "98GWnp...",
//       "status": "COMPLETED",
//       "chain": "BSC",
//       "token": "USDT",
//       "metadata": {
//         "exchangeOrderId": "2GGHWR",
//         "exchangeToken": "dUi9jl4PMh...",
//         "fromCurrency": "USDTBSC",
//         "toCurrency": "SOLSOL",
//         "depositAddress": "0x3e80...",
//         "depositAmount": "2.00000000",
//         "expectedAmount": "1.69",
//         "exchangeFee": "0.31"
//       }
//     },
//     "exchangeOrder": {
//       "id": "2GGHWR",
//       "status": "NEW",
//       "from": {
//         "code": "USDTBSC",
//         "amount": "2.00000000",     // Total sent to exchange
//         "address": "0x3e80..."      // Exchange deposit address
//       },
//       "to": {
//         "code": "SOLSOL",
//         "amount": "1.69",            // What you'll receive
//         "address": "98GWnp..."       // Your destination
//       },
//       "token": "dUi9jl4PMh..."      // Order token for status checks
//     },
//     "txHash": "0xefe2aaf4..."       // Blockchain transaction hash
//   },
//   "meta": {
//     "timestamp": "2025-12-20T04:39:11.901Z"
//   }
// }

// Access the data:
const { withdrawal, exchangeOrder, txHash } = data.data;

✅ Fully Automated: This endpoint handles everything:

Creates exchange order
Debits your balance (including exchange fees)
Automatically sends USDT to exchange service
Tracks transaction on blockchain
Returns complete withdrawal + order details

💡 Fee Handling: The system calculates total exchange fees and debits the full amount from your balance. For example, if you request 2 USDT and the exchange needs 2.31 USDT total, your balance will be debited 2.31 USDT.

Check Order Status

POST/v1/withdrawals/exchange/order/details

Get details and status of an existing order

order-details.js

const response = await fetch('https://api.fromchain.plus/v1/withdrawals/exchange/order/details', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer gw_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    id: "ABCDEFGH",
    token: "secret_token_from_order_creation"
  })
});

const data = await response.json();
// Returns full order details with current status

Withdrawal Statuses

PENDING

Request received and being processed.

PROCESSING

Transaction submitted to blockchain, waiting for confirmation.

COMPLETED

Funds successfully transferred.

FAILED

Transaction failed. Funds are returned to your balance.