Release date

Production - June 26th, 2025

📘

This feature was released to our Cert environment on June 20th, 2025

Release type

Informational – Optional action from platforms.

Summary

  • You can now set your own identifier (reference_id) when generating JWT tokens for the Account Funding SDK.
  • For the Account Funding API (POST /fund/rfq), the same functionality is offered through the newly added client_fund_id param. The name slightly deviates on the API versus the modal in order to be consistent with previously existing similar fields on other endpoints.
  • Zerohash will store this reference_id / client_fund_id and associate it with any future fund events and webhooks.
  • The reference_id is always tied to the most recent fund session. For example, if the SDK is invoked at 12:00 with reference_id = "abc123" but the user does not complete a deposit during that session, the reference_id remains associated with the session.
  • If the user later sends a deposit to the address from that session - say, at 2:00 PM, perhaps using an address they saved earlier - the resulting webhook event will still include reference_id = "abc123". Likewise, this same reference_id will appear in the fund event returned by the GET /fund/transactions endpoint.

Use Cases

  • Attributing deposits to specific user actions or campaigns, brokerages and neobanks can use the reference_id to track whether a deposit originated from a specific in-app prompt, bonus program, marketing campaign, or onboarding flow.
  • Reconciling fund events with internal transaction IDs: Platforms can embed their own transaction or session identifiers in the reference_id, simplifying back-office reconciliation and support workflows.
  • Tracking deposit behavior across time: Since the reference_id persists even if a user delays funding, platforms (ie, sports betting apps) can still attribute the deposit to the original context or user action, enabling delayed conversion tracking.
  • Managing fraud and risk workflows: card programs and fintechs can flag or review specific funding sessions by embedding a risk score or workflow reference into the reference_id, helping tie later deposits to earlier risk decisions.

Example

Account Funding SDK

{
    "participant_code": "CUST01",
    "permissions": ["fwc"],
    "reference_id": "abc123"
}
  • The Platform displays the SDK to the End Customer
  • The End Customer selects the asset + network and generates a deposit address
  • The End Customer deposits on-chain to the address
  • Zerohash will send a webhook like so:
{
  "participant_code": "CUST01",
  "fund_asset": "USDC.ETH",
  "rate": "1",
  "quoted_currency": "USD",
  "source_address": "0xd3c5967d94d79F17bDc493401c33f7e8897c5f81",
  "deposit_address": "0x34f53Aea3ba8b60B0ed19106baF43A4f3F73f242",
  "quantity": "100",
  "notional": "100",
  "success": true,
  "status_reason": "",
  "fund_timestamp": 1750404740514,
  "deposit_timestamp": 1750404905037,
  "transaction_id": "0xcd9e98ae631cf7cfcf4d351374337a55096abd01d9637303aaef31d5c0766569",
  "account_label": "general",
  "fund_id": "363b5b15-02bd-4797-892f-8baa4eec60d9",
  "is_first_deposit": false,
  "raw_fee_bps": "",
  "deposit_fee_bps": "",
  "raw_fee_notional": "",
  "deposit_fee_notional": "",
  "deposited_asset": "USDC",
  "reference_id": "abc123"
}

Account Funding API

{
    "participant_code": "CUST01",
    "fund_asset": "USDC.ETH",
    "client_fund_id": "abc123"
}
  • The Platform displays the address from the response to the End Customer
  • The End Customer deposits on-chain to the address
  • Zerohash will send a webhook like so:
{
  "participant_code": "CUST01",
  "fund_asset": "USDC.ETH",
  "rate": "1",
  "quoted_currency": "USD",
  "source_address": "0xd3c5967d94d79F17bDc493401c33f7e8897c5f81",
  "deposit_address": "0x34f53Aea3ba8b60B0ed19106baF43A4f3F73f242",
  "quantity": "100",
  "notional": "100",
  "success": true,
  "status_reason": "",
  "fund_timestamp": 1750404740514,
  "deposit_timestamp": 1750404905037,
  "transaction_id": "0xcd9e98ae631cf7cfcf4d351374337a55096abd01d9637303aaef31d5c0766569",
  "account_label": "general",
  "fund_id": "363b5b15-02bd-4797-892f-8baa4eec60d9",
  "is_first_deposit": false,
  "raw_fee_bps": "",
  "deposit_fee_bps": "",
  "raw_fee_notional": "",
  "deposit_fee_notional": "",
  "deposited_asset": "USDC",
  "reference_id": "abc123" <-- correlates to the client_fund_id
}

Action required

  • n.a

Endpoints impacted

Relevant documentation

Release Details

  • Release Date: June 25, 2025

Release Type

Informational – Optional action from platforms

Summary

Zero Hash is pleased to announce enabling support for USDC on Worldchain. This asset uses the symbol USDC.WORLDCHAIN and is available to buy, sell, deposit, and withdraw on PROD.

