This guide will explain how a platform can support multiple commission structures depending on a customers account tier. For example, "pro" account are charged a X bps commission as a flat fee, "lite" accounts are charged a X bps commission applied as a spread.

See core product page here

Setup

In this guide, the Platform is setup to use the CLOB .

The "pro" and "lite" commission rates are communicated to the Zero Hash team and pre-configured in the trading system.

The platform will have two FIX Market Data connections.

• The first market data connection will return the raw order book updates for "pro" users.
• The second market data connection will show the order book adjusted by spread for "lite" users.

The market data connections are distinguished by the SenderCompID.

• [platformName]-RAW
• [platformName]-ADJUSTED

It is important to make sure you "pro" users are routed to the "RAW" market data connection, and the "lite" users are routed to the "ADJUSTED" market data connection.

Flow

In this example, the Platform is configured to have support CLOB trading and creation of both pre-funded and non pre-funded accounts. Summary of all involved participants:

• Platform (participant_code: PLAT01)
• End Customer 1 (participant_code: CUST01)
  • Customer 1 Account Label (participantcode: _custom-account-label-1)
• End Customer 2 (participant_code: CUST02)
  • Customer 2 Account Label (participantcode: _custom-account-label-2)

Submit customer

Example request - POST /participants/customers/new

{
"first_name": "John",
"last_name": "Smith",
"email": "jsmith@example.com",
"phone_number": "9545551234",
"address_one": "1 Main St.",
"address_two": "Suite 1000",
"city": "Chicago",
"state": "IL",
"zip": "12345",
"country": "United States",
"date_of_birth": "1985-09-02",
"citizenship": "United States",
"tax_id": "123456789",
"risk_rating": "low",
"kyc": "pass",
"kyc_timestamp": 1630623005000,
"sanction_screening": "pass",
"sanction_screening_timestamp": 1630623005000,
"idv": "pass",
"liveness_check": "pass",
"signed_timestamp": 1630623005000,
"metadata": {},
}

There may be situations where the Platform is restricted from submitting Customers who reside in certain jurisdictions (ie, New York). The Platform will receive an error that looks like:

{
    "errors": [
        "The submitting platform is not allowed to operate in the participant's resident state",
        "participant is not in an allowed jurisdiction"
    ]
}

The preferred approach is for the Platform to not allow Customers to onboard on their side (through a feature flag, for example). However, if a request with a Customer in a blocked jurisdiction does get submitted to Zero Hash via API, the Platform should fail gracefully and display a descriptive error message on-screen.

Create Account - POST /clob/accounts

Example request

{
  "participant_code": "CUST01",
  "prefunded":true,
  "account_label": "custom-account-label-1",
  "account_tier": ["gold"], //gold represents "pro" accounts, empty array means no tier and will default to "lite" commission
}

Interpretation of this request - an account for end customer (CUST01) is being created with the custom-account-label-1 account label. This is a prefunded account, and their trades will charged the pro/gold commission rate.

Example response - POST /clob/accounts

{
  "message": {
    "participant_code": "PLAT01",
    "prefunded": true,
    "account_label": "custom-account-label-1",
    "account_group": "CUST01",
    "account_tier": ["gold"]
  }
}

Update an Existing Account - PATCH /clob/accounts

Example request

{
  "participant_code": "CUST01",
  "prefunded":true,
  "account_label": "custom-account-label-1",
  "account_tier": [], //empty array will remove the tier
}

Interpretation of this request - an account for end customer (CUST01) is being updated with the custom-account-label-1 account label. This is a prefunded account, and their trades will charged the pro/gold commission rate.

Example response - PATCH /clob/accounts

{
  "message": {
    "participant_code": "PLAT01",
    "prefunded": true,
    "account_label": "custom-account-label-1",
    "account_group": "CUST01",
    "account_tier": []
  }
}

Retrieve List of Existing Accounts - GET /clob/accounts

Example request

Optional query parameters include:

• participant_code
• account_label

{
  "participant_code": "CUST01",
  "account_label": "custom-account-label-1"
}

Example response - GET /clob/accounts

{
  "accounts":[
    {
      "participant_code":"CUST01",
      "account_group":"PLAT01",
      "account_label":"custom-account-label-1",
      "prefunded":true,
      "account_tier":[], //empty array will remove the tier
    }
  ],
  "next_page":0
}

Market Data Subscriptions - FIX API (35=V)

In this example, the platform should have two market data sessions setup. "Pro" customers that have account_tier = "gold" should view the market data via the [platformName]-RAW session to see the unadjusted order book.

Customers who do not have "pro" should be routed to view the market data via the [platformName]-ADJUSTED session to see the adjusted by spread order book.