Withdrawals SDK

Load config  →  Get routes  →  Get balance  →  Quote (prepare)  →  Sign  →  Submit  →  Poll status

import { MoonPayCommerceWithdraw } from '@heliofi/withdraw-react';
import '@heliofi/withdraw-react/dist/withdraw-react.css';

export const Withdraw = () => (
  <MoonPayCommerceWithdraw
    withdrawalConfigId="wc_..."
    sourceWalletAddress="0xMerchantWallet"
    handleSign={async (payload) => {
      // Simplest path — EIP-712 typed data. See "Signing" for all payload kinds.
      return walletClient.signTypedData(payload.data);
    }}
    onWithdrawalComplete={(result) => console.log('Done', result)}
    onError={(error) => console.error('Failed', error.code, error.message)}
  />
);

{/* String form — relabel the default button (replaces buttonText) */}
<MoonPayCommerceWithdraw
  withdrawalConfigId="wc_..."
  sourceWalletAddress="0xMerchantWallet"
  handleSign={handleSign}
  display="button"
  trigger="Withdraw funds"
/>

{/* Render-prop form — fully custom trigger (replaces renderButton) */}
<MoonPayCommerceWithdraw
  withdrawalConfigId="wc_..."
  sourceWalletAddress="0xMerchantWallet"
  handleSign={handleSign}
  display="button"
  trigger={({ open, close, isOpen }) => (
    <MyButton onClick={isOpen ? close : open}>
      {isOpen ? 'Close' : 'Withdraw funds'}
    </MyButton>
  )}
/>

import { WithdrawProvider } from '@heliofi/withdraw-react';

const App = () => (
  <WithdrawProvider
    withdrawalConfigId="wc_..."
    sourceWalletAddress="0xMerchantWallet"
    handleSign={handleSign} // your wallet signer — see Signing
    onWithdrawalComplete={(result) => console.log('Done', result)}
    onError={(error) => console.error('Failed', error.code, error.message)}
  >
    <YourCustomUI />
  </WithdrawProvider>
);

useGetWithdraw()      → load config (source currencies)
useGetRoutes()        → available destination currencies / chains
useGetBalances()      → user's spendable balance
useCreateWithdrawalDetail()  → get a quote
useUpdateWithdrawalDetail()  → re-quote after edits (optional)
handleSign()          → sign the prepared tx (from context)
useSubmitWithdraw()   → submit the signature
usePollStatus()       → poll until terminal

import { useState } from 'react';
import {
  useWithdrawContext,
  useGetWithdraw,
  useGetBalances,
  useCurrencyOptions,
  useToCurrencyIdForBlockchain,
  useCreateWithdrawalDetail,
  useUpdateWithdrawalDetail,
  useSubmitWithdraw,
  usePollStatus,
  TERMINAL_STATES,
  SignedTransactionKind,
  BlockchainSymbol,
} from '@heliofi/withdraw-react';
import type { QuoteResponse, SigningPayload } from '@heliofi/withdraw-react';

// Map a prepared transaction to the handleSign payload (see Signing).
const toSigningPayload = (prepared: QuoteResponse['prepared']): SigningPayload => {
  switch (prepared.kind) {
    case SignedTransactionKind.POLYMARKET_WALLET:
    case SignedTransactionKind.HYPERCORE:
      return { kind: 'typed_data', data: prepared.typedData };
    case SignedTransactionKind.RAW:
      return { kind: 'transaction', data: prepared.unsignedTx };
    case SignedTransactionKind.USER_OP:
      return {
        kind: 'user_op',
        data: {
          userOp: prepared.userOp,
          entryPoint: prepared.entryPoint,
          chain: prepared.chain,
          authorization: prepared.authorization,
        },
      };
  }
};