Note that this asset is not available in New York.

Action Required

This asset is immediately available using the above symbol.

Endpoints Impacted

There are no changes to existing endpoints as a result of this launch.

Relevant Documentation

For a full list of supported assets and instruments, please use the links below.

Release date

June 18th, 2025

Release type

Action is required if you currently use the Account Funding: Withdrawals product or the Payouts product. There is a new conformance test scenario to ensure you're treating the new statuses correctly

Summary

Zero Hash is introducing 2 new payment statuses, applicable to SDK integrations only (specifically if permission = crypto-withdrawals or crypto-payouts):

  • initialized - The Platform has successfully generated a JWT via the POST /client_auth_token endpoint
  • abandoned - The JWT token has expired before the withdrawal was initiated by the End Customer. Currently, each JWT token is valid for 5 minutes.

Webhook and REST endpoint impacts

  • Zero Hash will send 2 new webhooks events for the new statuses. See initialized example here and abandoned example here
  • Zero Hash will be populating payments that have either of these 2 statuses as their current status on the GET /payments or GET /payments/{payment_id}endpoints.

Action required

  • If you have yet to pass our conformance test, ensure you can pass Scenario 7 here

Endpoints impacted

Relevant documentation

Release date

June 13th, 2025

Release type

Action is required if you fall into any of the below buckets:

  • You currently consume any webhooks of ours
  • You currently use the Account Funding: Withdrawals product

Summary

Payments webhooks: new timestamp header

📢 Security Enhancement

To strengthen webhook security against replay attacks, we’ve introduced a new mechanism that includes a timestamp and new signature headers. These additions allow you to verify not only the authenticity of a webhook, but also its timeliness, helping prevent intercepted messages from being reused maliciously.

🔄 Graceful Transition Plan

To allow a smooth migration, both the existing and new security headers will be sent during a grace period. We encourage clients to begin validating the new headers as soon as possible, as the old headers will be deprecated in the future.

✅ Current headers: Will continue to be sent during the transition.

✅ New headers: Available now for improved protection.

❌ Deprecated: The old signature-only verification will be phased out after the grace period (cutover date is August 12th, 2025).

🔧 Header Reference

Standard Headers

NameDescription
x-zh-hook-notification-idUnique identifier for the notification. Use for idempotency checks.
x-zh-hook-payload-typeType of payload (e.g., participant_status_changed, payment_status_changed, etc.).

Depending on your security configuration, additional headers may also be included:

Current Security Headers (Legacy)

NameDescription
x-zh-hook-signature-256to_hex(hmac(sha_256(payload), your-secret))used if token-based signing was configured.
x-zh-hook-rsa-signature-256to_hex(rsa(sha_256(payload), zh-sec-key))— RSA signature of payload.

New Security Headers (Replay Attack Protection)

NameDescription
x-zh-hook-timestampUNIX timestamp (in milliseconds) when the webhook request was generated. Clients should validate that this value is within an acceptable window (e.g., ±5 minutes) of their system clock.
x-zh-hook-signatureto_hex(hmac(sha256(payload + timestamp), your-secret)) — includes timestamp in signature for replay protection.
x-zh-hook-rsa-signatureto_hex(rsa(sha256(payload + timestamp), zh-sec-key)) — RSA signature of payload + timestamp.

/client_auth_token response: new payment_id field

We will now be providing the payment_id on the response of the POST /client_auth_token call If the permission = crypto-withdrawals or crypto-payouts. This payment_id will then be included in all subsequent payment webhook events associated with that SDK session. This payment_id is also included in the GET /payments/{payment_id} call.

Action required

  • For any Platforms that are currently consuming any webhooks of ours, the grace period to transition to our new webhook verification convention will end on August 12th, 2025. We'll send periodic reminders and as always can offer technical support if there are any questions.
  • For those Platforms that are using the Account Funding: Withdrawal product, please begin to consume the payment_id from the POST /client_auth_token as soon as possible. We'll then schedule a conformance test in accordance with the requirements laid out in the Withdrawals - Reconciliation guide.

Endpoints impacted

  • POST /client_auth_token

Relevant documentation


Release date

June 11th, 2025

Release type

Informational – Optional action from platforms.

Summary

Zero Hash now supports the following Polkadot Asset Hub assets on our platform:

  • DOT (native token)
  • USDC
  • USDT

This includes the ability to deposit, hold and withdraw funds on the native chain of these assets.

📘

USDT not available in CERT environment

Note that USDT is not available in CERT for testing. We recommend use USDC instead for CERT testing.

NY supported

Only the asset DOT is supported in NY State. USDC and USDT on Asset Hub are NOT supported on NY State.

Action required

No action required by the platforms, these assets are enabled automatically for your use.

Endpoints impacted

