@rampnow/sdk

JavaScript/TypeScript SDK for embedding the Rampnow onramp/offramp widget into any website or web app.

Installation

npm install @rampnow/sdk
# or
yarn add @rampnow/sdk
# or
pnpm add @rampnow/sdk

CDN (no bundler)

<script src="https://cdn.jsdelivr.net/npm/@rampnow/sdk/dist/rampnow-sdk.umd.js"></script>

Integration modes

The SDK supports three ways to integrate the Rampnow widget:

| Mode | How it works | When to use | | ------------ | ----------------------------------------------------------------------------- | ---------------------------------------------- | | Overlay | SDK injects a full-screen modal overlay with the widget iframe inside | Default — quickest to set up | | Embedded | Widget iframe is mounted inside a DOM element you control (containerId) | When you want the widget inline in your layout | | Redirect | RampnowSdk.createRedirectUrl() builds a URL you open in a new tab or window | Native apps, email links, server-side flows |

Quick start

import { RampnowSdk, RampnowEventType } from "@rampnow/sdk"

const sdk = new RampnowSdk({
  apiKey: "pk_live_xxxxxxxxxxxx",
  srcCurrency: "EUR",
  dstCurrency: "ETH",
  walletAddress: "0xYourWalletAddress",
})

sdk
  .on(RampnowEventType.ORDER_COMPLETED, (e) => {
    console.log("Order completed:", e.payload.orderUid)
  })
  .init()

Configuration

Pass a config object to new RampnowSdk(config).

| Option | Type | Default | Description | | ------------------ | ------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------- | | apiKey | string | required | Your partner public API key | | widgetUrl | string | https://app.rampnow.io | Override the widget base URL | | containerId | string | — | ID of a DOM element to mount the iframe into. If omitted, an overlay modal is created automatically | | width | string \| number | 450 | Iframe width (px) | | height | string \| number | 700 | Iframe height (px) | | orderType | 'buy' \| 'sell' | — | Pre-select the order direction | | srcCurrency | string | — | Pre-select source (fiat) currency, e.g. 'EUR', 'USD' | | srcChain | string | — | Pre-select source chain | | dstCurrency | string | — | Pre-select destination (crypto) currency, e.g. 'ETH', 'BTC' | | dstChain | string | — | Pre-select destination chain, e.g. 'ethereum', 'bitcoin' | | paymentMode | string | — | Pre-select payment method, e.g. 'SEPA', 'ACH' | | srcAmount | string | — | Pre-fill the source amount | | walletAddress | string | — | Pre-fill the recipient wallet address | | walletAddressTag | string | — | Wallet address memo/tag (for XRP, XLM, etc.) | | externalOrderId | string | — | Your own order ID for cross-referencing | | lockFields | LockField[] | — | Lock individual quote-page fields so the user cannot change them. See Locking fields | | hideOrderTabs | boolean | false | Hide the Buy/Sell tab in the widget header. Pair with orderType to pin the widget to one direction | | utm_source | string | — | UTM tracking | | utm_medium | string | — | UTM tracking | | utm_campaign | string | — | UTM tracking |

Locking fields

Use lockFields to make individual quote-page inputs non-interactive — the picker won't open and the value cannot be changed by the user. Combine with the matching prefill option to set the locked value; locking on its own keeps the system default.

type LockField =
  | "srcAsset"
  | "srcAmount"
  | "dstAsset"
  | "paymentMode"
  | "walletAddress"

| Field | Locks | | --------------- | --------------------------------------------------- | | srcAsset | Source chain + currency picker | | srcAmount | Source amount input (and quick-amount chips) | | dstAsset | Destination chain + currency picker | | paymentMode | Payment-mode selector | | walletAddress | Recipient wallet selector (no add/change recipient) |

Examples

Pin destination to your token; let the user pick fiat and amount:

new RampnowSdk({
  apiKey: "pk_live_xxx",
  dstCurrency: "USDC",
  dstChain: "ethereum",
  lockFields: ["dstAsset"],
})

Pin everything (full-checkout flow — user only confirms):

new RampnowSdk({
  apiKey: "pk_live_xxx",
  srcCurrency: "EUR",
  srcChain: "FIAT",
  srcAmount: "100",
  dstCurrency: "ETH",
  dstChain: "ethereum",
  paymentMode: "SEPA",
  walletAddress: "0xYourWalletAddress",
  lockFields: [
    "srcAsset",
    "srcAmount",
    "dstAsset",
    "paymentMode",
    "walletAddress",
  ],
})

