Documentation
Portal

Trading with Customer Accounts

Several account types support tenants — participants who are authorized to trade on an account they don't solely own. This lets platforms enable multi-tenant trading, where one or more authorized participants place orders against a single shared account.

A tenant is a participant authorized to trade on an account they don't solely own, enabling multi-tenant trading against a single shared balance. The account's primary owner holds the funds and ledgers all trades, while each tenant's orders are attributed to them via the trader field. For more information on the supported tenant types on customer accounts, you can refer to documentation here.

Tenant executes a trade on a Customer Account

This section highlights the ledgering of a trade record, when a tenant has executed a trade on Customer Account as an authorized trader.

Pre-requisites:

  • CUST01 participant status is approved in zerohash.
  • CUST02 participant status is approved in zerohash.
  • The newly created account is funded for trading activity.

Create a Customer Account

After both participants are created and in the approved status , use POST /accounts to create a JTIC account with both participants.

  1. The participant_code is the primary account holder, CUST01 in this example.
  2. The participant_code associated with tenant is the second owner for this account, CUST02 in this example, who will be able to place orders on behalf of the JTIC account.

Sample Request:

{
    "participant_code": "CUST01",
    "prefunded": false,
    "tier": "pro",
    "type": "jtic",
    "account_label": "my-label",
    "tenant": ["CUST02"]
}

Sample Response:

{
    "zrn": "zrn:zh:us:accounts:customer:c761fc96-5c44-40d4-8eb2-3fcd5d06754e",
    "participant_code": "CUST01",
    "prefunded": false,
    "tier": "pro",
    "type": "jtic",
    "account_label": "my-label",
    "tenant": ["CUST02"],
    "account_group": "PLAT01"
}
ℹ️

The zrn should be stored for performing future operations on this particular customer account.

Primary or Secondary User Places an Order via CLOB

For a JTIC account, both the primary and the secondary user associated with the JTIC account will have full trading authorization. Please refer to the Central Limit Order Book documentation for instructions on how to place an order via CLOB.

In the example payload below, the zrn for the JTIC account is included, and participant who placed the order is represented by the trader field on the trade object. The trader's participant_code value will be extracted from the order placement request in FIX, tag <50> SenderSubID.

ℹ️

Regardless of which participant placed the order (primary or secondary), the trade will be ledgered with the primary participant's ledger account. In the example below, CUST02 is the participant who is trading on behalf of the JTIC account and CUST01 will be referenced in the ledger, given CUST01 is the primary participant for this JTIC account.

Sample Trade Object

{
  "message": {
    "batch_trade_id": null,
    "trade_id": "ab8603ef-5a66-4c4a-be05-c90e16b5d3ad",
    "client_trade_id": "d9561804-1bb5-4fc2-b195-992a2b8ff7a8",
    "trade_state": "terminated",
    "market_identifier_code": "SCXM",
    "trade_reporter_code": "PLAT00",
    "symbol": "BTC/USD",
    "trade_quantity": "0.00184456",
    "trade_price": "108426.9419265299041506",
    "trade_type": "regular",
    "physical_delivery": true,
    "comment": "",
    "last_update": 1751046915636,
    "transaction_timestamp": 1751046911000,
    "accepted_timestamp": 1751046911764,
    "defaulted_timestamp": null,
    "settled_timestamp": 1751046915603,
    "expiry_timestamp": null,
    "settlement_timestamp": null,
    "settlement_price_index_id": null,
    "contract_size": 1,
    "underlying": "BTC",
    "quoted_currency": "USD",
    "trade_reporter": "PLAT00",
    "platform_code": "PLAT00",
    "product_type": "spot",
    "parties_anonymous": false,
    "bank_fee": null,
    "reporting_party": "PLAT00",
    "settlement_schedule": null,
    "parties": [
      {
        "settling": true,
        "participant_code": "CUST01",
        "side": "buy",
        "asset": "BTC",
        "amount": "null",
        "liquidity_indicator": null,
        "execution_id": "",
        "order_id": "",
        "obligations_outstanding_timestamp": null,
        "current_obligations_met_timestamp": null,
        "settlement_state": "settled",
        "client_order_id": "",
        "collateral_percentage": null,
        "account_label": "general",
        "account_profile": null,
        "zrn": "zrn:zh:us:accounts:customer:c761fc96-5c44-40d4-8eb2-3fcd5d06754e",
        "trader": "CUST02"
      },
      {
        "settling": true,
        "participant_code": "PLAT01",
        "side": "sell",
        "asset": "USD",
        "amount": "null",
        "liquidity_indicator": null,
        "execution_id": "",
        "order_id": "",
        "obligations_outstanding_timestamp": null,
        "current_obligations_met_timestamp": null,
        "settlement_state": null,
        "client_order_id": "",
        "collateral_percentage": null,
        "account_label": "general",
        "account_profile": null,
        "zrn": "zrn:zh:us:accounts:customer:d731ff96-5c44-41d4-8eb0-3dcd5d02764a",
        "trader": "PLAT01"
      }
    ],
    "session_id": "20250627175500",
    "fees": [],
    "issuer_fee_rate": "0",
    "issuer_fee_amount": "0",
    "issuer_fee_payor_type": null,
    "payment_processor": null,
    "network_fee_notional": null,
    "network_fee_quantity": null,
    "total_notional": "200.00",
    "asset_cost_notional": "200.00",
    "spread_notional": "2",
    "spread_bps": "100",
    "origin": "rest_api"
  }
}

Get Account Balances Using the ZRN

To get all ledger accounts associated with the customer account, request GET /accounts endpoint, providing the ZRN query parameter.

Example:

GET /accounts?zrn=zh:us:accounts:customer:c761fc96-5c44-40d4-8eb2-3fcd5d06754e

{
  "message": [
    {
      "zrn": "zrn:zh:us:accounts:ledger:ce819fe8-b1d7-43bb-961c-e09ede0988d3",
      "asset": "USD",
      "account_owner": "ABCDEF",
      "account_type": "available",
      "account_group": "XYZ456",
      "account_label": "general",
      "balance": "1.00",
      "account_id": "ce819fe8-b1d7-43bb-961c-e09ede0988d3",
      "last_update": 1554395972174
    },
    {
      "zrn": "zrn:zh:us:accounts:ledger:ce819fe8-b1d7-43bb-961c-e09ede0988d4",
      "asset": "BTC",
      "account_owner": "ABCDEF",
      "account_type": "available",
      "account_group": "XYZ456",
      "account_label": "general",
      "balance": "0.00000001",
      "account_id": "ce819fe8-b1d7-43bb-961c-e09ede0988d4",
      "last_update": 1554395972174
    }
  ],
  "page": 1,
  "total_pages": 1
}

Get Account Details Using the ZRN

To get customer account details, request GET/accounts/{zrn}/details

Example:

GET /accounts/zh:us:accounts:customer:c761fc96-5c44-40d4-8eb2-3fcd5d06754e/details

{
  "zrn": "zrn:zh:us:accounts:customer:c761fc96-5c44-40d4-8eb2-3fcd5d06754e",
  "participant_code": "CUST01",
  "prefunded": true,
  "account_label": "U12345678",
  "tier": "pro",
  "account_group": "GROUP1",
  "type": "jtic",
  "tenants": ["CUST02"]
}


Updated about 1 hour ago

Did this page help you?