Differentiate the available balance and frozen balance in wallet(s) of AccountInfo?

[rafalkrupinski]

Wallet.getDescription() ?

[lazyp]

I think his mean that add List frozenWallet attr in the AccountInfo class.

[sutra]

About 50% exchanges could differentiate the availableBalance and frozenBalance(lockedBalance, reservedBalance):

15 (anx, bitfinex, bitso, bitstamp, bittrex, bleutrade, btcchina, btctrade, bter, hitbtc, huobi, itbit, loyalbit, okcoin, taurus) of 31(anx, bitcointoyou, bitcurex, bitfinex, bitso, bitstamp, bittrex, bleutrade, btcchina, btce, btctrade, bter, campbx, cexio, clevercoin, coinbase, coinsetter, cryptotrade, crypts, empoex, hitbtc, huobi, itbit, kraken, lakebtc, loyalbit, mercadobitoin, okcoin, poloniex, taurus, vircurex)

Details as below:

anx
currency -> balance, availableBalance

bitcointoyou
currency -> balanceAvailable

bitcurex
currency -> balance

bitfinex
A list of wallet balances:
type (string): "trading", "deposit" or "exchange".
currency (string): Currency 
amount (decimal): How much balance of this currency in this wallet
available (decimal): How much X there is in this wallet that is available to trade.

bitso
  private final BigDecimal mxnBalance;

  private final BigDecimal btcBalance;

  private final BigDecimal mxnReserved;

  private final BigDecimal btcReserved;

  private final BigDecimal mxnAvailable;

  private final BigDecimal btcAvailable;

bitstamp
  private final BigDecimal usdBalance;
  private final BigDecimal btcBalance;
  private final BigDecimal usdReserved;
  private final BigDecimal btcReserved;
  private final BigDecimal usdAvailable;
  private final BigDecimal btcAvailable;

    "btc_available":"6.99990000",
    "usd_reserved":"172.87",
    "btc_balance":"6.99990000",
    "usd_balance":"172.87",
    "usd_available":"0.00"

bittrex
  private BigDecimal available;
  private BigDecimal balance;
  private String currency;
  private BigDecimal pending;

bleutrade
  @JsonProperty("Currency")
  private String Currency;
  @JsonProperty("Balance")
  private BigDecimal Balance;
  @JsonProperty("Available")
  private BigDecimal Available;
  @JsonProperty("Pending")
  private BigDecimal Pending;

btcchina
        "balance": {
            "btc": {
                "currency": "BTC",
                "symbol": "\u0e3f",
                "amount": "0.00100000",
                "amount_integer": "100000",
                "amount_decimal": 8
            },
            "ltc": {
                "currency": "LTC",
                "symbol": "\u0141",
                "amount": "0.00000000",
                "amount_integer": "0",
                "amount_decimal": 8
            },
            "cny": {
                "currency": "CNY",
                "symbol": "\u00a5",
                "amount": "0.00000",
                "amount_integer": "0",
                "amount_decimal": 5
            }
        },
        "frozen": {
            "btc": {
                "currency": "BTC",
                "symbol": "\u0e3f",
                "amount": "0.00000000",
                "amount_integer": "0",
                "amount_decimal": 8
            },
            "ltc": {
                "currency": "LTC",
                "symbol": "\u0141",
                "amount": "0.00000000",
                "amount_integer": "0",
                "amount_decimal": 8
            },
            "cny": {
                "currency": "CNY",
                "symbol": "\u00a5",
                "amount": "0.00000",
                "amount_integer": "0",
                "amount_decimal": 5
            }
        }

btce
        "funds": {
            "usd": 0,
            "rur": 0,
            "eur": 0,
            "btc": 0.1,
            "ltc": 0,
            "nmc": 0
        },

btctrade
{
    "uid": 1,
    "nameauth": 1,
    "moflag": "0",
    "btc_balance": 1,
    "btc_reserved": 2,
    "ltc_balance": 3,
    "ltc_reserved": 4,
    "doge_balance": 5,
    "doge_reserved": 6,
    "ybc_balance": 7,
    "ybc_reserved": 8,
    "cny_balance": 9,
    "cny_reserved": 10
}

