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:

1. Node.js and npm are installed on your system.

2. An Ethereum wallet with some testnet cryptocurrency (we'll be using the Alfajores testnet for this tutorial).

3. An account with OneRamp to obtain your client's public key and secret key.

4. 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()