const YourCustomUI = () => {
  const { withdrawalConfigId, sourceWalletAddress, handleSign } = useWithdrawContext();

  const { data: config } = useGetWithdraw();
  const { data: balance } = useGetBalances(sourceWalletAddress);
  const { trigger: createQuote } = useCreateWithdrawalDetail();
  const { trigger: updateQuote } = useUpdateWithdrawalDetail();
  const { trigger: submit } = useSubmitWithdraw();

  // ── Form state (yours to manage) ──
  const [currencySymbol, setCurrencySymbol] = useState<string>();
  const [blockchainSymbol, setBlockchainSymbol] = useState<BlockchainSymbol>();
  const [amount, setAmount] = useState('');       // minimal units
  const [recipient, setRecipient] = useState('');
  const [quote, setQuote] = useState<QuoteResponse>();
  const [withdrawalDetailId, setWithdrawalDetailId] = useState<string>();

  // ── 1. Build the currency/blockchain selectors ──
  const { options: currencyOptions } = useCurrencyOptions();
  const toCurrencyId = useToCurrencyIdForBlockchain(currencySymbol, blockchainSymbol);
  const sourceCurrencyId = config?.fromCurrencies[0]?.id;

  // ── 2. Get a quote ──
  const handleGetQuote = async () => {
    if (!withdrawalConfigId || !sourceWalletAddress || !toCurrencyId || !sourceCurrencyId) return;
    const result = await createQuote({
      withdrawalConfigId,
      ownerAddress: sourceWalletAddress,
      recipient,
      amount,
      toCurrencyId,
      sourceCurrencyId,
    });
    setQuote(result);
  };

  // ── 2b. Re-quote after the user edits amount/recipient ──
  const handleUpdateQuote = async () => {
    if (!quote || !toCurrencyId || !sourceCurrencyId) return;
    const result = await updateQuote({
      withdrawalDetailId: quote.withdrawalDetailId,
      ownerAddress: sourceWalletAddress,
      recipient,
      amount,
      toCurrencyId,
      sourceCurrencyId,
    });
    setQuote(result);
  };

  // ── 3. Sign and submit ──
  const handleConfirmAndSign = async () => {
    if (!quote) return;
    const signature = await handleSign(toSigningPayload(quote.prepared));
    await submit({
      withdrawalDetailId: quote.withdrawalDetailId,
      token: quote.token,       // JWT from the quote — required for submit
      signedTx: signature,
    });
    setWithdrawalDetailId(quote.withdrawalDetailId);
  };

  // ── 4. Poll status (auto-polls every 3s once the id is set) ──
  const { data: status } = usePollStatus(withdrawalDetailId);
  const isTerminal = status && TERMINAL_STATES.has(status.state);

  return <div>{/* Your UI here */}</div>;
};

type SigningPayload = {
  kind: 'transaction' | 'typed_data' | 'user_op';
  data: unknown;
};

const handleSign = async (payload: SigningPayload): Promise<string> => { /* ... */ };

import { signTypedData } from '@wagmi/core';
import type { SigningPayload } from '@heliofi/withdraw-react';
import { wagmiConfig } from './wagmiConfig';

const handleSign = async (payload: SigningPayload): Promise<string> => {
  if (payload.kind === 'typed_data') {
    const { domain, types, primaryType, message } = payload.data as {
      domain: Record<string, unknown>;
      types: Record<string, Array<{ name: string; type: string }>>;
      primaryType: string;
      message: Record<string, unknown>;
    };

    // wagmi/viem derives EIP712Domain itself — strip it from the types.
    const { EIP712Domain: _omit, ...messageTypes } = types;

    return signTypedData(wagmiConfig, { domain, types: messageTypes, primaryType, message });
  }

  throw new Error(`Unsupported signing kind: ${payload.kind}`);
};

import { sendTransaction } from '@wagmi/core';

if (payload.kind === 'transaction') {
  const tx = payload.data as { to: `0x${string}`; value?: bigint; data?: `0x${string}` };
  return sendTransaction(wagmiConfig, tx);
}

import { VersionedTransaction } from '@solana/web3.js';

const base64ToBytes = (b64: string) => Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
const bytesToBase64 = (bytes: Uint8Array) => btoa(String.fromCharCode(...bytes));

const handleSign = async (payload: SigningPayload): Promise<string> => {
  if (payload.kind !== 'transaction') throw new Error(`Unsupported: ${payload.kind}`);
  const tx = VersionedTransaction.deserialize(base64ToBytes(payload.data as string));
  const signed = await signTransaction(tx); // from useWallet()
  return bytesToBase64(signed.serialize());
};

import { getUserOperationHash } from 'viem/account-abstraction';
import type { Address } from 'viem';

// aa-sdk hexlifies these gas fields; viem's hash needs them as bigints.
const BIGINT_FIELDS = ['nonce', 'callGasLimit', 'verificationGasLimit', 'preVerificationGas',
  'maxFeePerGas', 'maxPriorityFeePerGas', 'paymasterVerificationGasLimit', 'paymasterPostOpGasLimit'];

