API Updates

• The GET /index endpoint has been converted from a public endpoint, to private
• This means that you will only be able to consume /index data via a valid API key
• A new API key permission has been added for index
  • All existing API Keys have been backfilled with read permissions for index

Release Date

Friday, December 16, 2022

Release Type

Actionable – Updates required for platforms that have enabled withdrawals and want to use the new feature.

Summary

Zero Hash now supports additional configurations related to handling network fees for withdrawals. The new model allows platforms to generate a network fee quote and execute it upon approval from the end user. Network fees are quoted and debited based on the requested withdrawal asset, making it easier for end users to understand charges. Network fees are also netted from the requested withdrawal amount, ensuring that end users do not owe more than they request to withdraw.

How It Works

• Platforms need to be configured by Zero Hash for the service.
• Platforms generate a withdrawal quote using GET /withdrawals/locked_network_fee, which returns details about the withdrawal and a withdrawal_quote_id.
• Withdrawal_quote_ids are valid for 30 seconds.
• After the Participant accepts the quote, the Platform executes the quote by passing the withdrawal_quote_id using POST /withdrawals/execute.
• Zero Hash performs ledgering actions, including generating a pending withdrawal and creating a confirmed withdrawal message.

Action Required

Platforms interested in using the feature need to reach out to Zero Hash Customer Service team or Platform Solutions team for additional configurations. This will impact how Platforms execute withdrawals and will require using the aforementioned endpoints to facilitate all withdrawals.

Endpoints Impacted

NEW - GET /withdrawals/locked_network_fee

Accepted Parameters:

• "participant_code" (Required)
• "account_group" (Optional)
• “account_label" (Optional)
• "amount" (Required)
• "max_amount" (Optional)
• "asset" (Required)
• "withdrawal_account_id" (Required if withdrawal_address is not provided)
• "withdrawal_address" (Required if withdrawal_account_id is not provided)
• "destination_tag" (Required for tag-based assets)

Example Request

GET /withdrawals/locked_network_fee?participant_code=CUST01&account_group=PLAT01&account_label=general&amount=0.02&asset=BTC&withdrawal_address=mohjSavDdQYHRYXcS3uS6ttaHP8amyvX78

Example Response

{
 'account_group': 'PLAT01',
 ‘request_id’: 'ac3se065c-a35d-xc3f-s802-2cefaabed6123’',
 'account_label': 'general',
 'amount': '0.02',
 'amount_notional': '339.39',
 'asset': 'BTC',
 'destination_tag': '',
 'max_amount': False,
 'net_withdrawal_notional': '339.34',
 'net_withdrawal_quantity': '0.01999718',
 'network_fee': '0.00000282',
 'network_fee_notional': '0.05',
 'participant_code': 'CUST01',
 'withdrawal_account_id': '',
 'withdrawal_address': 'mohjSavDdQYHRYXcS3uS6ttaHP8amyvX78',
 'withdrawal_quote_id': '53b9065c-185d-4c9f-ba90-2cefaabed6e1'
}

Release Date

Available in Cert as of December 7, 2022

Once Cert testing has been completed, platforms may be approved for Prod use

Release Type

Actionable, non-breaking – Updates required for platforms, but it will not break current functionality

Summary

Zero Hash has added an endpoint (PATCH /participants/customers/{participant_code}) that permits platforms to update certain participant data. This enables address updates to participants, which allows for easier reporting (including tax reporting) and improved end user experience when transacting on the Zero Hash platform.

Important note: This endpoint does not support updating entities, which will come at a later date on a distinct endpoint. Updating authorized minors occurs on a different endpoint that is not public.

Updatable Information

Fixed pieces of participant information are updatable via this new endpoint:

• Name
• Address
• Email
• ID

Zero Hash requires that platforms perform due diligence when a participant updates fundamental pieces of their identity, so a <platform_updated_at> timestamp has been introduced to capture when the platform validated and approved the participant submitted update.

Requirements:
All update requests must include the following. Requests that don’t include the following will fail.

• participant_code – The unique identifier of the participant being updated
• platform_updated_at – A UNIX (ms) timestamp of when the platform verified/accepted the participant requested update

Endpoints Impacted

The addition of this endpoint does not impact the functionality of any other existing endpoints; however, it is inherently tied to POST /participants/customers/new.

New Endpoint:

PATCH /participants/customers/{participant_code}

Seeing as the endpoint request involves a <participant_code>, multiple participants cannot be updated in one call.

Action Required

Platforms are required to backfill data that was previously updated by participants. Platforms should also begin to pass participant updates through as those updates are verified/approved to ensure no disruption in participant access to transactions, and to enable accurate state reporting for Zero Hash. This includes all address updates, not just updates in and out of heavily regulated jurisdictions.

Success and Failure Messages

A platform can send one update at a time (e.g. just address), or multiple (e.g. name and address); however, if segment requirements are not met, the whole update will be declined.

Breakdown:

Restricted Jurisdiction Residents