bter
{
   "result":"true",
   "available_funds":{
      "BTC":"0.00010165",
      "LTC":"0.00166859",
      "FTC":"0.00003326",
      "CNY":"0.01018463"
   },
   "locked_funds":{
      "LTC":"0.384"
   }
}

campbx
{
    "Total USD":"0.00",
    "Total BTC":"0.10000000",
    "Liquid USD":"0.00",
    "Liquid BTC":"0.00000000",
    "Margin Account USD":"0.00",
    "Margin Account BTC":"0.00000000"
}

cexio
  private final CexIOBalance balanceBTC;
  private final CexIOBalance balanceLTC;
...
  CexIOBalance.available

clevercoin
 [
     {
         "currency": "BTC",
         "balance": "0.00000000",
     },
     {
         "currency": "EUR",
         "balance": "0.00",
     },
 ]

coinbase
{
   "amount":"7.10000000",
   "currency":"BTC"
}

coinsetter
{
    "accountUuid":"c7d6d8f6-79e9-4975-9122-d981cd0602a5",
    "customerUuid":"aa72fa7d-06d6-466f-a141-155b22c5e2dc",
    "accountNumber":"CST0000001",
    "name":"My Bitcoin account",
    "description":"For primary trading",
    "btcBalance":0E-8,
    "usdBalance":1000,
    "accountClass":"TEST",
    "activeStatus":"ACTIVE",
    "approvedMarginRatio":1.0000,
    "createDate":"19/08/2013 18:54:41.571"
}

cryptotrade
        "funds": {
            "usd": "1896.55927015",
            "eur": "0",
            "btc": "12098.91081965",
            "ltc": "1000",
            "nmc": "0",
            "trc": "0",
            "dvc": "0",
            "ppc": "0",
            "ftc": "0",
            "cnc": "0",
            "bqc": "0"
        },

cryptsy
  private final Map<String, BigDecimal> availableFunds;
  private final Map<String, BigDecimal> availableFundsBTC;

empoex
coin(currency) -> amount

hitbtc
{
    "balance": [
        {"currency_code": "BTC","cash": 0.045457701,"reserved": 0.01},
        {"currency_code": "EUR","cash": 0.0445544,"reserved": 0},
        {"currency_code": "LTC","cash": 0.7,"reserved": 0.1},
        {"currency_code": "USD","cash": 2.9415029,"reserved": 1.001}
    ]
}

huobi
  private final BigDecimal availableCny;
  private final BigDecimal availableBtc;
  private final BigDecimal availableLtc;
  private final BigDecimal frozenCny;
  private final BigDecimal frozenBtc;
  private final BigDecimal frozenLtc;
  private final BigDecimal loanCny;
  private final BigDecimal loanBtc;
  private final BigDecimal loanLtc;

itbit
  private final BigDecimal availableBalance;
  private final BigDecimal totalBalance;
  private final String currency;

kraken
currency -> balance

lakebtc
  private final BigDecimal USD;
  private final BigDecimal CNY;
  private final BigDecimal BTC;

loyalbit
{
  "available_usd":1283.24,
  "available_btc":0.72530797,
  "reserved_order_usd":325.8,
  "reserved_order_btc":0,
  "reserved_withdraw_usd":3000,
  "reserved_withdraw_btc":1.0005,
  "fee":"0.0040"
}

mercadobitoin
        "funds": {
            "ltc": "0.00000000",
            "brl": "248.29516",
            "btc": "0.25000000"
        },

okcoin
{
    "result": true,
    "info": {
        "funds": {
            "asset": {
                "net": "0",
                "total": "0"
            },
            "borrow": {
                "btc": "0",
                "cny": "0",
                "ltc": "0"
            },
            "free": {
                "cny": 1000,
                "btc": 10,
                "ltc": 0
            },
            "freezed": {
                "cny": 1000,
                "btc": 10,
                "ltc": 0
            },
            "union_fund": {
                "btc": "0",
                "ltc": "0"
            }
        }
    }
}

poloniex
currency -> balance

taurus
  private final BigDecimal cadBalance;
  private final BigDecimal btcBalance;
  private final BigDecimal cadReserved;
  private final BigDecimal btcReserved;
  private final BigDecimal cadAvailable;
  private final BigDecimal btcAvailable;

vircurex
currency -> availablebalance, ?

