Skip to main content

Sub-Balances

Every wallet in TrexWallet maintains four sub-balances per currency. These partitions ensure that funds are properly reserved during multi-step operations, preventing double spending and enabling concurrent transactions.

Sub-Balance Types​

Sub-BalanceFieldDescription
Freefree_balanceAvailable for immediate use — transfers, withdrawals, trading
Income Locklock_in_balanceReserved for pending incoming transactions (e.g., unconfirmed deposits)
Withdrawal Locklock_out_balanceReserved for pending outgoing transactions (e.g., withdrawal in progress)
Orders Locklock_ordersAllocated for open trading orders or active investments

The user balance returned by the API (userBalance) is free_balance + lock_orders — funds the user already controls, including the part currently parked in their own orders.

The available balance (what the user can spend without unlocking something first) is just free_balance.

How Sub-Balances Work​

Withdrawal Example​

When a user initiates a 100 USDT withdrawal:

Before:  free=500  lock_out=0    → Available: 500
Step 1:  free=400  lock_out=100  → Available: 400 (funds reserved)
Step 2:  Blockchain confirms
Step 3:  free=400  lock_out=0    → Available: 400 (withdrawal complete)

The user cannot spend the locked 100 USDT on another operation while the withdrawal is in progress.

Deposit Example​

When a blockchain deposit of 50 BTC is detected but not yet confirmed:

Before:  free=100  lock_in=0     → Total: 100
Step 1:  free=100  lock_in=50    → Total: 150 (but only 100 available)
Step 2:  Confirmations complete
Step 3:  free=150  lock_in=0     → Total: 150 (fully available)

The user can see the pending deposit but cannot spend it until confirmations are complete.

Trading Example​

When a user places a limit order to sell 2 BTC:

Before:  free=5    lock_orders=0  → Available: 5
Step 1:  free=3    lock_orders=2  → Available: 3 (2 BTC reserved for order)
Step 2:  Order partially filled (1 BTC sold)
Step 3:  free=3    lock_orders=1  → Available: 3 (1 BTC still in order)
Step 4:  Order fully filled
Step 5:  free=3    lock_orders=0  → Available: 3 (USDT credited separately)

Why Sub-Balances Matter​

Preventing Double Spending​

Without sub-balances, a user with 100 USDT could simultaneously initiate a 100 USDT withdrawal AND a 100 USDT transfer — both checks would pass because the balance shows 100. Sub-balances solve this by immediately reserving funds.

Enabling Concurrent Operations​

A user can have multiple pending operations at the same time:

  • An open exchange order (lock_orders)
  • A pending withdrawal (lock_out)
  • An incoming deposit (lock_in)

Each operation locks only the specific funds it needs, while the remaining free balance stays available.

Atomic Updates​

Sub-balance changes are atomic: either every balance effect of an operation succeeds or none is applied. Integrators never need to compensate for a partially applied TrexWallet operation.

Sub-Balance in API Responses​

GET /trex/v1/wallet/get_balance returns one entry per currency held by the wallet:

{
  "result": [
    {
      "currency": "USDT",
      "freeBalance": 450.00,
      "lockInBalance": 50.00,
      "lockOutBalance": 100.00,
      "lockOrders": 200.00,
      "userBalance": 650.00,
      "userBalanceBaseEqu": 650
    }
  ],
  "error": null
}
  • userBalance = freeBalance + lockOrders (what the user "owns").
  • userBalanceBaseEqu is the long-integer equivalent in the platform base currency, computed from current rates.
  • lockInBalance and lockOutBalance are not part of userBalance — they belong to the address-transaction layer until confirmed or refunded.
  • Transaction States — which states trigger sub-balance changes
  • Fees — fees are deducted from the free balance
  • Atomicity — guarantees on balance updates