Web Sdk

Onramp Web SDK

A TypeScript/JavaScript SDK for integrating Onramp's crypto purchase widget into your web application.

Installation

Install the SDK using npm:

npm install @onramp.money/onramp-web-sdk

Or using yarn:

yarn add @onramp.money/onramp-web-sdk

Quick Start

1. Import the SDK

ES6/TypeScript:

import { OnrampWebSDK } from '@onramp.money/onramp-web-sdk';

CommonJS:

const { OnrampWebSDK } = require('@onramp.money/onramp-web-sdk');

Browser (UMD):

<script src="node_modules/@onramp.money/onramp-web-sdk/dist/onramp-web-sdk.umd.js"></script>

2. Initialize the SDK

const onrampSDK = new OnrampWebSDK({
  appId: YOUR_APP_ID, // Required: Get this from Onramp dashboard
  walletAddress: "0x...", // User's wallet address
  coinCode: "USDT", // Cryptocurrency to purchase
  network: "polygon", // Blockchain network
  fiatAmount: 100, // Amount in fiat currency
});

3. Show the Widget

// Display the widget as an overlay
onrampSDK.show();

4. Handle Events (Optional)

// Listen to transaction events
onrampSDK.on('TX_EVENTS', (event) => {
  console.log('Transaction event:', event);
});

// Listen to widget events
onrampSDK.on('WIDGET_EVENTS', (event) => {
  console.log('Widget event:', event);
});

// Listen to KYC events
onrampSDK.on('KYC_EVENTS', (event) => {
  console.log('KYC event:', event);
});

5. Close the Widget

// Close the widget programmatically
onrampSDK.close();

Usage Examples

Basic Overlay Mode

import { OnrampWebSDK } from '@onramp.money/onramp-web-sdk';

const onrampSDK = new OnrampWebSDK({
  appId: 12345,
  walletAddress: "0x742d35Cc6634C0532925a3b8d3Ac337F24d7D4",
  coinCode: "USDT",
  network: "polygon",
  fiatAmount: 50
});

// Show widget
onrampSDK.show();

// Handle events
onrampSDK.on('TX_EVENTS', (event) => {
  if (event.type === 'ONRAMP_WIDGET_TX_SUCCESSFUL') {
    console.log('Purchase successful!', event.data);
  }
});

Embedded Mode

<!-- Create a container for the widget -->
<div id="onramp-container" style="width: 100%; height: 600px;"></div>

const onrampSDK = new OnrampWebSDK({
  appId: 12345,
  containerId: "#onramp-container", // Embed in specific container
  walletAddress: "0x742d35Cc6634C0532925a3b8d3Ac337F24d7D4",
  coinCode: "USDT",
  network: "polygon"
});

onrampSDK.show();

Custom Theming

const onrampSDK = new OnrampWebSDK({
  appId: 12345,
  walletAddress: "0x742d35Cc6634C0532925a3b8d3Ac337F24d7D4",
  theme: {
    lightMode: {
      baseColor: "#6366f1", // color of all the primary elements, shades of this color get generated for secondary elements
      inputRadius: "8px", // radius of input boxes
      buttonRadius: "12px" // radius of buttons
    },
    darkMode: { // colors for dark mode
      baseColor: "#4f46e5",
      inputRadius: "8px",
      buttonRadius: "12px"
    },
    default: "lightMode" // the default mode when user opens the sdk (lightMode | darkMode)
  }
});

onrampSDK.show();

widgetUrl

You can pass the kycUrl you get from our api into the sdk to initialise it as a kyc sdk

const onrampSDK = new OnrampWebSDK({
  appId: 12345,
  widgetUrl:''
});

onrampSDK.show();

Configuration Options

