Release Date
Friday, March 03, 2023
Release Type
Informational – Optional action from platforms.
Summary
Zero Hash is pleased to announce that we have increased support for additional query parameters when using our GET /transfers endpoint. Prior to this launch, Platforms could only query applying a filter for the client_transfer_id.
Action Required
This is a feature that Platforms can opt to use if they are already using transfers to query transfer history. No additional configuration is required.
Endpoints Impacted
GET /transfers
will now support the following query parameters:
-
page
: Optional. This is to allow the Platform to paginate through response payloads. -
page_size
: Optional. Shall dictate the size of the list in the response payloads. -
to_participant_code
: Optional. Filter for transfers that have the participant_code matching what is provided in the query param. -
from_participant_code
: Optional. Filter for transfers that have the participant_code matching what is provided in the query param. -
requested_timestamp
: Optional. Correspond to the created_at date. Requested_timestamp filters movements based on a given timestamp in milliseconds1593798130060
or nanoseconds1593798130060000000
using the following next params for the following filter types:[gt]
: greater than a given timestamp, e.g.requested_timestamp[gt]=1593798130060
[gte]
: greater than or equal to a given timestamp, e.g.requested_timestamp[gte]=1593798130060
[e]
: equal to a given timestamp, e.g.requested_timestamp[e]=1593798130060
[lt]
: less than a given timestamp, e.g.requested_timestamp[lt]=1593798130060
[lte]
: lower than or equal to a given timestamp, e.g.requested_timestamp[lte]=1593798130060
Combinations are also possible, e.g. to find movements between
1593798130555
and1593798130777
you can use the next combinationrequested_timestamp[gt]=1593798130555&requested_timestamp[lt]=1593798130777
Relevant Documentation
N/A
Coming soon
N/A
Release Date
Wednesday, February 1, 2022
Release Type
Informational – No action or changes necessary from platforms.
Summary
Zero Hash has now added an account label query parameter to the following endpoints:
GET /trades
GET /positions
GET /withdrawals/requests
GET /deposits
Prior to this release, platforms were not able to designate a specific account label for these responses and thus received back a larger data set than was needed.
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 two separated BTC accounts, for example.
Platforms are now able to add the account label filter to all of these responses in order to query by account label as well as participant code.
Action Required
Informational – No action or changes necessary from platforms.
Endpoints Impacted
The following endpoints are impacted due to this feature improvement, the change being available in both Cert and Production environments:
GET /trades
GET /positions
GET /withdrawals/requests
GET /deposits
Relevant Documentation
Release Date
Wednesday, February 1, 2023
Release Type
Informational – Please see the “Action Required” section for instructions on enabling this feature.
Summary
Zero Hash has now added the ability for platforms to provide an account label when using the following endpoint:
POST /deposits/digital_asset_addresses
Prior to this release, platforms were not able to designate a specific account label for a digital asset deposit, and thus could not create different on-chain digital asset addresses for a customer that had multiple accounts on their platform.
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 two separated BTC accounts, for example.
Platforms are now able to designate a specific account label when creating multiple digital asset addresses. This functionality is available on a per participant and per asset basis. If Zero Hash receives a new account label within the deposit request, a new on-chain address will be created. Please note that each on-chain address creation event will incur network fees.
Account labels must conform to the following criteria:
- Account labels are case sensitive and can be a maximum of 40 characters
- Only numbers, letters, hyphens, and underscores are allowed.
Sending the same account label with different cases will result in multiple accounts being created.
Action Required
If you would like to enable this feature, please reach out to [email protected]. This will allow our team to properly configure platform settings to create multiple on-chain addresses per participant code per asset.
Endpoints Impacted
The following endpoint is impacted due to this feature improvement, the change being available in both Cert and Production environments:
POST /deposits/digital_asset_addresses
Relevant Documentation
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
- 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 updatedplatform_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:
Scenario | Response |
---|---|
Successfully updated data | 200 + payload of the updated participant record |
Submits data that is not updatable | 400: Cannot update the requested fields: {fields listed} |
Segment requirements were not met | 400: Data segment validation failed. One or more segment fields either invalid or not provided. Segment error: “{required field} required field”, “{field_name} should match format {required format}” |
Participant is not allowed to be updated via this endpoint | 400 - Participant {participant_code} is not a customer |
Platform is not approved to submit participant updates | 403 - Participant {platform_code} is not allowed to submit/update customers |
Relationship does not exist between the platform and participant | 403 - Participant {participant_code} is not a customer of {platform_code} |
Only platform_updated_at is submitted | 400 - platform_updated_at submitted with no data segment to update |
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
:
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
Name | Symbol | Custody | Liquidity | Environment | Type | Precision |
---|---|---|---|---|---|---|
Cardano | ADA | Yes | Yes | Prod | Base | 6 |
Full list of assets supported by Zero Hash can be found here.