Ramp JavaScript SDK Reference

@ramp-network/ramp-instant-sdk is a library that allows you to easily integrate the Ramp widget into your web app and communicate with it.

While using an SDK is not necessary, it is strongly recommended.

It's written with TypeScript, so typings come out of the box and are always up-to-date.

Installation

You can find the package here.

Install via Yarn:

yarn add @ramp-network/ramp-instant-sdk

Install via npm:

npm install @ramp-network/ramp-instant-sdk

Example usage

import { RampInstantSDK } from '@ramp-network/ramp-instant-sdk';
new RampInstantSDK({
hostAppName: 'your dApp',
hostLogoUrl: 'https://yourdapp.com/yourlogo.png',
swapAmount: '150000000000000000000', // 150 ETH in wei
swapAsset: 'ETH_ETH',
userAddress: 'user blockchain address',
}).on('*', event => console.log(event)).show();
// That's it!

Initialization & configuration

@ramp-network/ramp-instant-sdk exports the RampInstantSDK class. As a principle, one instance of the class corresponds to one instance of the widget. If a user closes the widget, you need to create a new instance of the RampInstantSDK class.

Configuration

The RampInstantSDK constructor accepts a configuration object. A detailed list of the available configurations with examples can be found here.

If any of the supplied config values are invalid, you'll be notified about it via the console in your devtools.

If you fail to supply any of the required config values, the widget will display an error page and won't start.

Initialization

Just call new RampInstantSDK(config) - this will run some prep work for the widget, but won't display it yet. In order to display the widget, run .show() on your instance of the RampInstantSDK class.

.show() adds the widget to the DOM - specifically, to the body element - starting from that moment, the semi-transparent overlay with a loader appears and the widget starts booting up.

NOTE: .show() is chainable.

Events

The Ramp widget sends some events that you can react to in your web app.

Each event has the following fields:

  • type - type of the event, i.e. what happened,
  • payload - any additional info related to the event,
  • widgetInstanceId - a random number-string - each widget instance has its own. You can use this if you have many instances of the widget and want to distinguish which event came from which instance.

Available events

// Sent when the widget is closed
{
type: 'WIDGET_CLOSE',
payload: null,
widgetInstanceId: string,
}
// Sent when a purchase is created, but not yet fulfilled
{
type: 'PURCHASE_CREATED',
payload: {
purchase: IPurchase,
purchaseViewToken: string,
apiUrl: string,
},
widgetInstanceId: string,
}
// Sent when the widget is done fetching internal configuration and can be displayed.
// This is when the loader hides.
// NOTE: it's done automatically, you can call `.show()` immediately without waiting for this event
{
type: 'WIDGET_CONFIG_DONE',
payload: null,
widgetInstanceId: string,
}
// Sent when a user wants to close the widget and a confirmation modal is displayed
{
type: 'WIDGET_CLOSE_REQUEST',
payload: null,
widgetInstanceId?: string,
}
// Sent when a user cancels closing the widget window
{
type: 'WIDGET_CLOSE_REQUEST_CANCELLED',
payload: null,
}
// Sent when a user confirms closing the widget - this ends the flow
{
type: 'WIDGET_CLOSE_REQUEST_CONFIRMED',
payload: null,
}

The package also exports a RampInstantEvents type which is a type containing all possible events and RampInstantEventTypes which is an enum of all possible event type values.

Ramp Purchase object

Webhooks, purchase status API and PURCHASE_CREATED event expose an object with the following details about the purchase.

interface RampPurchase {
id: string;
endTime: string | null; // purchase validity time, ISO date-time string
asset: AssetInfo; // description of the purchased asset (address, symbol, name, decimals)
receiverAddress: string // blockchain address of the buyer
cryptoAmount: string; // number-string, in wei or token units
fiatCurrency: string; // three-letter currency code
fiatValue: number; // total value the user pays for the purchase, in fiatCurrency
assetExchangeRate: number; // price of 1 whole token of purchased asset, in fiatCurrency
assetExchangeRateEur: number; // price of 1 whole token of purchased asset, in EUR
fiatExchangeRateEur: number; // price of fiatCurrency in EUR
baseRampFee: number; // base Ramp fee before any modifications, in fiatCurrency
networkFee: number; // network fee for transferring the purchased asset, in fiatCurrency
appliedFee: number; // final fee the user pays (included in fiatValue), in fiatCurrency
paymentMethodType: PaymentMethodType; // type of payment method used to pay for the swap - see values below
finalTxHash?: string; // hash of the crypto transfer blockchain transaction, filled once available
createdAt: string; // ISO date-time string
updatedAt: string; // ISO date-time string
status: PurchaseStatus; // See available values below
purchaseViewToken: string; // secret API key that can be used to access info about this transaction via our API
}
type PaymentMethodType = 'MANUAL_BANK_TRANSFER' | 'AUTO_BANK_TRANSFER' | 'CARD_PAYMENT' | 'APPLE_PAY';
interface AssetInfo {
address: string | null; // token contract address for token assets, `null` for coins (e.g. ETH, BTC)
symbol: string; // asset symbol, for example `ETH`, `DAI`, `USDC`
chain: string; // asset chain, for example `ETH`, `BSC`, `POLKADOT`
type: string; // NATIVE for native assets (e.g. ETH, BTC, ELROND), or a token standard (e.g. ERC20)
name: string;
decimals: number; // token decimals, e.g. 18 for ETH/DAI, 6 for USDC
}

