On-ramp Flow

To on-ramp from a Holyheld account the following steps should be completed:

1. Get settings and ensure that on-ramping is available using getServerSettings method.
2. Check that selected wallet can transact using validateAddress method.
3. Provide two parameters: token and amount in EUR.
4. Optionally. Get binary data to pass as swap parameters using convertEURToToken or convertTokenToEUR methods.
5. Call the requestOnRamp method to execute the transaction.

🔔 User will need to confirm the on-ramp request in their Holyheld app

6. Wait for the callback response of the operation result using watchRequestId.

Here are the functions that are available for you to use.

getServerSettings Get settings:

This method gets current state/settings for interacting with the service. Please always use this method to check:

• if the feature is available;
• the minimum and maximum allowed amounts to on-ramp.

🔔 Please note, that financial values are provided and consumed as strings to avoid floating point conversion problems.

(async () => {
  const data = await holyheldSDK.getServerSettings();
})();

Types:

type Response = {
  external: {
    // indicates if the sending feature is available at the moment
    isTopupEnabled: boolean;
    // maximum amount (equivalent in EUR) that is allowed to be processed
    maxTopUpAmountInEUR: string; // example: '1000'
    // minimum amount (equivalent in EUR) that is allowed to be processed
    minTopUpAmountInEUR: string; // example: '5'
  };
  common: {
    // fee (in percent) that is deducted when making an off-ramping operation on mainnet
    topUpFeePercent: string; // example: '0.75'
  };
}

validateAddress Get wallet information:

User wallet address is a unique identifier which can have account, card and a $holytag bound to it. It is alphanumeric string.

🔔 Please note that a valid wallet address is 42 strings long and begins with 0x prefix.

🔔 Please note that this method does not support ENS domains.

(async () => {
  // a wallet address could be pre-set or have to be input by user, depends on the application
  const data = await holyheldSDK.validateAddress('0x000000000000000000000000000000000000dEaD');
})();

Types:

type Response = {
  isTopupAllowed: boolean;
  isOnRampAllowed: boolean;
}

convertTokenToEUR Convert token to EUR:

This method is used to estimate a token value in EUR to proceed with the on-ramping. convertTokenToEUR method can also be used in some scenarios/apps where token to be sent is pre-set and not selectable.

(async () => {
  const result = await sdk.onRamp.convertTokenToEUR(
    token,
    '11.11' // native token amount
  );
  console.log('EUR amount is', result)
})();

convertEURToToken Convert EUR to token:

convertEURToToken method returns a calculated token amount to match requested EUR amount.

(async () => {
  const result = await sdk.onRamp.convertEURToToken(
    token,
    '11.11' // EUR amount
  );
  console.log('token amount is', result)
})();

requestOnRamp Created on-ramp transaction request:

This is the 'main' method to call that executes on-ramping from a Holyheld account. Parameter values should be retrieved using methods described above, such as transferData matching token and token amount provided.

🚨 As per security requirements, user must approve or confirm the on-ramp request in their Holyheld mobile app within 3 minutes. If the user declines, or lets the confirmation expire -- the transaction will fail.

(async () => {
  // you can locate token by address and network, or you can use a self token object
  const selectedToken = await sdk.getTokenByAddressAndNetwork('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', Network.ethereum)

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

  const data = await sdk.onRamp.requestOnRamp(
    walletClient,
    walletClient.account.address, // user wallet address
    selectedToken.address, // address of the token to arrive
    selectedToken.network, // network where tokens will arrive
    '1' // amount in EUR
  );
})();

Types:

type RequestResult = {
  requestUid: string; // ID of the on-ramp request credted
  chainId: number; // ID of the network where tokens will arrive
  token: Token; // Address of the token to arrive
  amountEUR: string; // amount of EUR charged from the user
  amountToken: string; // native amount of tokens received
  feeEUR: string; // network gas fee charged from the total transaction amount
  beneficiaryAddress: Address; // user wallet address where tokens will arrive
}

After creating the on-ramp request, user will need to confirm it in their Holyheld app.

watchRequestId Watch the on-ramp request by ID:

This method is used to await for the request outcome based on the user confirmation or rejection in the Holyheld app. There are only three possible outcomes of any request:

1. true if the request has been confirmed by the user and processed
2. false if the request has been declined by the user
3. An error if request was not processed, timed out, or HTTP request was not returned as OK

(async () => {
  const result = await sdk.onRamp.watchRequestId(
    requestUid, // request ID from response for the requestOnRamp method
    timeout // optional
  );
})();