When updating participant data, platforms may find that a participant is moving from a less restricted jurisdiction to a more heavily restricted jurisdiction, or vice versa. The most prominent example right now is a participant moving to or from New York (NY). Specifically, New York residents can only trade a subset of Zero Hash supported assets.

Participant moves to NY who holds a NY restricted asset:
These participants will be allowed to hold, sell, or withdraw the NY restricted asset at any time. They will not be able to buy, deposit, transfer, or **gain rewards in the NY restricted asset.

Participant moves out of NY:
Once the address update is successful, the participant will be able to make requests for assets that were not available in NY, barring the assets are allowed in the new participant jurisdiction. Platforms are encouraged to get proof of new address across the board, and especially for those leaving NY

Relevant Documentation

Please reference the Participants section of the API documentation.

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.

Release date

Friday, December 2, 2022

Release type

Informational – No action or changes necessary from platforms.

Summary

Zero Hash is excited to expand our support for smart contract calls to include Solana. Previously, Zero Hash supported withdrawals to smart contracts on Ethereum, Polygon, and all EVM-compatible chains.

Action required

No additional action is required. If platforms would like to begin using this feature then they can find further details in the Smart Contracts FAQ.

Endpoints impacted

Withdrawals to smart contracts are invoked via the input_data field when creating a withdrawal request via POST /withdrawals/requests endpoint.

For EVM-compatible chains, the input_data field takes an ABI generated value.

For Solana, the input_data field must be a stringified JSON in the following format:

{  
  \"contract_call_accounts\":[  
   {	\"account\": \"73tMMfb2Y5u848jHX6kr7koH73uZABKc8KnTqfNRno7n\",
  		\"is_signer\": false,
			\"is_writeable\": true
		}
	],  
   \"contract_call_data\": \"E93ebh\"  
}

A sample call including the above format for the input_data field would look like the following:

{
"address":"73tMMfb2Y5u848jHX6kr7koH73uZABKc8KnTqfNRno7n",
"participant_code":"E93ebh",
"amount":".002",
"asset":"SOL",
"account_group":"188IMJ",
"client_withdrawal_request_id":"smart_contract_example_withdrawal_sol",
"input_data":
"{"contract_call_accounts":[{"account": "73tMMfb2Y5u848jHX6kr7koH73uZABKc8KnTqfNRno7n","is_signer": false,"is_writeable": true}], "contract_call_data": "E93ebh"}"
}

Relevant Documentation

Smart Contracts at Zero Hash

Asset Deployment Update

We have deployed all changes needed in order to support Cardano ($ADA) for settlement and liquidity services in both the certification and production environment. This asset is now fully accessible and does not require any additional adjustments to begin using for purposes of settlement, liquidity, or withdrawal.

Cardano is a decentralized blockchain based on peer-reviewed research and highly secure Haskell coding language.

Asset Details

Full list of assets supported by Zero Hash can be found here.

Release Date

Wednesday, November 30, 2022

Release Type

Informational – No action or changes necessary from platforms.

Summary

Zero Hash is excited to launch flexible fee payment configurations for platforms enabling on-chain withdrawals and provisioning crypto deposit addresses. This feature allows the platform to select the currency and entity that pays the blockchain network fee associated with the on-chain action where applicable. These payment configurations are:

• Platform - Crypto: Network fees are covered from the Platform’s reserves for the applicable network fee asset. This has been the default method when withdrawal and deposit functionality is enabled.
• Platform - Fiat: Network fees are covered from the Platform’s fiat reserves for the network fee fiat equivalent. This has been the default method when deposit address functionality is enabled.
• Participant (end-customer) - Crypto Additive: Network fees are covered from the participant crypto balances. When processing withdrawals, network fees are added to the requested withdrawal amount.
• Participant (end-customer) - Crypto Netted: Network fees are denominated in the asset being withdrawn. Network fees are deducted from the requested withdrawal amount.

Action Required

If platforms have deposit address functionality enabled and are satisfied with their current setup, then no action is required. If platforms do not yet have the functionality to create deposit addresses enabled and wish to do so, then they should reach out to their account team and choose the preferred configuration.

Platforms paying for deposit address creation now have additional options to change the way deposit address creation fees are assessed.

Endpoints Impacted

Deposit Address Creation

When a Participant requests a deposit address to be created, the Platform calls POST /deposits/digital_asset_addresses to create a new digital wallet deposit address for the [asset] and [participant_code] provided.

Sample Request

{
   "participant_code": "CUST01",
   "asset": "UNI"
}

Sample Response

