Developer Docs

Appearance

Orchestrate ​

Orchestrate (the supporting layer — cross-chain routing, validation, balances, monitoring) is everything your application needs around a Deposit or a Withdraw, but isn't the on-chain action itself. It is how BRRR turns "the user holds tokens somewhere on some chain" into a single signed transaction, and how your application gets enough information to render a credible UI before that transaction is signed.

There's no single orchestrate() method. Orchestrate surfaces through four concrete capabilities: cross-chain routing, recipient and address validation, wallet balance discovery, and post-flow monitoring.

Cross-chain routing ​

A user might hold USDC on Polygon while connecting to your app from Ethereum. They might hold a long-tail token that needs a swap before BRRR can accept it. They might be on a chain that requires a bridge hop. None of that is your application's concern.

When you call convertTokenToEUR or convertEURToToken, BRRR computes the optimal route — bridges, swaps, gas estimation — and returns it as an opaque transferData object. You pass that object unchanged to topup and the SDK executes the route in one signing flow.

If you skip the explicit quote step, topup fetches current routing data internally before submitting. The tradeoff: skipping the quote means you can't show the user a rate preview, but it removes one round trip when previewing isn't needed.

Recipient and address validation ​

Two helpers replace the question "is this destination valid?" with a structured answer:

  • getTagInfo(holytag) — looks up a Holyheld user by holytag and returns whether they exist and accept Deposits. Use before calling topup.
  • validateAddress(address) — returns whether a wallet address is registered with Holyheld and which flows it's eligible for (isTopupAllowed, isOnRampAllowed). Use before calling topupSelf or requestOnRamp.

Both methods catch the common failure modes — typos, ineligible addresses, risk-flagged wallets — before the user signs anything.

Wallet balances across networks ​

getWalletBalances(address) returns every supported token the wallet holds, across every supported network, in one call. Each entry includes the network, contract address, decimals, symbol, USD value, and whether the token supports an EIP-2612 permit (hasPermit: true) — useful for picking the cheapest signing path in your UI.

Combined with cross-chain routing, this is what makes a "pick any token, on any chain, send anywhere" experience possible without your application implementing per-chain RPC logic.

Network helpers ​

The SDK ships small synchronous utilities for working with the supported network catalog. Useful when building dropdowns, validating user input, or matching wallet state to expected chains.

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

sdk.evm.offRamp.getAvailableNetworks();      // ['ethereum', 'polygon', ...]
sdk.evm.onRamp.getAvailableNetworks();       // ['ethereum', 'polygon', ...]
sdk.evm.isEVMNetwork(Network.ethereum);      // true
sdk.evm.getNetwork(Network.ethereum);        // NetworkInfoEVM
sdk.evm.getNetworkChainId(Network.ethereum); // 1
sdk.evm.getNetworkByChainId(1);              // NetworkInfoEVM | undefined
typescript
import { SolanaNetwork } from '@holyheld/sdk';

sdk.solana.offRamp.getAvailableNetworks();         // ['solana-mainnet']
sdk.solana.isSolanaNetwork(SolanaNetwork.Mainnet); // true
sdk.solana.getNetwork(SolanaNetwork.Mainnet);      // NetworkInfoSolana

NetworkInfoEVM and NetworkInfoSolana carry the displayable name, chain ID, RPC URLs, block explorer details, native gas token, and an icon URL. Use them to render network pickers without hard-coding chain metadata.

For server-side gas estimation on EVM Deposits, getTopUpEstimation returns the expected native-token cost (in WEI) for the underlying transaction — useful when the application needs to display "you'll spend ~X ETH in gas" alongside the conversion quote.

Monitoring ​

Once a Deposit or Withdraw is in flight, Webhooks deliver server-side notifications for terminal states: settled, failed, refunded. Prefer webhooks over polling whenever your architecture allows — they are the canonical channel for letting downstream systems react to flow outcomes.

For client-side state, the SDK's onStepChange and onHashGenerate callbacks (Deposit) and watchRequestId (Withdraw) are the equivalent surfaces.

Where to next ​