Skip to main content

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.