Skip to main content

​
Deposits & Withdrawals

Users fund card spending by depositing funds. This guide covers the deposit and withdrawal flows.

​
How It Works

  1. Each user gets a unique deposit address per chain
  2. Deposits are automatically detected and credited
  3. Credit limit equals deposited value (100% advance rate)
  4. Spending reduces available spending power
  5. Users can withdraw unused funds

​
Supported Chains & Tokens

ChainUSDCUSDTChain ID
PolygonYesYes137
BaseYesYes8453
OptimismYesYes10
ArbitrumYesYes42161
AvalancheYesYes43114

​
Deposits

​
Step 1: Get Deposit Address

curl https://api.ledger.so/v1/users/$USER_ID/contracts \
  -H "Api-Key: $API_KEY"
Response: 
{
  "userId": "user_abc123",
  "contracts": [{
    "chainId": 8453,
    "depositAddress": "0x36561987b391685A09A26068eFBa31D6dFbfC530",
    "tokens": [{
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "symbol": "USDC",
      "balance": "0.00"
    }]
  }]
}

​
Step 2: Send Tokens

Transfer USDC or USDT to the depositAddress on your preferred chain.
Send tokens to the correct chain! Each deposit address only works on its specific chain.

​
Step 3: Verify Balance

curl https://api.ledger.so/v1/users/$USER_ID/balance \
  -H "Api-Key: $API_KEY"
Response: 
{
  "userId": "user_abc123",
  "creditLimit": 10000,
  "pendingCharges": 0,
  "postedCharges": 0,
  "balanceDue": 0,
  "spendingPower": 10000
}
Balance updates within a few minutes of the deposit confirming on-chain.

​
Understanding Balance Fields

FieldDescription
creditLimitTotal deposited value in cents
pendingChargesAuthorized but not settled
postedChargesSettled transactions
balanceDueAmount to be repaid
spendingPowerAvailable for new transactions
Formula: 
spendingPower = creditLimit - pendingCharges - postedCharges

​
Withdrawals

Users can withdraw unused funds at any time.

​
Check Available Balance

Before withdrawing, ensure spendingPower covers the amount: 
curl https://api.ledger.so/v1/users/$USER_ID/balance \
  -H "Api-Key: $API_KEY"

​
Create Withdrawal

curl -X POST https://api.ledger.so/v1/users/$USER_ID/withdrawals \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": 8453,
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": 5000,
    "recipientAddress": "0x..."
  }'
FieldTypeRequiredDescription
chainIdnumberYesChain to withdraw on
tokenAddressstringYesToken contract address
amountnumberYesAmount in cents
recipientAddressstringNoDestination wallet address
Response: 
{
  "id": "withdrawal_xyz",
  "userId": "user_abc123",
  "chainId": 8453,
  "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": 5000,
  "recipientAddress": "0x...",
  "transactionHash": "0x...",
  "status": "submitted"
}

​
Withdrawal Status

StatusDescription
pendingAwaiting processing
submittedTransaction submitted to network
confirmedTransaction confirmed on-chain
failedTransaction failed

​
List Withdrawals

curl https://api.ledger.so/v1/users/$USER_ID/withdrawals \
  -H "Api-Key: $API_KEY"

​
Webhooks

Subscribe to deposit and withdrawal events:
EventDescription
deposit.receivedFunds received and credited
deposit.address_readyDeposit address available
withdrawal.submittedWithdrawal transaction submitted
withdrawal.confirmedWithdrawal confirmed on-chain
withdrawal.failedWithdrawal failed
user.balance.updatedCredit limit or spending power changed

​
Sandbox Testing

In sandbox, use test tokens (rUSD) instead of real USDC:
ChainrUSD Contract
Base Sepolia0x10b5Be494C2962A7B318aFB63f0Ee30b959D000b
Optimism Sepolia0x915F8c4a8b9fE793b3185c4186F716d7e5D891b6
Arbitrum Sepolia0xd116d4752fc50D660FB5b5c801448Ae84B4937bc
To get test tokens:
  1. Go to the block explorer for the rUSD contract
  2. Connect your wallet
  3. Call mint(amount) (max 100 tokens per transaction)
  4. Transfer to the user’s depositAddress
rUSD has 6 decimals like USDC. To mint 100 rUSD, call mint(100000000).

​
Best Practices

Use user.balance.updated webhooks to track credit changes in real-time.
Always verify spendingPower before issuing cards or making large purchases.
Withdrawal transactions can fail due to network issues. Implement retry logic.