Articles in this section

See more

What is an Account Label?

  • Updated

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:

We are now adding a 5th attribute: account_label.

mceclip0.png

Release notes can be found here.

 

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 Platform's standard brokerage product to make this purchase:

{ 
   "symbol":"BTC/USD",
   "trade_price":"60000.00000",
   "product_type":"spot",
   "trade_type":"regular",
   "trade_reporter":"reporter@platform.com",
   "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 .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":"reporter@platform.com",
   "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 .5.

 

GET requests involving Account Labels

API Docs

View balances: GET /accounts

  • New field account_label in response
  • You have the ability to filter your request by account_label

View outstanding positions: GET /accounts/net_delivery_obligations

  • New field account_label in response

View balances of a specific account id: GET /accounts/:account_id

  • New field account_label in response

View deposit history: GET /deposits

  • New field account_label in response

View positions: GET /positions

  • New field account_label in response

 

Transferring funds between Account Labels

  • Note: 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"
}

 

Related articles