TypeScript Types

Key exported types, interfaces, and enums from @holyheld/sdk. Import them directly:

import {
  Network,
  SolanaNetwork,
  HolyheldSDKErrorCode,
  TopUpStep,
} from '@holyheld/sdk';
import type {
  TopUpCallbackConfig,
  ServerExternalSettings,
} from '@holyheld/sdk';

Enums

Network

EVM-compatible blockchain networks supported by the SDK.

enum Network {
  ethereum = 'ethereum',
  polygon = 'polygon',
  avalanche = 'avalanche',
  arbitrum = 'arbitrum',
  optimism = 'optimism',
  gnosis = 'gnosis',
  zkevm = 'zkevm',
  base = 'base',
  zksyncera = 'zksyncera',
  blast = 'blast',
  mode = 'mode',
  bsc = 'bsc',
  manta = 'manta',
  alephzero = 'alephzero',
  ink = 'ink',
  sonic = 'sonic',
  hyperEVM = 'hyperevm',
  berachain = 'berachain',
  plume = 'plume',
  plasma = 'plasma'
}

Use Network values for the tokenNetwork parameter in all EVM off-ramp and on-ramp methods.

SolanaNetwork

Solana networks supported by the SDK.

enum SolanaNetwork {
  Mainnet = 'solana-mainnet'
}

HolyheldSDKErrorCode

Error codes thrown by SDK methods. Catch and inspect error.code to handle specific cases.

enum HolyheldSDKErrorCode {
  NotInitialized = 'HSDK_NI',
  FailedInitialization = 'HSDK_FI',
  UnsupportedNetwork = 'HSDK_UN',
  InvalidTopUpAmount = 'HSDK_ITUA',
  InvalidOnRampAmount = 'HSDK_IORA',
  UnexpectedWalletNetwork = 'HSDK_UWN',
  UserRejectedSignature = 'HSDK_RS',
  UserRejectedTransaction = 'HSDK_RT',
  FailedSettings = 'HSDK_FS',
  FailedTagInfo = 'HSDK_FTI',
  FailedAddressInfo = 'HSDK_FAI',
  FailedWalletBalances = 'HSDK_FWB',
  FailedEstimation = 'HSDK_FE',
  FailedConversion = 'HSDK_FC',
  FailedTopUp = 'HSDK_FTU',
  FailedCreateOnRampRequest = 'HSDK_FCOR',
  FailedOnRampRequest = 'HSDK_FOR',
  FailedWatchOnRampRequestTimeout = 'HSDK_FwORT',
  FailedWatchOnRampRequest = 'HSDK_FWORR',
  FailedConvertOnRampAmount = 'HSDK_FCORA',
  FailedOnRampEstimation = 'HSDK_FORE',
}

TopUpStep

Steps emitted via onStepChange during a topup or topupSelf call.

enum TopUpStep {
  Confirming = 'confirming', // Waiting for the user to confirm in wallet
  Approving  = 'approving',  // Waiting for token approval or permit signature
  Sending    = 'sending',    // Waiting for the final send transaction signature
}

TopUpStep is a single shared enum exported by the SDK. Some flows may not use every step at runtime.

Interfaces

TopUpCallbackConfig

Callback hooks passed to topup and topupSelf via the eventConfig parameter.

interface TopUpCallbackConfig {
  /**
   * Called once when the transaction hash becomes available.
   * Use this to display or store the transaction hash.
   */
  onHashGenerate?: (hash: string) => void;

  /**
   * Called each time the flow advances to a new TopUpStep.
   * Use this to update your UI (e.g. spinner text, progress indicator).
   */
  onStepChange?: (step: TopUpStep) => void;
}

ServerExternalSettings

Return type of getServerSettings.

type ServerExternalSettings = {
  external: {
    /** Whether off-ramp (topup) is currently available. */
    isTopupEnabled: boolean;
    /** Whether on-ramp is currently available. */
    isOnRampEnabled: boolean;
    /** Maximum EUR equivalent allowed per off-ramp transaction (as string). */
    maxTopUpAmountInEUR: string;
    /** Minimum EUR equivalent allowed per off-ramp transaction (as string). */
    minTopUpAmountInEUR: string;
    /** Maximum EUR amount allowed per on-ramp transaction (as string). */
    maxOnRampAmountInEUR: string;
    /** Minimum EUR amount allowed per on-ramp transaction (as string). */
    minOnRampAmountInEUR: string;
  };
  common: {
    /** Off-ramp fee as a percentage string (e.g. "0.75" means 0.75%). */
    topUpFeePercent: string;
  };
};

ConvertTopUpData

Return type of convertTokenToEUR and convertEURToToken.

EVM

type ConvertTopUpDataEVM = {
  /** Token amount involved in the conversion, as a decimal string. */
  tokenAmount: string;
  /** EUR equivalent of the token amount, as a decimal string. */
  EURAmount: string;
  /**
   * Token-specific routing data for the off-ramp transaction.
   * Pass this directly to topup/topupSelf as the transferData parameter.
   * Do not modify or cache across sessions.
   */
  transferData?: TransferDataEVM;
};

Solana

type ConvertTopUpDataSolana = {
  tokenAmount: string;
  EURAmount: string;
  transferData?: TransferDataSolana;
};

RequestOnRampEVMResult

Return type of requestOnRamp.

type RequestOnRampEVMResult = {
  /** Unique ID of the on-ramp request. Pass to watchRequestId. */
  requestUid: string;
  /** Chain ID of the network where tokens will arrive. */
  chainId: number;
  /** Token metadata for the token being purchased. */
  token: TokenEVM;
  /** EUR amount charged from the user's Holyheld balance, as a decimal string. */
  amountEUR: string;
  /** Expected token amount to be delivered to the wallet, as a decimal string. */
  amountToken: string;
  /** Network gas fee deducted from the transaction, denominated in EUR. */
  feeEUR: string;
  /** Destination wallet address where tokens will arrive. */
  beneficiaryAddress: EVMAddress;
};

WatchOnRampResult

Return type of watchRequestId.

type WatchOnRampResult = {
  /** true if the user approved and the transaction was submitted; false if declined or expired. */
  success: boolean;
  /**
   * On-chain transaction hash. Present only when success is true
   * and waitForTransactionHash was set to true in the options.
   */
  hash?: string;
};

WatchOnRampRequestIdOptions

Options passed to watchRequestId.

type WatchOnRampRequestIdOptions = {
  /**
   * Polling timeout in milliseconds. If the request is not resolved
   * within this window, watchRequestId throws a FailedWatchOnRampRequestTimeout error.
   * Default: SDK internal default (recommended: 180000 for a 3-minute window).
   */
  timeout?: number;
  /**
   * If true, watchRequestId continues polling until the on-chain transaction
   * hash is available, not just until user confirmation.
   * Default: false.
   */
  waitForTransactionHash?: boolean;
};