topup

This is the primary method for executing an off-ramp to the user's Holyheld card. If you already requested a quote, reuse its transferData unchanged. If you did not request a quote, the SDK can fetch the current conversion and routing data internally.

🚨

Please note! Some wallets like Metamask are single-network handled. It means that while Holyheld can return/accept transaction on any supported network, user MUST switch to the correct network in the wallet for the transaction to be processed.

You can call topup with or without a pre-fetched quote. If you already obtained a quote from convertTokenToEUR or convertEURToToken, reuse its transferData unchanged.

Usage

EVM

import { Network } from '@holyheld/sdk';
import * as chains from 'viem/chains';
import { createPublicClient, createWalletClient, custom, http } from 'viem';

const provider; // current provider in your app (see examples below)
const transferData; // transfer data from conversion methods or undefined
const eventConfig; // callbacks
const chainId; // token chain id

const chain = Object.values(chains).find((item) => item.id === chainId); // get chain entity from viem

const publicClient = createPublicClient({ // create viem public client - https://viem.sh/docs/clients/public.html
  chain,
  transport: http(),
});

const walletClient = createWalletClient({ // wrap your provider in viem wallet client - https://viem.sh/docs/clients/wallet.html
  chain,
  transport: custom(provider), // current provider in your app (see examples below)
  account: '0x...', // wallet address
});

// off-ramp to user's Holyheld card by $holytag
await holyheldSDK.evm.offRamp.topup({
  publicClient: publicClient,
  walletClient: walletClient,
  walletAddress: '0x...',
  tokenAddress: '0x...',
  tokenNetwork: Network.ethereum,
  tokenAmount: '5.25',
  transferData: transferData, // if was provided by 'convertTokenToEUR' and/or 'convertEURToToken'
  holytag: 'SDKTEST', // funds recipient tag
  supportsSignTypedDataV4: true, // true if connected wallet supports eth_signTypedData_v4 (default: false)
  supportsRawTransactionsSigning: true, // true if connected wallet supports raw transactions signing via "eth_sign" or "eth_signTransaction" (default: false)
  eventConfig: eventConfig, // callbacks (see below)
});

Solana

import { Connection, clusterApiUrl } from '@solana/web3.js';
import { PhantomWalletAdapter } from '@solana/wallet-adapter-phantom';
import { SolanaNetwork, createSolanaWalletClientFromAdapter } from '@holyheld/sdk';


const transferData; // transfer data from conversion methods or undefined
const eventConfig; // callbacks

const networkInfo = holyheldSDK.solana.getNetwork(SolanaNetwork.Mainnet);

const connection = new Connection(networkInfo.httpRpcURL, {
  commitment: 'confirmed',
  wsEndpoint: networkInfo.wsRpcURL ?? clusterApiUrl(networkInfo.cluster, true)
});

const walletAdapter = new PhantomWalletAdapter();

const walletClient = createSolanaWalletClientFromAdapter(walletAdapter, connection);

// off-ramp to user's Holyheld card by $holytag
await holyheldSDK.solana.offRamp.topup({
  connection: connection,
  walletClient: walletClient,
  walletAddress: '...',
  tokenAddress: '...',
  tokenNetwork: SolanaNetwork.Mainnet,
  tokenAmount: '5.25',
  transferData: transferData, // if was provided by 'convertTokenToEUR' and/or 'convertEURToToken'
  holytag: 'SDKTEST', // funds recipient tag
  eventConfig: {}, // callbacks (see below)
});

Parameters

EVM

holyheldSDK.evm.offRamp.topup({
  publicClient,            // PublicClient
  walletClient,            // WalletClient
  walletAddress,           // string
  tokenAddress,            // string
  tokenNetwork,            // Network
  tokenAmount,             // string
  transferData,            // TransferDataEVM | undefined
  holytag,                 // string
  supportsSignTypedDataV4, // boolean  (default: false)
  supportsRawTransactionsSigning, // boolean  (default: false)
  eventConfig,             // TopUpCallbackConfig | undefined
});

Solana

holyheldSDK.solana.offRamp.topup({
  connection,    // Connection
  walletClient,  // SolanaWalletClient
  walletAddress, // string
  tokenAddress,  // string
  tokenNetwork,  // SolanaNetwork
  tokenAmount,   // string
  transferData,  // TransferDataSolana | undefined
  holytag,       // string
  eventConfig,   // TopUpCallbackConfig | undefined
});

Parameter	Type	Required	Description
publicClient	PublicClient	Yes (EVM only)	Viem public client configured for the token's chain. Used to read on-chain state.
walletClient	WalletClient / SolanaWalletClient	Yes	Viem wallet client (EVM) or Solana wallet client wrapping the user's provider. Used to request signatures and send transactions.
connection	Connection	Yes (Solana only)	Solana Connection instance for the target cluster.
walletAddress	string	Yes	The EVM or Solana wallet address initiating the transaction. Must match the account in walletClient.
tokenAddress	string	Yes	Contract address of the token to send.
tokenNetwork	Network | SolanaNetwork	Yes	The network enum value for the token's chain. Must match the network of tokenAddress.
tokenAmount	string	Yes	Amount of tokens to send, as a decimal string (e.g. "5.25" for 5.25 USDC). Use the value returned by convertTokenToEUR or convertEURToToken.
transferData	TransferDataEVM | TransferDataSolana | undefined	No	Routing data from convertTokenToEUR or convertEURToToken. Pass undefined to use the current market rate without a pre-fetched quote.
holytag	string	Yes	The recipient's Holyheld tag (without the $ prefix). Funds are credited to this account.
supportsSignTypedDataV4	boolean	No	Set true if the connected wallet supports eth_signTypedData_v4. Enables permit-based token approvals, avoiding a separate approval transaction. Default: false.
supportsRawTransactionsSigning	boolean	No	Set true if the wallet supports raw transaction signing via eth_sign or eth_signTransaction. Default: false.
eventConfig	TopUpCallbackConfig	No	Callback hooks for tracking transaction progress. See Types below.

Returns

Promise<string>

topup waits until the transaction has been included in a block before resolving. For both EVM and Solana, the method returns the transaction hash. The onHashGenerate callback also emits the hash as soon as it becomes available, so your UI can display it immediately.

Types

typescript

enum TopUpStep {
  Confirming = 'confirming', // user is confirming action in wallet
  Approving = 'approving',   // wallet is signing an approval or permit
  Sending = 'sending',       // wallet is signing the final send transaction
}

interface TopUpCallbackConfig {
  /** Called once the transaction hash is available. */
  onHashGenerate?: (hash: string) => void;
  /** Called each time the flow advances to a new step. */
  onStepChange?: (step: TopUpStep) => void;
}

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