How to offramp your users to mobile money in a node js script.
Tutorial - Intergrating web3 using the oneramp sdk
In this tutorial, we will walk you through the process of integrating the OneRamp SDK npm package into your web3 project. This SDK allows you to seamlessly offramp funds from your web3 project to mobile money, making it easier for your users to access their cryptocurrency holdings.
Prerequisites
Before you begin, make sure you have the following prerequisites:
Node.js and npm are installed on your system.
An Ethereum wallet with some testnet cryptocurrency (we'll be using the Alfajores testnet for this tutorial).
An account with OneRamp to obtain your client's public key and secret key.
Some test funds are tUSDT in your address. You can get some here.
Set Up Your Project
Start by creating a new directory for your project if you haven't already:
mkdir my-web3-project
cd my-web3-project
Initialize a new Node.js project:
npm init -y
Install the Required Dependencies
To use the OneRamp SDK, you'll need to install the @oneramp/sdk
package and the ethers
package, which is a popular Ethereum library for interacting with smart contracts and wallets.
Additionally, we'll use the dotenv
package to manage environment variables.
Install the required dependencies:
npm install @oneramp/sdk ethers dotenv
Create a OneRamp Account
If you haven't already, create an account on OneRamp. This will allow you to obtain your client's public key and secret key, which are essential for interacting with the OneRamp service.
Create a .env
File
Create a .env
file in your project's root directory to store sensitive information like your private key and OneRamp credentials. Replace the values with your actual credentials:
PRIVATEKEY=your_ethereum_private_key
MUMBAI_PROVIDER="MUMBAI RPC"
You can find the MUMBAI_PROVIDER
from Alchemy
Write the Integration Code
Now, let's write the integration code. Create a JavaScript file (e.g., oneramp-integration.js
) and add the following code:
We start by importing the necessary Node.js modules and libraries required for our integration:
OneRamp
and ethers
are imported from their respective packages. OneRamp
is the primary class from the OneRamp SDK, and ethers
is a library for interacting with Ethereum.
We also import dotenv
to help us load environment variables stored in a .env
file.
// Import necessary modules
const { OneRamp } = require('@oneramp/sdk')
const { ethers } = require('ethers')
require('dotenv').config()
// Load private key from environment variables
const { PRIVATEKEY: privateKey, MUMBAI_PROVIDER } = process.env
Destructure assignment to extract the values of PRIVATEKEY
and MUMBAI_PROVIDER
from the environment variables specified in the .env
file. These values will be used to set up our Ethereum provider and wallet.
// Load private key from environment variables
const { PRIVATEKEY: privateKey, MUMBAI_PROVIDER } = process.env
Create a provider using the ethers.providers.JsonRpcProvider
class. and pass the MUMBAI_PROVIDER
URL obtained from our environment variables, which connects the code to the Mumbai testnet.
This provider will allow us to interact with the Mumbai blockchain.
// Create an ethers provider that connects to the Alfajores testnet
const provider = new ethers.providers.JsonRpcProvider(MUMBAI_PROVIDER)
Next, create a wallet using the private key extracted from the environment variables and the provider we established earlier. This wallet will be used to sign transactions and perform various operations on the blockchain.
// Create a wallet using the private key and the provider
const signer = new ethers.Wallet(privateKey, provider)
Specify the client public key (clientPub
) and secret key (secretKey
) obtained from the OneRamp dashboard. These keys are essential for authentication when interacting with the OneRamp service.
Create an instance of the
OneRamp
class, passing in the following parameters:'mumbai'
: This specifies the environment we are using (Mumbai testnet in this case).clientPub
: The client public key for OneRamp authentication.secretKey
: The secret key for OneRamp authentication.provider
: The Ethereum provider we created earlier.signer
: The Ethereum wallet we created earlier.
// Application keys from https://dashboard.oneramp.io
const clientPub = 'YOUR_CLIENT_PUBLIC_KEY'
const secretKey = 'YOUR_SECRET_KEY'
const oneRamp = new OneRamp('mumbai', clientPub, secretKey, provider, signer)
Make sure to replace 'YOUR_CLIENT_PUBLIC_KEY'
with your OneRamp client public key and 'YOUR_SECRET_KEY'
with your OneRamp secret key.
Also, replace 'RECEIVER_MOBILE_MONEY_NUMBER'
with the recipient's mobile money number.
Before you offramp your users with real money, it's advisable to show them a price quote of the amount they’re going to receive. Fortunately, oneramp has a .quote()
returns a specific quote amount that the user will receive in their wallet.
Let's see how it works:
Define an asynchronous function called quote()
. This function is used to request a quote for offramping a specified amount of cryptocurrency (in this case, 5 USDT).
Inside the function, we use a
try...catch
block to handle potential errors.We call the
oneRamp.quote()
method with the amount (5) and the currency ('usdt') as parameters to obtain a quote for the offramp transaction.The result is logged to the console for inspection.
async function main() {
try {
const result = await oneRamp.offramp('usdt', 5, 'RECEIVER_MOBILE_MONEY_NUMBER')
console.log('====================================')
console.log(result)
console.log('====================================')
} catch (error) {
console.log(error)
}
}
Run the Integration
Now that you have the integration code in place, you can run it to test the OneRamp SDK in your project. Open your terminal and execute the following command:
node oneramp-integration.js
You should see output similar to the following:
====================================
{
recives: 4.9,
estimated_fee: 0.1,
amount: 5,
asset: 'usdt',
memo: 'Prices may vary with local service providers'
}
====================================
This output represents the quote for offramping 5 USDT to mobile money.
Now that we've got the quote too, we can go ahead and offramp the user to mobile money.
To do this, we use the .offramp()
which takes in a number of arguments:
The token/asset being paid
Amount
Phone number to receive the mobile money
Create a main()
function as below
async function main() {
try {
const result = await oneRamp.offramp('usdt', 5, '25677280949')
console.log('====================================')
console.log(result)
console.log('====================================')
} catch (error) {
console.log(error)
}
}
Run the Integration
Remember to call the main()
function at the bottom of the script and in your terminal run:
node oneramp-integration.js
Output:
====================================
{
success: true,
response: {
store: '650837563f03d6d25a857075',
txHash: '0x0f63fd8ffb0ef4c26ba6752e31f102e409ea8baf7e109a976a8c128ddb74e75e',
amount: 5,
fiat: 18715.3,
phone: '25677280949',
asset: 'usdt',
network: 'mumbai',
status: 'Pending',
env: 'DEV',
createdAt: '2023-09-22T10:02:50.613Z',
}
}
====================================
The transaction should be processed, and you will receive a response indicating the success or failure of the offramp transaction.
Congratulations! You have successfully integrated the OneRamp SDK into your web3 project, allowing you to offramp cryptocurrency to mobile money. You can now incorporate this functionality into your project to provide a seamless experience for your users.
For more information and detailed documentation, refer to the OneRamp SDK documentation.
That's it for this tutorial. Happy coding!
Full code:
// Import necessary modules
const { OneRamp } = require('@oneramp/sdk')
const { ethers } = require('ethers')
require('dotenv').config()
// Load private key from environment variables
const { PRIVATEKEY: privateKey, MUMBAI_PROVIDER } = process.env
// Create an ethers provider that connects to the Alfajores testnet
const provider = new ethers.providers.JsonRpcProvider(MUMBAI_PROVIDER)
// Create a wallet using the private key and the provider
const signer = new ethers.Wallet(privateKey, provider)
// Application keys from https://dashboard.oneramp.io
const clientPub = 'YOUR_CLIENT_PUBLIC_KEY'
const secretKey = 'YOUR_SECRET_KEY'
const oneRamp = new OneRamp('mumbai', clientPub, secretKey, provider, signer)
async function quote() {
try {
const quote = await oneRamp.quote(5, 'usdt')
console.log('====================================')
console.log(quote)
console.log('====================================')
} catch (error) {
console.log(error)
}
}
async function main() {
try {
const result = await oneRamp.offramp('usdt', 5, 'RECEIVER_MOBILE_MONEY_NUMBER')
console.log('====================================')
console.log(result)
console.log('====================================')
} catch (error) {
console.log(error)
}
}
quote()