{
   "message": {
   "created_at": 1647050013,
   "address": "0x7f41A26C0CB9D5a1e57BE9cF10F8354b77CD8ab3",
   "participant_code": "CUST01",
   "asset": "UNI"
}

Configuration 1: Platform pays in crypto (Default)

The default configuration when enabling deposit addresses is for the Platform to pay for deposit address creation fees in crypto. Zero Hash pays the network fee to create the deposit address, assigns the deposit address to the participant, and deducts the crypto from the platform’s crypto wallet.

Configuration 2: Platform pays in fiat (NEW)

Platforms can still pay for the deposit address creation however choose to deduct fiat. Zero Hash pays the network fee to create the deposit address, assigns the deposit address to the participant, and deducts from the platform’s float account.

Configuration 3: Participant pays in crypto (NEW)

Another newly created configuration option is for Platforms to pass responsibility for the deposit address creation fees to the end user. Zero Hash pays the network fee to create the deposit address, assigns the deposit address to the participant, and deducts the fee from the participant’s crypto account for the chosen asset.

Withdrawals

When using the new Fee Payor configuration for withdrawals (Participant (end-customer) - Crypto Netted), Platforms can now use the new withdrawal endpoints that are used to generate and execute the withdrawal locked network fee quote.

Affected Endpoints:

• GET /withdrawals/locked_network_fee
• POST /withdrawals/execute

To read more about the new withdrawals configuration and endpoint implementation see the article titled “2022-12-15: Netted Withdrawals” under the “Relevant Documentation” section of these release notes.

Summary

Zero Hash has improved the logic and error handling around restricted geo-based jurisdictions.

The enhanced logic exists across API endpoints so tailored rules can be established based on a platform’s setup. Addresses submitted at participant creation (POST /participants/customers/new) are referenced when checking a platform’s restricted vs. enabled jurisdictional rules. Geo-based jurisdiction rules can sweep an entire country, or remain specific to a single state or region.

Jurisdiction logic upholds regulatory standards that Zero Hash and our partners must adhere to. This includes ensuring that only New York approved assets are traded by New York residents for platforms enabled in New York.

As always, platforms should continue to monitor restricted activity as well. If a platform submits a request for a restricted jurisdiction, an error code will be returned noting that the platform or participant are not able to request transactions for that jurisdiction or trade in a specific asset.

Refer here for a full list of error codes.

Endpoints Impacted

• POST /awards/fund
• POST /awards/distribute
• GET /convert_withdraw/rfq
• POST /convert_withdraw/execute
• POST /deposits/digital_asset_addresses
• GET /liquidity/rfq
• POST /liquidity/execute
• POST /participants/customers/new
• POST /participants/customers/minor
• POST /participants/documents
• POST /payments/external_accounts
• POST /rewards
• POST /trades
• POST /trades/batch
• POST /transfers
• POST /withdrawals/requests
• DELETE /withdrawals/requests/:id

Coming Soon

Note: A participant update endpoint shall be released soon, which will enable platforms to update participant data (with supporting evidence) including the address of a customer.

API Updates

• Zero Hash will rate limit based on IP Address
• You will be rate limited once you breach 2,000 requests over a rolling 10 second timeframe, across all endpoints
• Example: If you hit GET /liquidity/rfq 1,000 times and GET /trades 1,001 times over a 5 seconds period, you will be unable to access the API for the next 10 seconds. 11 seconds later, you will be able to access the API again.
• Error Code when the limit is breached: HTTP/1.1 429
• Error Message: Too Many Requests
• The Rate Limit specs above apply to both Prod and Cert

API Updates

General

• We've added a new field to the POST /transfers endpoint called client_transfer_id.
• This is an optional field and when used Zero Hash will complete idempotency checks for previously created transfers to validate that the client_transfer_id has not already been used.
• If providing a value, the client_transfer_id must be unique, we will return an error if the id has ever been used in the past.
• Zero Hash will now return the client_transfer_id when a Platform uses the GET /transfers endpoint.
• If a client_transfer_id was not provided for a transaction, we will return a null value.

Use Cases

This feature is ideal for Platforms that expect to perform a significant volume of transfers and wants to ensure that transfer requests are not duplicated.

API Sequencing

Example Request POST /transfer

{  
    "from_participant_code":"PLAT01",  
    "from_account_group": "PLAT01",  
    "to_participant_code":"CUST01",  
    "to_account_group": "PLAT01",  
    "client_transfer_id": "b8aa391c-6da9-4991-b123-f8d64976c92e",  
    "asset":"USD",  
    "amount":"1.00"  
}

Example Response:

{  
    "message": {  
        "id": 48598,  
        "client_transfer_id": "b8aa391c-6da9-4991-b123-f8d64976c92e",  
        "created_at": "2022-10-13T20:06:29.276Z",  
        "updated_at": "2022-10-13T20:06:29.276Z",  
        "status": "approved",  
        "from_participant_code": "PLAT01",  
        "from_account_group": "PLAT01",  
        "from_account_label": null,  
        "to_participant_code": "CUST01",  
        "to_account_group": "PLAT01",  
        "to_account_label": null,  
        "amount": "1.00",  
        "movement_id": null,  
        "admin_transfer": false,  
        "asset": "USD"  
    }  
}

Example Error Response (duplicate client_transfer_id used):

{  
    "error": true,  
    "message": "Request does not contain an unique client_transfer_id"  
}