topupSelf

This is the primary method for executing an off-ramp to the user's Holyheld card without specifying a $holytag — the Holyheld card is identified automatically from the connected wallet address. 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.

Use topupSelf instead of topup when the user is off-ramping to their own Holyheld card and you do not need to specify a $holytag. If you already obtained a conversion quote, 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 the Holyheld card of the connected wallet
await holyheldSDK.evm.offRamp.topupSelf({
  publicClient: publicClient,
  walletClient: walletClient,
  walletAddress: '0x...',
  tokenAddress: '0x...',
  tokenNetwork: Network.ethereum,
  tokenAmount: '5.25',
  transferData: transferData, // if was provided by 'convertTokenToEUR' and/or 'convertEURToToken'
  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 the Holyheld card of the connected wallet
await holyheldSDK.solana.offRamp.topupSelf({
  connection: connection,
  walletClient: walletClient,
  walletAddress: '...',
  tokenAddress: '...',
  tokenNetwork: SolanaNetwork.Mainnet,
  tokenAmount: '5.25',
  transferData: transferData, // if was provided by 'convertTokenToEUR' and/or 'convertEURToToken'
  eventConfig: {}, // callbacks (see below)
});

Parameters

topupSelf accepts the same parameters as topup, except holytag is omitted — funds are credited to the Holyheld card associated with the connected wallet address.

Parameter	Type	Required	Description
publicClient	PublicClient	Yes (EVM only)	Viem public client configured for the token's chain.
walletClient	WalletClient / SolanaWalletClient	Yes	Wallet client wrapping the user's provider.
connection	Connection	Yes (Solana only)	Solana Connection instance for the target cluster.
walletAddress	string	Yes	The wallet address initiating the transaction. The Holyheld card linked to this address receives the funds.
tokenAddress	string	Yes	Contract address of the token to send.
tokenNetwork	Network | SolanaNetwork	Yes	The network enum value for the token's chain.
tokenAmount	string	Yes	Amount of tokens to send as a decimal string (e.g. "5.25").
transferData	TransferDataEVM | TransferDataSolana | undefined	No	Routing data from convertTokenToEUR or convertEURToToken.
supportsSignTypedDataV4	boolean	No	Set true if the wallet supports eth_signTypedData_v4. Enables permit-based approvals. Default: false.
supportsRawTransactionsSigning	boolean	No	Set true if the wallet supports raw transaction signing. Default: false.
eventConfig	TopUpCallbackConfig	No	Callback hooks for tracking transaction progress.

Returns

Promise<string>

topupSelf 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.