SDK Introduction

The Holyheld SDK enables your application to facilitate crypto-to-fiat conversions (off-ramp) and fiat-to-crypto purchases (on-ramp) directly from a user's connected wallet. Off-ramping converts tokens from a user's wallet to EUR on their Holyheld card. On-ramping does the reverse — initiating a fiat spend that results in tokens delivered to a specified wallet address.

To use Holyheld SDK, you will require an SDK API key. To obtain one, please reach out to your Holyheld point of contact.

SDK flow overview

Off-Ramp (token → EUR)

1. Check availability
   holyheldSDK.getServerSettings()
   └── confirms isTopupEnabled, min/max EUR limits

2. Validate recipient
   holyheldSDK.getTagInfo(holytag)          ← sending to a $holytag
   holyheldSDK.validateAddress(address)     ← OR sending to own account

3. Get a conversion quote
   holyheldSDK.evm.offRamp.convertTokenToEUR({ tokenAddress, amount, ... })
   holyheldSDK.evm.offRamp.convertEURToToken({ tokenAddress, amount, ... })
   └── returns { tokenAmount, EURAmount, transferData }

4. Execute the off-ramp
   holyheldSDK.evm.offRamp.topup({ transferData, holytag, eventConfig, ... })
   holyheldSDK.evm.offRamp.topupSelf({ transferData, walletAddress, eventConfig, ... })
   │
   ├── onStepChange('confirming')   ← user confirms in wallet
   ├── onStepChange('approving')    ← token approval or permit (if needed)
   ├── onStepChange('sending')      ← final send transaction
   └── onHashGenerate(txHash)       ← transaction hash available ✓

On-Ramp (EUR → token)

1. Check availability
   holyheldSDK.getServerSettings()
   └── confirms isOnRampEnabled, min/max EUR limits

2. Validate recipient wallet
   holyheldSDK.validateAddress(walletAddress)

3. Get an estimation (optional)
   holyheldSDK.evm.onRamp.getOnRampEstimation({ tokenAddress, EURAmount, ... })
   └── returns estimated token amount to be delivered

4. Request on-ramp
   holyheldSDK.evm.onRamp.requestOnRamp({ tokenAddress, EURAmount, walletAddress, ... })
   └── returns { requestUid, amountEUR, amountToken, beneficiaryAddress, ... }

5. Wait for user confirmation
   holyheldSDK.evm.onRamp.watchRequestId(requestUid, { timeout: 180_000 })
   │
   ├── success: true  → on-ramp approved, tokens en route
   │   hash (if waitForTransactionHash: true) → on-chain tx hash
   └── success: false → declined or timed out

Web3 Provider

The SDK supports both EVM compatible and Solana networks. Please see examples for more details.

EVM Networks

A Viem provider is used for EVM-compatible JSON-RPC interactions, Web3.js and ethers.js are also supported.

Solana

Solana is supported via @solana/web3.js.

Node.js polyfill required

Some dependencies in SDK rely on Node.js's Buffer class, which is not available by default in modern bundlers. To ensure compatibility, you must polyfill Buffer using one of the following:

• buffer - for manual importing
• vite-plugin-node-polyfills - for Vite
• node-polyfill-webpack-plugin - for Webpack
• rollup-plugin-node-polyfills - for Rollup

Please refer to your bundler's documentation for setup instructions.

Getting help

Resource	Link
Bug reports & questions	support@holyheld.com
Changelog	SDK Changelog
npm package	@holyheld/sdk

If you believe you have found a security issue, contact support@holyheld.com directly rather than filing a public issue.