JavaScript SDK

Import

import { RampInstantSDK } from '@ramp-network/ramp-instant-sdk';

Constructor

new RampInstantSDK({...config parameters...}): RampInstantSDK

Example

let widget = new RampInstantSDK({
  hostAppName: 'Your Dapp',
  hostLogoUrl: 'https://yourdapp.com/yourlogo.png',
  swapAmount: '150000000000000000000', // 150 ETH in wei
  swapAsset: 'ETH',
  userAddress: '0xab5801a7d398351b8be11c439e05c5b3259aec9b',
  userEmailAddress: 'user@network.com',
  webhookStatusUrl: 'https://my.domain/callback/123/'
});

Creates an instance of the SDK.

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

Config parameters

{
// 'ETH' or 'DAI'
swapAsset: string;

// int string - wei or token units
swapAmount: string;

// 0x-prefixed ETH address of the buyer
userAddress: string;

// URL to your app's logo
hostLogoUrl: string;

// your app's name
hostAppName: string;

// _optional_
// Email address of the buyer
userEmailAddress: string;

// _optional_
// allows to provide an alternative URL to load
// a non-production version of the widget
url?: string;

// _optional_
// allows you to opt-in to our mobile version beta
// 'desktop' forces the widget to use the desktop version
// 'mobile' forces the widget to use the mobile version
// 'auto' picks the right version depending on user device
// for now, 'desktop' is the default value here
// in a future release, 'auto' will be the default.
variant?: 'desktop' | 'mobile' | 'auto';

// _optional_
// your URL for webhook updates of the purchase status
webhookStatusUrl?: string;
}

Methods

on(type, callback)

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, callback)

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

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.

Events

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

Widget status events

// Sent when the widget is closed
{
  type: 'WIDGET_CLOSE',
  payload: null,
  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,
}

Purchase status events

// Sent when a purchase is created, but not yet fulfilled
{
  type: 'PURCHASE_CREATED',
  payload: {
    purchase: RampInstantPurchase,
    purchaseViewToken: string,
    apiUrl: string,
  },
  widgetInstanceId: string,
}

// Sent when the user receives their crypto
{
  type: 'PURCHASE_SUCCESSFUL',
  payload: {
    purchase: RampInstantPurchase,
  },
  widgetInstanceId: string,
}

// Sent when a purchase fails (for any reason)
{
  type: 'PURCHASE_FAILED',
  payload: null,
  widgetInstanceId: string,
}

Listen to particular event

import { RampInstantSDK } from "@ramp-network/ramp-instant-sdk";

let widget = new RampInstantSDK({...}).show();

widget.on('WIDGET_CLOSE', (event) => {
// ... do something useful
});

Listen to all events

import { RampInstantSDK } from "@ramp-network/ramp-instant-sdk";

let widget = new RampInstantSDK({...});

widget.on('*', (event) => {
  // ... do something useful
});

RampInstantPurchase object

Events like PURCHASE_CREATED and PURCHASE_SUCCESSFUL expose an object with the following details of the purchase.

interface RampInstantPurchase {
  id: number;
  endTime: string | null;  // ISO-formatted datestring
  tokenAddress: string | null;  // [DEPRECATED - use asset.address] 0x-prefixed ETH address for ERC-20 tokens, `null` for ETH
  asset: AssetInfo;  // description of the purchased asset (ETH/token)
  escrowAddress?: string;  // 0x-prefixed ETH address, set after escrow `create()` tx is confirmed
  receiverAddress: string  // 0x-prefixed ETH address of the buying user
  cryptoAmount: string;  // number-string in wei or token units
  ethAmount?: string;  // [DEPRECATED - use cryptoAmount] cryptoAmount for ETH purchases
  tokenAmount?: string;  // [DEPRECATED - use cryptoAmount] cryptoAmount for token purchases
  fiatCurrency: string;  // three-letter currency code, e.g. `GBP`
  fiatValue: number;  // in the selected currency, e.g. in GBP
  assetExchangeRate: number;  // the asset exchange rate at the moment of escrow creation
  poolFee: number;  // in the same currency as `fiatValue`
  rampFee: number;   // in the same currency as `fiatValue`
  purchaseHash: string;  // 0x-prefixed hash of certain purchase details, used in blockchain events
  purchaseViewToken: string; // Access token to retrieve purchase data via API
  actions: PurchaseAction[];  // Low-level state changes of the purchase
}

interface AssetInfo {
  address: string | null;  // 0x-prefixed address for ERC-20 tokens, `null` for ETH
  symbol: string;  // asset symbol, for example `ETH`, `DAI`, `USDC`
  name: string;
  decimals: number;  // token decimals, e.g. 18 for ETH/DAI, 6 for USDC
}