Locking does not validate the prefilled value against your account's allowed routes — pass values that are supported by your partner configuration.

API

new RampnowSdk(config)

Creates an SDK instance. Validates apiKey and merges defaults. Does not open the widget yet — call .init().

sdk.init(): RampnowSdk

Opens the widget. If containerId is set, the iframe is mounted inside that element. Otherwise, a full-screen overlay modal is created. Returns this for chaining.

sdk.close(): void

Closes and removes the widget from the DOM.

sdk.on(eventType, callback): RampnowSdk

Subscribe to widget events. Returns this for chaining. Accepts three forms:

// Single event
sdk.on(RampnowEventType.ORDER_CREATED, (e) => {
  console.log(e.payload.orderUid)
})

// Array of events
sdk.on(
  [RampnowEventType.ORDER_CREATED, RampnowEventType.ORDER_COMPLETED],
  (e) => console.log(e.type, e),
)

// All events (wildcard)
sdk.on("*", (e) => console.log(e.type, e))

sdk.off(eventType, callback): RampnowSdk

Unsubscribe from widget events. Accepts the same forms as on() — a single event type, an array, or '*'.

sdk.send(commandType, payload): RampnowSdk

Send a command to the widget iframe. Returns this for chaining.

import { RampnowCommandType } from "@rampnow/sdk"

// Submit a crypto transaction hash for processing
sdk.send(RampnowCommandType.UPDATE_PAYMENT_DETAIL, {
  transactionHash: "0xabc123...",
})

sdk.isOpen: boolean

Whether the widget is currently open.

RampnowSdk.createRedirectUrl(config): string (static)

Builds a full widget URL from the given config without opening any iframe. Useful for redirect integrations, server-side link generation, or native apps.

const url = RampnowSdk.createRedirectUrl({
  apiKey: "pk_live_xxx",
  srcCurrency: "EUR",
  dstCurrency: "ETH",
  walletAddress: "0xYourWalletAddress",
})
// → "https://app.rampnow.io/order/quote?apiKey=pk_live_xxx&..."
window.open(url, "_blank")

Events

Subscribe with sdk.on(RampnowEventType.EVENT_NAME, callback).

| Event | Payload fields | Description | | ----- | -------------- | ----------- | | WIDGET_READY | — | Widget iframe has loaded and is ready | | WIDGET_CLOSED | — | Widget was closed (by user or sdk.close()) | | USER_AUTHENTICATED | — | User signed in | | ORDER_CREATED | { orderUid, orderType, srcCurrency, srcChain, srcAmount, dstCurrency, dstChain, paymentMode, cryptoTxnInfo?, bankTxnInfo? } | Order was successfully created | | ORDER_PAYMENT_PROCESSING | { orderUid, status, paymentStatus } | Payment is being processed | | ORDER_PAYMENT_COMPLETED | { orderUid, status, paymentStatus } | Payment received by Rampnow | | ORDER_PAYMENT_FAILED | { orderUid, status, paymentStatus } | Payment failed | | ORDER_COMPLETED | { orderUid, status, srcCurrency, srcChain, srcAmount, dstCurrency, dstChain, dstAmount, walletAddress, transactionHash, cryptoTxnInfo? } | Order fully completed, crypto sent | | ORDER_FAILED | { orderUid, status } | Order failed or was cancelled | | KYC_STARTED | — | User started identity verification | | KYC_SUBMITTED | — | User submitted KYC documents | | KYC_APPROVED | — | KYC approved | | KYC_REJECTED | — | KYC rejected | | ERROR | { message, code? } | An error occurred in the widget |

CryptoTxnInfo (in ORDER_COMPLETED)

| Field | Type | Description | | ----- | ---- | ----------- | | currency | string | Crypto currency code, e.g. "USDC" | | chain | string | Chain code, e.g. "ethereum" | | amount | string | Amount credited to the receiver | | receiverAddress | string | Address that received the crypto | | fillAmount | string | Filled/settled amount (may differ from amount on partial fills) | | senderAddress | string | Address that sent the crypto | | transactionHash | string | On-chain transaction hash | | status | string | Status of the transaction |

Commands

Commands are messages sent from the SDK to the widget using sdk.send(). This is the reverse direction of events.

Domain whitelisting required: For security, the widget only accepts commands from whitelisted origins. To whitelist your domain, please contact Rampnow. Commands sent from non-whitelisted origins will be silently ignored.

| Command | Payload fields | Description | | ----------------------- | --------------------- | ---------------------------------------------------- | | UPDATE_PAYMENT_DETAIL | { transactionHash } | Update payment detail with a crypto transaction hash |