const toBigints = (op: Record<string, unknown>) => {
  const out = { ...op };
  for (const f of BIGINT_FIELDS) if (typeof out[f] === 'string') out[f] = BigInt(out[f] as string);
  return out;
};

const handleSign = async (payload: SigningPayload): Promise<string> => {
  if (payload.kind !== 'user_op') throw new Error(`Unsupported: ${payload.kind}`);
  const { userOp, entryPoint, authorization } = payload.data as {
    userOp: Record<string, unknown>;
    entryPoint: Address;
    authorization: { chainId: string; address: Address; nonce: string };
  };
  const chainId = Number(BigInt(authorization.chainId));
  const nonce = Number(BigInt(authorization.nonce));

  const userOpHash = getUserOperationHash({
    chainId,
    entryPointAddress: entryPoint,
    entryPointVersion: '0.7',
    userOperation: toBigints(userOp) as never,
  });

  const signature = await account.signMessage({ message: { raw: userOpHash } });
  const signed = await account.signAuthorization({ address: authorization.address, chainId, nonce });

  return JSON.stringify({
    signature,
    authorization: {
      chainId, address: authorization.address, nonce,
      r: signed.r, s: signed.s, yParity: signed.yParity,
    },
  });
};

import { WithdrawalSDK } from '@heliofi/withdraw-core';

const sdk = WithdrawalSDK.create({
  baseUrl: 'https://api.hel.io/v1',
  // headers?: extra request headers
  // fetch?:   custom fetch (e.g. for Node < 18 or instrumentation)
});

const configId = 'wc_...';

// 1. Load config → source currency
const config = await sdk.getWithdrawalConfig(configId);
const sourceCurrencyId = config.fromCurrencies[0].id;

// 2. See where the user can withdraw to
const { routes } = await sdk.getRoutes(configId);
const toCurrencyId = routes.find((r) => r.available)!.toCurrency.id;

// 3. (Optional) check balance
const { balances } = await sdk.getBalance(configId, ownerAddress);

// 4. Quote
const quote = await sdk.createWithdrawalDetail({
  withdrawalConfigId: configId,
  ownerAddress,
  recipient,
  amount: '1000000', // minimal units
  toCurrencyId,
  sourceCurrencyId,
});

// 5. Sign the prepared tx with your wallet (branch on quote.prepared.kind — see Signing)
const signedTx = await signWithYourWallet(quote.prepared);

// 6. Submit
const submit = await sdk.submitWithdrawal({
  withdrawalDetailId: quote.withdrawalDetailId,
  token: quote.token,
  signedTx,
});

// 7. Poll until terminal
import { TERMINAL_STATES } from '@heliofi/withdraw-core';
let status = await sdk.getWithdrawalDetail(quote.withdrawalDetailId);
while (!TERMINAL_STATES.has(status.state)) {
  await new Promise((r) => setTimeout(r, 3000));
  status = await sdk.getWithdrawalDetail(quote.withdrawalDetailId);
}

import { decodeJwt, isQuoteExpired, isSupported, isBelow, SDK_VERSION } from '@heliofi/withdraw-core';

isQuoteExpired(quote.token);        // → true once the quote's JWT has expired (5s buffer)
decodeJwt(quote.token);             // → { exp, iat, withdrawalDetailId, ... }

// Success result passed to onWithdrawalComplete.
interface WithdrawResult {
  withdrawalDetailId: string;
  status: string;
  txHash: string | null;
}

// Error passed to onError (React) — a code + human message.
interface WithdrawError {
  code: WithdrawErrorCode;
  message: string;
}

// The signing callback payload.
interface SigningPayload {
  kind: 'transaction' | 'typed_data' | 'user_op';
  data: unknown;
}

// Quote response (from prepare / update).
interface QuoteResponse {
  withdrawalDetailId: string;
  token: string;                 // JWT — required for submit
  prepared: PreparedTransaction; // branch on .kind to sign (see Signing)
  summary: QuoteSummary;         // amounts + fee breakdown
}

// Submit / status responses.
interface SubmitResponse { withdrawalDetailId: string; txHash: string | null; state: WithdrawalState; broadcastAck: BroadcastAck | null; }
interface StatusResponse { withdrawalDetailId: string; state: WithdrawalState; txHash: string | null; broadcastAck: BroadcastAck | null; errorReason: string | null; }