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 off-ramp is available at the moment
    isTopupEnabled: boolean;
    // indicates if on-ramp is available at the moment
    isOnRampEnabled: true;
    // maximum amount (equivalent in EUR) that is allowed to be processed (off-ramp)
    maxTopUpAmountInEUR: string; // example: '1000'
    // minimum amount (equivalent in EUR) that is allowed to be processed (off-ramp)
    minTopUpAmountInEUR: string; // example: '5'
    // maximum amount in EUR that is allowed to be processed (on-ramp)
    maxOnRampAmountInEUR: string; // example: '1000'
    // minimum amount in EUR that is allowed to be processed (on-ramp)
    minOnRampAmountInEUR: 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(
    '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // address of the token
    Network.ethereum, // network of the 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(
    '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // address of the token
    Network.ethereum, // network of the 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.

🚨 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 () => {
  const data = await sdk.onRamp.requestOnRamp(
    walletClient,
    '0x...', // user wallet address
    '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // address of the token to arrive
    Network.ethereum, // 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
  );
})();