Purchase Actions

Actions list represents history of purchase state changes.

interface PurchaseAction {
  id: number;
  newStatus: PurchaseStatus; // see below for possible values
  timestamp: string; // ISO-formatted datestring
  details?: string; // additional details for some actions, see below
}

Here is a list of possible actions:

  • INITIALIZED - The swap was initialized.
  • ESCROW_CREATING - Escrow create() tx was sent. Details: tx hash.
  • ESCROW_CREATED - Escrow create() tx was mined and confirmed. Details: escrow contract address.
  • PAYMENT_STARTED - An automated payment was initiated.
  • PAYMENT_IN_PROGRESS - User completed the payment process.
  • PAYMENT_FAILED - The last payment was canceled, rejected, or otherwise failed.
  • PAYMENT_EXECUTED - The last payment was successful.
  • FIAT_SENT - Wire transfer was confirmed on the buyer's account.
  • FIAT_RECEIVED - Wire transfer was confirmed on the pool owner's account.
  • FIAT_SETTLED - Added automatically when conditions for swap settlement are met.
  • RELEASING - Escrow release() tx was sent. Details: tx hash.
  • RELEASED - Escrow was released to the buyer. A terminal state.
  • RETURNING - Escrow returnFunds() tx was sent. Details: tx hash.
  • RETURNED - Escrow was returned to the pool. A terminal state.
  • ERROR - An irrecoverable error occured and the swap requires manual intervention.

Example event

⇩ click to view event JSON ⇩
{
  "type": "PURCHASE_CREATED",
  "payload": {
    "purchase": {
      "id": 310,
      "endTime": "2019-08-30T08:19:04.387Z",
      "tokenAddress": null,
      "asset": {
        "address": null,
        "symbol": "ETH",
        "name": "Ether",
        "decimals": 18
      },
      "escrowAddress": "0x9608662B400625d1E48045a875Ee7bc72db61383",
      "receiverAddress": "0x5cf9fecd31e783b1436252f22731be9cd0b64d17",
      "cryptoAmount": "30000000000000000",
      "ethAmount": "30000000000000000",
      "tokenAmount": null,
      "fiatCurrency": "GBP",
      "fiatValue": 3.79,
      "assetExchangeRate": 1.26154964636082,
      "poolFee": 0.056769734086236895,
      "rampFee": 0.0378464893908246,
      "actions": [
        {
          "id": 34,
          "newStatus": "INITIALIZED",
          "timestamp": "2019-08-28T08:17:37.613Z",
          "details": null
        },
        {
          "id": 35,
          "newStatus": "ESCROW_CREATING",
          "timestamp": "2019-08-28T08:17:38.492Z",
          "details": "0xacf1769519af0c4b13ff3c67563050e6c803fa2bce14f41c3aa7ff9594141388"
        },
        {
          "id": 36,
          "newStatus": "ESCROW_CREATED",
          "timestamp": "2019-08-28T08:19:04.387Z",
          "details": "0x9608662B400625d1E48045a875Ee7bc72db61383"
        },
        {
          "id": 37,
          "newStatus": "FIAT_RECEIVED",
          "timestamp": "2019-08-28T08:21:17.601Z",
          "details": null
        },
        {
          "id": 38,
          "newStatus": "FIAT_SETTLED",
          "timestamp": "2019-08-28T08:21:17.647Z",
          "details": null
        },
        {
          "id": 39,
          "newStatus": "RELEASING",
          "timestamp": "2019-08-28T08:21:19.826Z",
          "details": "0xe614d2ab0182a0e14c2c36d3dff842a80eadb2db51d35d9e967a4a86b66095ca"
        },
        {
          "id": 40,
          "newStatus": "RELEASED",
          "timestamp": "2019-08-28T08:23:05.308Z",
          "details": null
        }
      ]
    },
    "purchaseViewToken": "hd943h67y...yzys",
    "apiUrl": "https://api-instant.ramp.network/api"
  },
  "widgetInstanceId": "1646168196"
}

DOM

RampInstantSDK instance exposes a domNodes field that contains body, iframe, overlay, shadowHost and shadow elements.

  • [SDK instance].domNodes.body - your app's <body> element.

  • [SDK instance].domNodes.iframe - the widget's <iframe>.

  • [SDK instance].domNodes.overlay - the semi-transparent backdrop for the widget.

  • [SDK instance].domNodes.shadowHost - the node where all widget-related elements are kept.

  • [SDK instance].domNodes.shadow - the widget's shadow DOM root.