Wallet API

Balance management, deposits, and withdrawals.

Get Balances

Retrieve balances for all subaccounts.

Endpoint: get_balances() -> Result<vec SubaccountBalances> (query)

Response

type SubaccountBalances = record {
  subaccount_id: nat8;
  balances: vec record { record { text; Blockchain }; Balance };
};

type Balance = record {
  available: nat;
  locked: nat;
  deposit_address: text;
  last_synced_at: nat64;
};

Example

const result = await backend.get_balances()
if ('Ok' in result) {
  result.Ok.forEach((subaccount) => {
    console.log(`Subaccount ${subaccount.subaccount_id}:`)
    subaccount.balances.forEach(([[asset, blockchain], balance]) => {
      console.log(`  ${asset} (${Object.keys(blockchain)[0]}):`)
      console.log(`    Available: ${balance.available}`)
      console.log(`    Locked: ${balance.locked}`)
    })
  })
}

Get Deposit Address

Get the deposit address for a specific asset/blockchain.

Endpoint: get_deposit_address(asset: text, blockchain: opt Blockchain, subaccount_id: opt nat8) -> Result<text> (query)

Example

const result = await backend.get_deposit_address(
  'USDT',
  [{ Solana: null }],
  [0]
)
if ('Ok' in result) {
  console.log(`Deposit USDT (Solana) to: ${result.Ok}`)
}

Update Balance

Trigger a balance sync for a specific asset. Use after deposits.

Endpoint: update_balance(asset: text, blockchain: opt Blockchain, subaccount_id: opt nat8) -> Result<Balance>

Example

// After depositing, sync the balance
const balance = await backend.update_balance(
  'SOL',
  [{ Solana: null }],
  [0]
)
if ('Ok' in balance) {
  console.log(`New balance: ${balance.Ok.available}`)
}

Request Withdrawal

Initiate a withdrawal to an external address.

Endpoint: request_withdrawal(request: WithdrawRequest) -> Result<nat64>

Request

type WithdrawRequest = record {
  asset: text;
  blockchain: Blockchain;
  address: text;
  amount: nat;
  subaccount_id: nat8;
};

Example

const result = await backend.request_withdrawal({
  asset: 'USDT',
  blockchain: { Solana: null },
  address: 'YOUR_SOLANA_ADDRESS',
  amount: 100_000000n, // 100 USDT (6 decimals)
  subaccount_id: 0,
})

if ('Ok' in result) {
  console.log(`Withdrawal request ${result.Ok} submitted`)
}

Get Withdrawal

Check the status of a specific withdrawal.

Endpoint: get_withdrawal(id: nat64) -> Result<opt Withdrawal> (query)

Response

type Withdrawal = record {
  id: nat64;
  account_id: nat64;
  subaccount_id: nat8;
  asset: text;
  blockchain: Blockchain;
  address: text;
  amount: nat;
  fee: nat;
  status: WithdrawalStatus;
  status_message: opt text;
  transaction_id: opt text;
  retry_count: nat8;
  created_at: nat64;
  trigger_at: nat64;
};

type WithdrawalStatus = variant {
  Pending;
  Processing;
  Confirmed;
  Failed;
};

Example

const withdrawal = await backend.get_withdrawal(12345n)
if ('Ok' in withdrawal && withdrawal.Ok[0]) {
  const w = withdrawal.Ok[0]
  console.log(`Status: ${Object.keys(w.status)[0]}`)
  if (w.transaction_id[0]) {
    console.log(`TX: ${w.transaction_id[0]}`)
  }
}

List Withdrawals

List all withdrawals for the current user.

Endpoint: list_withdrawals() -> Result<vec Withdrawal> (query)

const result = await backend.list_withdrawals()
if ('Ok' in result) {
  result.Ok.forEach(w => {
    console.log(`${w.id}: ${w.amount} ${w.asset} - ${Object.keys(w.status)[0]}`)
  })
}

Best Practices

Deposits

1. Always verify the deposit address before sending funds
2. Check minimum deposit amounts per token
3. Call update_balance() after deposit to sync
4. Wait for blockchain confirmations

Withdrawals

1. Verify the destination address is valid
2. Check withdrawal limits and fees
3. Monitor withdrawal status
4. Store the withdrawal ID for tracking

Balance Management

• Use subaccounts for portfolio isolation
• Track available vs locked balances
• Locked funds are reserved for open orders