Skip to main content

Get Balance

Retrieves the available balance for a specific cryptocurrency in your Gate.io spot trading account. Essential for checking funds before placing orders or monitoring your portfolio.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.
info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs​

  • Client Id - The unique client identifier from the Connect node. Can be left empty if using direct credentials.
  • Currency - The currency code to check balance for (e.g., BTC, USDT, ETH, GT).

Options​

  • Api Key - Gate.io API key credential (optional if using Client Id from Connect node).
  • Secret Key - Gate.io API secret key credential (optional if using Client Id from Connect node).

Output​

  • Result - A string representing the available balance for the specified currency (e.g., "1.5" for 1.5 BTC).

How It Works​

The Get Balance node executes the following steps:

  1. Authenticates using either Client Id or direct credentials
  2. Validates that the Currency is not empty
  3. Queries Gate.io spot account API for the specified currency
  4. Extracts the available balance (not locked in orders)
  5. Returns the balance as a string

Requirements​

  • Either a valid Client Id from Connect node OR API credentials
  • Valid currency code that exists on Gate.io
  • Read permissions on your API key

Error Handling​

The node will return specific errors in the following cases:

  • ErrInternal - Failed to retrieve input parameters
  • ErrInvalidArg - Currency is empty
  • ErrListSpotAccounts - Failed to retrieve balance data or currency not found

Usage Notes​

  • The returned balance is the available amount (not locked in open orders)
  • Balance is returned as a string to preserve decimal precision
  • If the currency doesn't exist in your account, an error is returned
  • The currency code must be exact (e.g., BTC not btc or Bitcoin)
  • This retrieves spot wallet balance only (not margin, futures, or other wallets)
  • Balance shown is net of any locked funds in open orders

Best Practices​

  • Check balance before placing buy/sell orders to avoid insufficient balance errors
  • Store balance in variables for calculations
  • Convert balance string to number for mathematical operations
  • Use in loops to monitor balance changes
  • Implement proper error handling for non-existent currencies
  • Cache balances when making multiple reads to reduce API calls
  • Check balances for both base and quote currencies before trading

Example Usage Scenarios​

Check Single Currency Balance​

Inputs:
- Client Id: (from Connect node)
- Currency: USDT

Output: "1000.50" (you have 1000.50 USDT available)

Check Bitcoin Balance​

Inputs:
- Client Id: (from Connect node)
- Currency: BTC

Output: "0.05" (you have 0.05 BTC available)

With Direct Credentials​

Inputs:
- Client Id: (empty)
- Currency: ETH

Options:
- Api Key: (your credential)
- Secret Key: (your credential)

Output: "2.5" (you have 2.5 ETH available)

Example Flow: Pre-Trade Balance Check​

[Connect]
    |
    +-> [Get Balance: USDT]
    |     |
    |     +-> [Store: usdt_balance]
    |
    +-> [Get Price: BTC_USDT]
    |     |
    |     +-> [Store: btc_price]
    |
    +-> [Calculate: max_btc = usdt_balance / btc_price]
    |
    +-> [If: max_btc >= 0.001]
    |     |
    |     +-> True: [Buy Order: 0.001 BTC]
    |     +-> False: [Log: Insufficient balance]
    |
    +-> [Disconnect]

Example Flow: Portfolio Monitor​

[Connect]
    |
    +-> [Get Balance: BTC]
    +-> [Get Balance: ETH]
    +-> [Get Balance: USDT]
    |
    +-> [Get Price: BTC_USDT]
    +-> [Get Price: ETH_USDT]
    |
    +-> [Calculate Total Portfolio Value]
    |     |
    |     +-> BTC value = btc_balance * btc_price
    |     +-> ETH value = eth_balance * eth_price
    |     +-> Total = BTC value + ETH value + USDT balance
    |
    +-> [Store in Database]
    +-> [Send Report Email]
    |
    +-> [Disconnect]

Example Flow: Balance Alert System​

[Connect]
    |
    +-> [Schedule: Every hour]
    |     |
    |     +-> [Get Balance: USDT]
    |     |
    |     +-> [If: balance < minimum_threshold]
    |           |
    |           +-> True: [Send Alert Notification]
    |           +-> False: [Log: Balance OK]
    |
    +-> [Disconnect]

Example Flow: Multi-Currency Balance Check​

[Connect]
    |
    +-> [Set: currencies = ["BTC", "ETH", "USDT", "GT"]]
    |
    +-> [For Each: currency in currencies]
    |     |
    |     +-> [Get Balance: currency]
    |     +-> [Store: balance_map[currency] = result]
    |     +-> [Log: {currency}: {result}]
    |
    +-> [Return: balance_map]
    |
    +-> [Disconnect]

Working with Balance Values​

Since balance is returned as a string, convert it for calculations:

// In a JS node
const balance = msg.result; // "1000.50"
const balanceNum = parseFloat(balance); // 1000.50
const canBuy = balanceNum >= 100; // true

Calculating Buying Power​

To determine how much you can buy:

[Get Balance: USDT] -> balance = "1000"
[Get Price: BTC_USDT] -> price = {last: "50000"}
[Calculate]
  btc_buyable = parseFloat(balance) / parseFloat(price.last)
  // btc_buyable = 0.02 BTC

Understanding Available vs Total Balance​

  • Available Balance (returned by this node): Amount you can use for new orders
  • Locked Balance: Amount reserved in open orders
  • Total Balance: Available + Locked

If you have 10 BTC total:

  • 8 BTC available (returned by Get Balance)
  • 2 BTC locked in open sell orders
  • 10 BTC total

Common Errors and Solutions​

Currency Not Found​

Error: ErrListSpotAccounts - No balance. Please check the name of the currency
Solutions:
- Verify currency code is correct (case-sensitive)
- Use exact symbol: "BTC" not "btc" or "Bitcoin"
- Currency may not exist on Gate.io
- You may have never traded this currency (zero balance still returns 0, not error)

Invalid Currency Code​

Error: ErrInvalidArg - Currency cannot be empty
Solutions:
- Ensure Currency input is provided
- Check variable is set correctly
- Verify no typos in currency code

Balance Precision​

Gate.io returns balances with high precision:

  • BTC: typically 8 decimal places
  • USDT: typically 2-8 decimal places
  • Other cryptos: varies by currency

Always preserve precision by keeping as string until calculations are needed.

Example: Safe Order Placement​

[Connect]
    |
    +-> [Get Balance: USDT]
    |     |
    |     +-> [Store: available_usdt]
    |
    +-> [Calculate: order_amount = available_usdt * 0.95]
    |     (Use only 95% to leave buffer for fees)
    |
    +-> [Get Price: BTC_USDT]
    |
    +-> [Calculate: btc_to_buy = order_amount / price]
    |
    +-> [Buy Order]
    |     Inputs:
    |     - Order Amount: btc_to_buy
    |     - Order Price: (market price)
    |
    +-> [Disconnect]
  • Connect - Establishes the client session needed for this node
  • Buy Order - Use balance check before buying
  • Sell Order - Check cryptocurrency balance before selling
  • Get Price - Combine with balance to calculate buying power
  • List My Orders - See where locked balance is allocated