Account Labels

Background

Account Labels can be thought of as “sub account groups”. Within each account group, you can have many Account Labels. They are used to separate funds at a more granular level. One individual can now have 2 separated BTC available accounts, for example.

The default account_label value is general.

Prior to our launch of Account Labels, Accounts were a unique combination of the following attributes:

  • participant_code
  • asset
  • account_type
  • account_group

We are now adding a 5th attribute:

  • account_label

Creating a new Account with a new Account Label

Accounts are created when you use them. If you deposit BTC, we will create your BTC Accounts. Same idea with trades and transfers.

To create a new Account that has a new (non-'general') Account Label, you will specify the name on the POST /trades call. The field name is account_label and it is optional.

Example

Let's say you operate the participant, "Trading Platform" and the participant_code is ABC123. You start by creating a retail customer, "John Smith" and Zero Hash responds and gives John the participant_code DEF456. At this point, John Smith has zero accounts in our system.

Trading Platform submits a trade where John Smith is purchasing BTC without an Account Label. John is using Trading Platforms standard brokerage product to make this purchase:

{ 
   "symbol":"BTC/USD",
   "trade_price":"60000.00000",
   "product_type":"spot",
   "trade_type":"regular",
   "trade_reporter":"[email protected]",
   "platform_code":"ABC123",
   "client_trade_id":"test1",
   "physical_delivery":true,
   "parties_anonymous":false,
   "transaction_timestamp":1569014063570,
   "parties":[ 
      { 
         "participant_code":"DEF456",    //<-- customer's participant_code
         "asset":"BTC",
         "amount":"0.1",
         "side":"buy",
         "settling": true
      },
      { 
         "participant_code":"ABC123",    //<-- platform's participant_code
         "asset":"USD",
         "amount":"6000.0000",
         "side":"sell",
         "settling": false
      }
   ]
}

Zero Hash has now created a BTC account for John Smith. Example details:

  • participant_code: DEF456
  • asset: BTC
  • account_type: available
  • account_group: ABC123
  • account_label: general

John's balance in this account is 0.1.

A couple weeks later, John creates an IRA account with Trading Platform and would like to make a larger BTC purchase within this new account. Trading Platform will submit a new trade, specifying an account_label:

{ 
   "symbol":"BTC/USD",
   "trade_price":"61000.00000",
   "product_type":"spot",
   "trade_type":"regular",
   "trade_reporter":"[email protected]",
   "platform_code":"ABC123",
   "client_trade_id":"test1",
   "physical_delivery":true,
   "parties_anonymous":false,
   "transaction_timestamp":1569014083570,
   "parties":[ 
      { 
         "participant_code":"DEF456",   
         "asset":"BTC",
         "amount":"0.5",
         "side":"buy",
         "settling": true,
         "individual_taxable": "individual_tax_advantaged" <-- see here
      },
      { 
         "participant_code":"ABC123",   
         "asset":"USD",
         "amount":"30500.0000",
         "side":"sell"
         "settling": false
      }
   ]
}

Zero Hash has now created a 2nd BTC account for John Smith. Details:

  • participant_code: DEF456
  • asset: BTC
  • account_type: available
  • account_group: ABC123
  • account_label: individual_tax_advantaged

John's balance in this account is 0.5.


GET requests involving Account Labels

View balances:

  • GET /accounts
    • New field account_label in response.
    • You have the ability to filter your request by account_label

View outstanding positions:

View balances of a specific account id:

View deposit history:

View positions:

Transferring funds between Account Labels

  • You will need to notify Zero Hash that you wish to use this feature, a configuration is required.
  • Once configured, you can use the POST /transfers endpoint. Here is an example request where you are transferring funds intra-participant from the general account_label to the joint account_label:
{
  "from_participant_code":"DEF456",
  "from_account_group":"ABC123",
  "from_account_label":"general",
  "to_participant_code":"DEF456",
  "to_account_group":"ABC123",
  "to_account_label":"joint",
  "asset":"BTC",
  "amount":".01"
}