Example: Submit a transaction hash from your wallet

import { RampnowSdk, RampnowEventType, RampnowCommandType } from "@rampnow/sdk"

const sdk = new RampnowSdk({ apiKey: "pk_live_xxx" })

// After your wallet completes a crypto transfer, send the hash to the widget
sdk.send(RampnowCommandType.UPDATE_PAYMENT_DETAIL, {
  transactionHash: "0xabc123...",
})

// Listen for confirmation that the payment is being processed
sdk.on(RampnowEventType.ORDER_PAYMENT_PROCESSING, ({ payload }) => {
  console.log("Payment updated:", payload.paymentStatus)
})

Usage examples

Overlay Widget (modal)

const sdk = new RampnowSdk({ apiKey: "pk_live_xxx" })
sdk.init()
// A full-screen modal overlay is injected into document.body

Embedded Widget (inline)

<div id="rampnow-widget" style="width:450px;height:700px"></div>

const sdk = new RampnowSdk({
  apiKey: "pk_live_xxx",
  containerId: "rampnow-widget",
})
sdk.init()
// The widget iframe is mounted inside #rampnow-widget

Redirect to Widget

// Build the URL and open in a new tab — no iframe required
const url = RampnowSdk.createRedirectUrl({
  apiKey: "pk_live_xxx",
  srcCurrency: "EUR",
  dstCurrency: "ETH",
  walletAddress: "0xYourWalletAddress",
})
window.open(url, "_blank")

Listen to order events

sdk
  .on(RampnowEventType.ORDER_CREATED, ({ payload }) => {
    // Save orderUid to your backend
    saveOrder(payload.orderUid, payload.srcCurrency, payload.dstCurrency)
  })
  .on(RampnowEventType.ORDER_COMPLETED, ({ payload }) => {
    // payload.cryptoTxnInfo has on-chain transaction details
    console.log("Tx hash:", payload.transactionHash)
    showSuccessMessage()
  })
  .on(RampnowEventType.ORDER_FAILED, ({ payload }) => {
    console.error("Order failed:", payload.status)
  })
  .init()

Listen to multiple events at once

// Subscribe to a group of related events
sdk.on(
  [
    RampnowEventType.ORDER_CREATED,
    RampnowEventType.ORDER_COMPLETED,
    RampnowEventType.ORDER_FAILED,
  ],
  (e) => {
    analytics.track("rampnow_order_event", { type: e.type })
  },
)

// Subscribe to all events with a wildcard
sdk.on("*", (e) => {
  console.log(`[Rampnow] ${e.type}`, e)
})

Open on button click, close programmatically

const sdk = new RampnowSdk({ apiKey: "pk_live_xxx" })

document
  .getElementById("buy-crypto")
  .addEventListener("click", () => sdk.init())

sdk.on(RampnowEventType.ORDER_COMPLETED, () => {
  sdk.close()
  showThankYouPage()
})

CDN usage (no bundler)

<script src="https://cdn.jsdelivr.net/npm/@rampnow/sdk/dist/rampnow-sdk.umd.js"></script>
<script>
  const { RampnowSdk: SDK, RampnowEventType } = window.RampnowSdk

  // Overlay
  const sdk = new SDK({ apiKey: "pk_live_xxx" })
  sdk.on(RampnowEventType.ORDER_COMPLETED, (e) => {
    console.log("Done:", e.payload.orderUid)
  })
  sdk.init()

  // Redirect (no iframe)
  const url = SDK.createRedirectUrl({
    apiKey: "pk_live_xxx",
    srcCurrency: "EUR",
  })
  window.open(url, "_blank")
</script>

React hook

import { useRampnowSdk } from "@rampnow/sdk/react"
import { RampnowCommandType, RampnowEventType } from "@rampnow/sdk"
import { useEffect } from "react"

function BuyCryptoButton() {
  const { init, close, send, on, isOpen } = useRampnowSdk({
    apiKey: "pk_live_xxx",
    srcCurrency: "EUR",
    dstCurrency: "ETH",
  })

  useEffect(() => {
    on(RampnowEventType.ORDER_COMPLETED, (e) => {
      console.log("Completed:", e.payload.orderUid)
      close()
    })
  }, [on, close])

  return <button onClick={init}>{isOpen ? "Loading…" : "Buy Crypto"}</button>
}

Getting your API key

Log in to the Rampnow Partner Portal and navigate to API Hub to find your public API key (pk_live_...).