Parameter	Type	Required	Description
appId	number	✅	Your application ID from Onramp dashboard
walletAddress	string	❌	User's wallet address
coinCode	string	❌	Cryptocurrency code (e.g., "USDT", "ETH")
network	string	❌	Blockchain network (e.g., "polygon", "ethereum")
fiatAmount	number	❌	Pre-filled fiat amount
coinAmount	number	❌	Pre-filled crypto amount
paymentMethod	number	❌	Preferred payment method ID
flowType	number	❌	1: Buy, 2: Sell, 3: Checkout, 4: Swap
containerId	string	❌	DOM element ID for embedded mode (e.g., "#container")
theme	object	❌	Custom theme configuration
sandbox	boolean	❌	Use sandbox environment for testing
lang	string	❌	Language code (e.g., "en", "es")
phoneNumber	string	❌	Pre-filled phone number
redirectUrl	string	❌	Redirect URL after completion
widgetUrl	string	❌	Kyc url containing kybData

Flow Types

• 1 (Buy/Onramp): Purchase cryptocurrency with fiat

• 2 (Sell/Offramp): Sell cryptocurrency for fiat

• 3 (Checkout): NFT/asset purchase flow

• 4 (Swap): Cryptocurrency swap

Event Types

Transaction Events (TX_EVENTS)

• ONRAMP_WIDGET_TX_INIT

• ONRAMP_WIDGET_TX_FINDING

• ONRAMP_WIDGET_TX_SELLING

• ONRAMP_WIDGET_TX_PURCHASING

• ONRAMP_WIDGET_TX_SENDING

• ONRAMP_WIDGET_TX_SENT

• ONRAMP_WIDGET_TX_COMPLETED

Widget Events (WIDGET_EVENTS)

• ONRAMP_WIDGET_READY

• ONRAMP_WIDGET_CLOSE_REQUEST_CONFIRMED

• ONRAMP_WIDGET_FAILED

• ONRAMP_WIDGET_CONTENT_COPIED

• ONRAMP_WIDGET_LOGIN_SUCCESS

• ONRAMP_WIDGET_NAVIGATION

KYC Events (KYC_EVENTS)

• ONRAMP_KYC_READY

• ONRAMP_KYC_PENDING

• ONRAMP_KYC_ERROR

• ONRAMP_KYC_REJECTED

• ONRAMP_KYC_CLOSE

Methods

show()

Displays the Onramp widget.

onrampSDK.show();

close()

Closes the Onramp widget.

onrampSDK.close();

on(eventType, callback)

Registers event listeners.

onrampSDK.on('TX_EVENTS', (event) => {
  // Handle transaction events
});

Error Handling

try {
  onrampSDK.show();
} catch (error) {
  console.error('Failed to show widget:', error.message);
}

// Handle widget events
onrampSDK.on('WIDGET_EVENTS', (event) => {
  if (event.type === 'ONRAMP_WIDGET_FAILED') {
    console.error('Widget failed:', event.data);
  }
});

Complete Example

<!DOCTYPE html>
<html>
<head>
    <title>Onramp Integration</title>
</head>
<body>
    <button id="buy-crypto">Buy Crypto</button>
    <div id="widget-container" style="width: 100%; height: 600px; display: none;"></div>

    <script src="node_modules/@onramp.money/onramp-web-sdk/dist/onramp-web-sdk.umd.js"></script>
    <script>
        const onrampSDK = new OnrampWebSDK({
            appId: 12345,
            walletAddress: "0x742d35Cc6634C0532925a3b8d3Ac337F24d7D4",
            coinCode: "USDT",
            network: "polygon",
            fiatAmount: 100
        });

        // Show widget on button click
        document.getElementById('buy-crypto').addEventListener('click', () => {
            onrampSDK.show();
        });

        // Handle successful transactions
        onrampSDK.on('TX_EVENTS', (event) => {
            if (event.type === 'ONRAMP_WIDGET_TX_SUCCESSFUL') {
                alert('Purchase successful!');
                onrampSDK.close();
            }
        });

        // Handle widget close
        onrampSDK.on('WIDGET_EVENTS', (event) => {
            if (event.type === 'ONRAMP_WIDGET_CLOSE_REQUEST_CONFIRMED') {
                console.log('Widget closed by user');
            }
        });
    </script>
</body>
</html>

Support

For questions and support:

• Documentation: https://docs.onramp.money

• Email: [e-mail]

• Website: https://onramp.money