Crypto Withdrawals SDK Guide

Setup

Platforms can instantiate the Crypto Withdrawals SDK offering with AUTH included that eliminates the need to use the Account Link SDK flow.

Crypto Withdrawals differs from the Fund Withdrawals SDK in that it does NOT require fiat to convert into outgoing with rawals from the platform's float account. Crypto Withdrawals SDK is a non-converted withdrawal of crypto on the zerohash ledger to the customer's exchange account or wallet. Both SDKs utilize the same permission crypto-withdrawals. The difference is in the token's payload: supplying withdrawal_details (with quoted_asset and withdrawal_request_amount) triggers the Fund Withdrawals flow, whereas Crypto Withdrawals expects no withdrawal_details and lets the End Customer pick asset, network, and amount inside the SDK.

The key difference between this integration and the Account Link SDK + Withdraw SDK integration is the absence of the external account reference. Otherwise, the SDK flow is similar.

Flow

Crypto Withdrawals SDK - Request Access Token

Platform generates a client access token with the crypto-withdrawals permission. Unlike the Fund Withdrawals SDK, no withdrawal_details block is required; the End Customer selects asset, network, and amount inside the SDK.

Example POST /client_auth_token request:

{
    "participant_code": "CUST01",
    "permissions": ["crypto-withdrawals"],
    "reference_id": "0bd7f7f0-cf26-495f-b2df-e8afe8481ba3"
}

Starting the Crypto Withdrawals flow

After a successful POST /client_auth_token call, the next step is to open the Crypto Withdrawals modal via the zh-web-sdk. The example below shows a React integration; for native iOS/Android, use our native mobile SDKs which expose the same flow.

import { useMemo } from 'react';
import ZeroHashSDK, { AppIdentifier } from 'zh-web-sdk';

export function WithdrawButton({ jwt }: { jwt: string }) {
  // Create the SDK instance once, not on every render.
  const sdk = useMemo(
    () =>
      new ZeroHashSDK({
        zeroHashAppsURL: 'https://web-sdk.zerohash.com',
        env: 'prod', // 'cert' | 'prod'
        theme: 'auto', // 'light' | 'dark' | 'auto'
      }),
    []
  );

  const openWithdrawal = () => {
    sdk.openModal({
      appIdentifier: AppIdentifier.CRYPTO_WITHDRAWALS,
      jwt,
    });
  };

  const closeWithdrawal = () => {
    sdk.closeModal(AppIdentifier.CRYPTO_WITHDRAWALS);
  };

  return <button onClick={openWithdrawal}>Withdraw crypto</button>;
}

The SDK walks the End Customer through the flow before the Review screen:

1. Select source (only when the token has AUTH enabled) - either link an exchange to withdraw from, or choose manual entry (classic transfer)
2. Select asset - the asset to withdraw
3. Select network - the network the asset should be sent on
4. Destination address - the destination wallet or exchange address (plus a memo/tag if the asset requires one). Only shown for manual entry; for exchange integrations the destination is resolved from the linked account
5. Enter amount - the amount to withdraw, in the selected asset

The Customer then lands on the Review screen, which shows:

Crypto Withdrawals SDK - Initiate Withdrawal

At this point, the End Customer is interacting with the front end SDK. The Customer will ultimately initiate the withdrawal.

Crypto Withdrawals SDK - Consume Webhook

If you are configured for the AUTH experience, you will receive AUTH Withdrawal webhooks for the transaction lifecycle.

Crypto Withdrawals SDK - Query Withdrawals

The Platform can also query the GET /withdrawals/requests endpoint to view information about the Withdrawal. See the endpoint reference for the full response shape and example.