[timmolter]

@sutra Nice list! If you want to modify AccountInfo and add that new field, go for it.

[jheusser]

Cool, certainly useful. @sutra if you could keep the current semantics of: balance = available + frozen - borrowed

for the main Wallet that would be good. My main argument is that this defines the boundary of going long vs going short on borrowed money, e.g. you initialise your balance to be 0 with borrowed money like that, short is a negative balance, and long is positive balance.

[sutra]

Considering to add 3 or more fields available, frozen, borrowed, (loan)... to Wallet, and keep the balance be available + frozen - borrowed (+ loan). And add a new method Wallet getWallet(String currency) to AccountInfo.

So for the users, could use: accountInfo.getWallet(Currencies.BTC).getBalance() accountInfo.getWallet(Currencies.BTC).getAvailable() accountInfo.getWallet(Currencies.BTC).getFrozen() accountInfo.getWallet(Currencies.BTC).getBorrowed()

If you has any idea, please feel free to comment.

[rafalkrupinski]

+1, makes description obsolete

[jheusser]

what about user defined wallets such as what itbit / okcoin provide?

[rafalkrupinski]

@jheusser good point, how theses fit into balance = available + frozen - borrowed scheme? hitbtc provides main vs trading accounts, funds in the main account are unavailable for trading, I'd skip it from the balance and available funds, since accessing it requires exchange specific API.

[jheusser]

itbit does not provide borrowing, however you can create an arbitrary number of wallets, with custom wallet id and balances in it. Okcoins borrowing works fine with balance = available + frozen - borrowed.

[rafalkrupinski]

does itbit allow trading with funds on a custom wallet?

[jheusser]

@rafalkrupinski yes

[rafalkrupinski]

Does itbit allow trading with funds on a custom wallet using xchange generic API? If so, how about adding it up as available (and what's its purpose)? Otherwise, can we leave it all to the itbit API?

[jheusser]

in the currently implementation you have to set an exchange specific param defining which wallet id you are currently using for all the API calls. So perhaps we can leave it at that already.

I think adding it all up would not be good. It's used for running multiple strategies on separate wallets without having to have multiple accounts.

[rafalkrupinski]

It still requires the user to use custom API (exchange specific Object... parameter). I believe @sutra has proposed very good generic API, and itbit, okcoin and hitbtc features should be handled separately. Would it be acceptable to put the wallet name in ExchangeSpecification.exchangeSpecificParameters and let AccountInfo return only that wallet?

[sutra]

1. The available should contain the borrowed? I am defining it as the amount of the <code>currency</code> in this wallet that is available to trade. But anyway, if server side provides a value named available, I think we could assign it directly.
2. Which term is better for the amount of the <code>currency</code> in this wallet that is locked in trading.? reserved, locked or frozen? I think reserved is the best.

[rafalkrupinski]

The available should contain the borrowed? I am defining it as the amount of the currency in this wallet that is available to trade.

If it's available for trading then it adds to available :)

Which term is better for the amount of the currency in this wallet that is locked in trading.? reserved, locked or frozen? I think reserved is the best.

Reserved associates with some kind of reserve (stash) to me; I'd prefer (b)locked or inUse

[jheusser]

The available should contain the borrowed? I am defining it as the amount of the currency in this wallet > that is available to trade.

I'm a bit confused. So just to summaries for myself: there will be 4 wallets per currency pair. balance (available + frozen - borrowed), available, frozen, and borrowed. Is that correct?

If so then available should definitely not contain the frozen amount such that things you see via the exchange UI match what you see in API calls.

Which term is better for the amount of the currency in this wallet that is locked in trading.? reserved, locked or frozen? I think reserved is the best.

Frozen is not a very explanatory term but it looks like it's most often used by exchange, so I would go with frozen to easily map back to terms used by exchanges.

[rafalkrupinski]

@jheusser you aren't confused, you're correct :) You can view the balance as your net worth - all that you own. Available amount is what you can use in a new order.

[jheusser]

:+1:

[sutra]

Proposed a PR #923 , a lot of files changed, but only 2 files are important: AccountInfo.java and Wallet.java. I have added only available and frozen now. Could add 2 more borrowed(that we borrowed from the exchange or someone in the exchange) and loan(that we loan to others?).