Release Notes
Back to All

Account Funding API and SDK: Ability to set your own identifier

June 26th, 2025

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