No endpoints impacted. When the asset is required on an action, just use the proper notation:

  • DOT.DOTHUB
  • USDC.DOTHUB
  • USDT.DOTHUB

Relevant documentation

Release type

Informational – Optional action from platforms.

Summary

A new field was added to the participants information sharing endpoint:

  • Metadata (object): Can be used to submit any additional unstructured metadata

This field will relay the content of metadata sent by the platform when creating the participant. This field is part of the participant creation endpoint and entity creation endpoint.

The information now is incorporated into the following endpoint payload:

  • GET /participant/{participant_code}/full_info

Action required

No action needed from platforms. The field will be included on the payload as described.

Platforms who want to access the Full Information endpoint need to contact client support to have this endpoint enabled.

Endpoints impacted

  • GET /participant/{participant_code}/full_info

Relevant documentation

Jun 3, 2025

Release type

Informational – Optional action from platforms.

Summary

There is a new endpoint under the Participant information sharing endpoints that allows the platform to access the information of Control Persons or Ultimate Business Owners of an entity with a participant code in Zero Hash.

  • GET /participant/{participant_code}/full_info/cp_bo
  • GET /participant/{participant_code}/sanction_screening_info/cp_bo
  • GET /participant/{participant_code}/basic_info/cp_bo

This endpoint will provide the Control Person / Ultimate Business Owner information according to the PII access level the platform is certified for.

For more information on this, refer to the following documentation:

https://docs.zerohash.com/changelog/participant-information-sharing-with-platform#summary

Action required

No action needed from platforms. The endpoint will be available upon release.

Platforms who want to access the Full Information endpoint need to contact client support to have this endpoint enabled.

Endpoints impacted

  • GET /participant/{participant_code}/full_info/cp_bo
  • GET /participant/{participant_code}/sanction_screening_info/cp_bo
  • GET /participant/{participant_code}/basic_info/cp_bo

Relevant documentation

Release Details

Release Date: June 2nd, 2025

Release Type

Informational – optional action from platforms

Summary

Zero Hash is pleased to announce the launch of the Payouts SDK - an embeddable, low-code widget that allows Platforms to offer stablecoin (and crypto) payouts to their end customers.

Use Cases

  • Gig economy payouts: Instantly pay freelancers, creators, and contractors in stablecoins or crypto - no more waiting days for bank transfers.
  • Marketplace payouts: Let sellers withdraw earnings in stablecoins or crypto for faster, global, low-fee access to their funds.
  • Cross-border payroll: Pay remote teams or international employees without the friction of traditional banking rails.
  • Creator economy: Enable platforms like streaming services, music apps, or influencer platforms to pay creators in real-time using stablecoins or crypto.
  • Affiliate & partner rewards: Instantly settle commissions and partner earnings globally with fewer currency conversion headaches.
  • DeFi and crypto-native platforms: Add stablecoin or crypto payouts for dApps or web3 tools that need to distribute funds or earnings.

How it works

  • See end to end integration guide here

Release Details

Release Date: May 12th, 2025

Release Type

Informational – optional action from platforms

Summary

Trade status and balance updates are now available via webhooks. This enhancement provides more granular and timely information on trade settlement, the flow of crypto assets, and authoritative changes to account balances held at Zero Hash. To enable this feature, please reach out to your Zero Hash rep and they will configure your Platform accordingly.

New webhook notifications:

  1. trade.status_changed
  2. account_balance.changed

For more information about configuration and handling webhook payloads, visit the Webhooks Overview page.

Trade Status Changed

Trade status notifications provide information about the current trade status. Net Settlement Trades (a.k.a allocation trades) are filtered out and thus don’t generate a notification for the platforms. There are 3 types of status change notifications:

  • accepted - the trade was successfully submitted, accepted, and pending settlement
  • active - within the settlement window, settlement was attempted but is not yet complete
  • terminated - trade was successfully settled; no further status updates will be issued

Note: The x-zh-hook-payload-type must be set to trade_status_changed

While the schema closely follows the existing GET /trades/{trade_id} endpoint, it does NOT contain EVERY field exposed by the endpoint, such as:

  • "accepted_timestamp"
  • "defaulted_timestamp"
  • "settled_timestamp"
  • "last_update"
  • "settlement_timestamp"
  • "expiry_timestamp"
  • "spread_notional"
  • "spread_bps"
  • "session_id"
  • “payment_processor”
  • “fees”
  • “batch_trade_id“

Any additional or supplementary information should still be fetched from GET /trades/{trade_id} endpoint.

Balance Changed

Account balance change notification provides information about the current available account balance. A notification is emitted when the account balance changes for the following account types:

  • available
  • collateral

Note: The x-zh-hook-payload-type must be set to account_balance.changed.

The schema of the event payload will follow the existing private websocket balance updates feed

Relevant Documentation