Developer Docs

Appearance

Deposit ​

A Deposit (also called off-ramp — moving from crypto to fiat) lets a user send tokens from their connected wallet and receive EUR on a Holyheld card. The user signs one blockchain transaction; BRRR handles conversion, routing across chains, and crediting the recipient's card.

Deposits are the most common flow on the platform. Reach for them whenever your application needs to turn on-chain assets into spendable fiat — payouts to creators, customer cash-out, agent operating budgets, or simply letting a user move funds out of a wallet.

How a Deposit works ​

  1. Your application proposes a Deposit: source wallet, token, amount, and recipient (a $holytag for sending to anyone, or the wallet's own card).
  2. BRRR returns a live conversion quote — token amount in, EUR amount out — together with the routing data that describes how the transaction will execute on-chain.
  3. The user signs in their wallet. If the token needs an allowance approval or supports an EIP-2612 permit, the SDK handles that transparently in the same flow.
  4. BRRR receives the tokens, converts at the quoted rate, and credits EUR to the recipient's Holyheld card.

The user's private key never leaves their wallet. BRRR is non-custodial through the entire signing flow.

Choose your integration surface ​

SurfaceWhen to useAuth
SDKA user-facing app where the end user signs the transaction in their walletSDK API key
Card APIYou already operate a card, custody, or payments product and want low-level building blocksX-Api-Key
OTC APIServer-to-server quote and execution against a known recipientX-Api-Key
Multi-tenant Settlement APIA regulated partner running settlement for its own customersX-Api-Key

If your end user controls the wallet and signs in the browser, choose the SDK. If you control the wallet and operate from a server, choose the API surface that matches your role.

Deposit with the SDK ​

The topup method (which executes a Deposit) is the primary entry point. A minimal end-to-end EVM example:

typescript
import HolyheldSDK, { Network } from '@holyheld/sdk';

const sdk = new HolyheldSDK({ apiKey: process.env.HOLYHELD_SDK_API_KEY });
await sdk.init();

const settings = await sdk.getServerSettings();
if (!settings.external.isTopupEnabled) {
  throw new Error('Deposits unavailable');
}

const tag = await sdk.getTagInfo('RECIPIENT_HOLYTAG');
if (!tag.found) {
  throw new Error('Recipient not found');
}

const quote = await sdk.evm.offRamp.convertTokenToEUR({
  walletAddress: '0x...',
  tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC on Ethereum
  tokenDecimals: 6,
  amount: '100',
  network: Network.ethereum,
});

await sdk.evm.offRamp.topup({
  publicClient,
  walletClient,
  walletAddress: '0x...',
  tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  tokenNetwork: Network.ethereum,
  tokenAmount: quote.tokenAmount,
  transferData: quote.transferData,
  holytag: 'RECIPIENT_HOLYTAG',
  supportsSignTypedDataV4: true,
});

Solana follows the same shape via sdk.solana.offRamp.topup with a Connection instead of a viem publicClient. See the topup reference for parameters and callbacks, and topupSelf when the destination is the connected wallet's own card.

Deposit through the APIs ​

Server-side Deposits skip the wallet-signing flow and instead rely on:

  • A registered partner (Multi-tenant Settlement) or your own platform credentials (Card API, OTC API).
  • An API-issued quote that locks the conversion rate.
  • An execution call that posts the on-chain transfer from your custody system.

Endpoint inventories live in the API Sections page; the Multi-tenant Settlement section walks through the partner-specific quote → execute → status loop.

Recipient, currency, and assets ​

  • Recipient. Any Holyheld user identified by $holytag, or the connected wallet's own card via topupSelf. The $ prefix appears in code; in prose, refer to the value as a holytag.
  • Settlement currency. EUR. All Deposits credit a Holyheld card balance.
  • Supported assets and networks. USDC, USDT, native gas tokens, and a curated set of EVM and Solana tokens. The canonical list is on the Supported Networks page — that page is the source of truth, not this hub.

Errors ​

The SDK throws typed errors via HolyheldSDKError with codes from HolyheldSDKErrorCode. Common Deposit codes include UnexpectedWalletNetwork, UserRejectedTransaction, UserRejectedSignature, and FailedTopUp. The full list — and how to catch them — lives in SDK error handling.

Where to next ​