Onramp Flow
To onramp from a Holyheld account the following steps should be completed:
- Get settings and ensure that onramping is available using
getServerSettings
method. - Check that selected wallet can transact using
validateAddress
method. - Provide two parameters: token and amount in EUR.
- Optional. Get binary data to pass as swap parameters using
convertEURToToken
orconvertTokenToEUR
methods. - Optional. Get an estimation of the network fee and the final token amount using
getOnRampEstimation
method. - Call the
requestOnRamp
method to execute the transaction.
🔔 Please note! User will need to confirm the onramp request in their Holyheld app
- 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:
{ success: true }
or{ success: true, hash: '0x...' }
if the request has been confirmed by the user and processed{ success: false }
if the request has been declined by the user- 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
}