Account Labels Added to New Endpoints

Release Date

Thursday, December 1, 2022

Release Type

Informational – No action or changes necessary from platforms.

Summary

Zero Hash has now added the ability for platforms to provide an account label when using the following endpoints:

POST /liquidity/RFQ
POST /rewards
POST /withdrawals/requests

Prior to this release, platforms were able to create and pass account labels to ZH using only the POST /trades and POST /transfers endpoints, as well as look up account labels using GET /accounts.

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 have 2 separated BTC available accounts, for example.

Most platforms use a UID such as an account number as the customer's unique account label. Account labels can be automatically created as they get used for both the POST /liquidity/RFQ,POST /rewards and POST /trade endpoints.

Please note, the POST /withdrawals/requests endpoint does NOT automatically create a new endpoint since a withdrawal would need to have had an account label created previously.

Previously, there was no way to designate a particular account when leveraging the specified endpoints, which limited the ability of platforms to offer separated accounts for end users. Platforms were only able to pass an account label using the POST /trades and POST /transfers endpoints.

Now, however, platforms are able to pass the account label value within these endpoints. They are also able to create the new account label automatically when using POST /rewards and POST /liquidity/rfq endpoints.

Limitations: Account labels are case sensitive with a 40 character limit, and will create two separate account labels if the same characters are sent at separate times using both upper and lower case. Only numbers, letters, and underscores are allowed.

Action Required

There is no action needed by platforms, as this is not a breaking change. If no unique account label is passed within the endpoint, the account label will default to the standard "general" label.

Endpoints Impacted

The following endpoints are impacted due to this feature improvement, the change being available in both Cert and Production environments:

POST /liquidity/RFQ
POST /rewards
POST /withdrawals/requests

Example Response of `POST /liquidity/execute` with `'test1'` as `account_label`:

{  
  "message": {  
    "request_id": "11b30347-d6e8-4147-87e6-7d5853ab568b",  
    "quote": {  
      "request_id": "f1051d64-399f-4753-b673-12e08c2b4d72",  
      "participant_code": "ABC123",  
      "quoted_currency": "USD",  
      "side": "buy",  
      "quantity": "0.01570402",  
      "price": "1273.5592542546430787",  
      "quote_id": "276fe1d6-1d6f-4660-b700-53b32fc19d80",  
      "expire_ts": 1669928253926,  
      "account_group": "00SCXM",  
      "account_label": "general",  
      "obo_participant": {  
        "participant_code": "XYZ123",  
        "account_group": "ABC123",  
        "account_label": "test1"  
      },  
      "underlying": "ETH",  
      "asset_cost_notional": "20",  
      "transaction_timestamp": 1669928231216  
    },  
    "trade_id": "a8a21bff-71da-4f95-a0f8-246a356b4e71",  
    "status": "Completed",  
    "trade_ids_list": [  
      "a8a21bff-71da-4f95-a0f8-246a356b4e71"  
    ]  
  }  
}

Relevant Documentation

Phase 1 Account Label release notes here.