Onramp Flow

To onramp from a Holyheld account the following steps should be completed:

  1. Get settings and ensure that onramping 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. Optional. Get binary data to pass as swap parameters using convertEURToToken or convertTokenToEUR methods.
  5. Optional. Get an estimation of the network fee and the final token amount using getOnRampEstimation method.
  6. Call the requestOnRamp method to execute the transaction.

🔔 Please note! User will need to confirm the onramp request in their Holyheld app

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

There are six functions available to use:

  • getServerSettings - to get server settings.
  • validateAddress - to get wallet information.
  • convertEURToToken - to get a a token quote for a specific amount of EUR.
  • convertTokenToEUR - to get a EUR quote for a specific amount of tokens.
  • getOnRampEstimation - to get an onramp estimation.
  • requestOnRamp - to execute onramp.

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

🔔 Please note! Financial values are provided and consumed as strings to avoid floating point conversion problems.

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

Types:

type ServerExternalSettings = {
  external: {
    isTopupEnabled: boolean; // indicates if off-ramp is available at the moment
    isOnRampEnabled: true; // indicates if onramp is available at the moment
    maxTopUpAmountInEUR: string; // maximum amount (equivalent in EUR) that is allowed to be processed, for example: '1000'
    minTopUpAmountInEUR: string; // minimum amount (equivalent in EUR) that is allowed to be processed, for example: '5'
    maxOnRampAmountInEUR: string; // maximum amount in EUR that is allowed to be processed, for example: '1000'
    minOnRampAmountInEUR: string; // minimum amount in EUR that is allowed to be processed, for example: '5'
  };
  common: {
    topUpFeePercent: string; // fee (in percent) that is deducted when making an onramp operation, for 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. Wallet address must be a valid EVM (0x..., 42 chars) or Solana (Base58, ~32–44 chars) address.

🔔 Please note! Ethereum Name Service (ENS) and Solana Name Service (SNS) domains are not supported.

(async () => {
  const data = await holyheldSDK.validateAddress('0x000000000000000000000000000000000000dEaD');  // a wallet address could be preset or have to be entered by user, depends on what user flow you as a developer want to set
})();

Types:

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

convertTokenToEUR Convert token to EUR

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

EVM Networks

(async () => {
  const data = await holyheldSDK.evm.onRamp.convertTokenToEUR(
    '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // address of the token
    Network.ethereum, // network of the token
    '11.11' // native token amount
  );
  console.log('EUR amount is', data)
})();

convertEURToToken Convert EUR to token

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

EVM Networks

(async () => {
  const data = await holyheldSDK.evm.onRamp.convertEURToToken(
    '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // address of the token
    Network.ethereum, // network of the token
    '11.11' // EUR amount
  );
  console.log('token amount is', data)
})();

getOnRampEstimation Estimate the network fee and the final token amount

getOnRampEstimation method returns the network fee in EUR and the final token amount.

EVM Networks

(async () => {
  const data = await holyheldSDK.evm.onRamp.getOnRampEstimation(
    '0x...', // user wallet address
    '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // address of the token
    Network.ethereum, // network where tokens will arrive
    '1' // amount in EUR
  );
})();

Types:

type EstimateOnRampResult = {
  feeAmount: string; // network fee in EUR
  expectedAmount: string; // expected amount of the token excluding network fee
}

requestOnRamp Created onramp transaction request

This is the 'main' method to call that executes onramping from a Holyheld account.

🚨 Please note! As per security requirements, the user must approve the onramp request in their Holyheld mobile app within 3 minutes. If the user declines, or lets the confirmation expire -- the transaction will fail and will not be executed.

EVM Networks

(async () => {
  const data = await holyheldSDK.evm.onRamp.requestOnRamp(
    '0x...', // user wallet address
    '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // address of the token to arrive
    Network.ethereum, // network where tokens will arrive
    '1' // amount in EUR
  );
})();

Types:

type RequestOnRampResult = {
  requestUid: string; // ID of the onramp request created
  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 onramp request, user will need to confirm it in their Holyheld app.

watchRequestId Watch the onramp 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. { success: true } or { success: true, hash: '0x...' } if the request has been confirmed by the user and processed
  2. { success: 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 data = await holyheldSDK.evm.onRamp.watchRequestId(
    requestUid, // request ID from response for the requestOnRamp method
    options // optional
  );
})();

Types:

type WatchOnRampRequestIdOptions = {
  timeout?: number; // timeout in ms
  waitForTransactionHash?: boolean;
};

type WatchOnRampResult = {
  success: boolean; // successful or not
  hash?: string; // transaction hash. Present if "waitForTransactionHash" is true in request options and "success" is true
}