Purchase status

States before any payment attempt:

  • INITIALIZED: The purchase was initialized.

Payment progress states:

  • PAYMENT_STARTED: An automated payment was initiated, eg. via card or open banking.
  • PAYMENT_IN_PROGRESS: User completed the payment process.
  • PAYMENT_FAILED: The last payment was cancelled, rejected, or otherwise failed.
  • PAYMENT_EXECUTED: The last payment was successful.
  • FIAT_SENT: Outgoing bank transfer was confirmed on the buyer's account.
  • FIAT_RECEIVED: Payment was confirmed, final checks before crypto transfer.

Final outcome states:

  • RELEASING: Crypto release started – transfer transaction or escrow release() tx was sent.
  • RELEASED: Crypto asset was confirmed to be transferred to the buyer. A terminal state.
  • EXPIRED: The time to pay for the purchase was exceeded. A terminal state.
  • CANCELLED: The purchase was cancelled and won't be continued. A terminal state.

Subscribing to events

In order to subscribe to an event, use the .on(eventType, callback) method on your SDK instance.

The .on(eventType, callback) method accepts either a string with the event's type when you want to subscribe to a specific kind of an event or '*' for subscribing to any event.

callback is called each time a given event occurs.

In order to unsubscribe, call the .unsubscribe(eventType, callback) method with the event type and handler you want to stop receiving updates for.

NOTE: .on(eventType, callback) and .unsubscribe(eventType, callback) are chainable.

Widget DOM nodes

The popup widget version (variant: "auto|mobile|desktop") RampInstantSDK instance exposes a domNodes field that contains body, iframe, overlay, shadowHost and shadow elements.

  • body is a reference to your app's <body> element.

  • iframe is a reference to the widget's <iframe>.

  • overlay is a reference to the semi-transparent backdrop for the widget.

  • shadowHost is a reference to the node where all widget-related elements are kept.

  • shadow is a reference to the widget's shadow DOM root.

Widget window reference

The hosted widget version (variant: 'hosted-auto' | 'hosted-mobile' | 'hosted-desktop') RampInstantSDK instance exposes a widgetWindow field that is a reference to the created window.

API Reference

new RampInstantSDK(config): RampInstantSDK

Creates an instance of the SDK.

Params:

{
// 'ETH_ETH'/'ETH_DAI/...
swapAsset: string;
// int string - wei or token units
swapAmount: string;
// blockchain address of the buyer
userAddress: string;
// URL to your app's logo
hostLogoUrl: string;
// your app's name
hostAppName: string;
// *optional*
// allows to provide an alternative URL to load
// a non-production version of the widget
url?: string;
// *optional*
// allows you to choose how the widget is displayed
// 'auto' displays widget in the popup iframe, widget version (desktop|mobile) is determined automatically
// 'hosted-auto' opens widget in new tab/window, widget version (desktop|mobile) is determined automatically
// 'desktop' | 'hosted-desktop' forces the widget to use the desktop version
// 'mobile' | | 'hosted-mobile' forces the widget to use the mobile version
variant?: 'auto' | 'hosted-auto' | 'desktop' | 'mobile' | 'hosted-desktop' | 'hosted-mobile';
// *optional*
// if you chose one of the hosted variants, you can choose a URL the user will be redirected to
// after their purchase is completed
finalUrl?: string;
// your URL for webhook updates
webhookStatusUrl?: string;
}

Note: this also fetches the Poppins font which will be used by the widget.

Instance methods

on(type: RampInstantEventTypes | '*', callback: (event: RampInstantEvents) => void): sdkInstance

Registers the callback to be called each time an event with the given type is dispatched. If type is '*', callback will be called for every event, regardless of its type.

Returns the instance of the SDK it was called on.

unsubscribe(type: RampInstantEventTypes | '*', callback: (event: RampInstantEvents) => void): sdkInstance

Allows you to unsubscribe from receiving updates for a given event type and handler.

Returns the instance of the SDK it was called on.

show(): sdkInstance

Initializes the widget and adds it to your webapp's DOM.

Note: this can be only called once per SDK instance - if you want to open the widget again, you need to create a new one.