RampAPI SDK

@rampapi/sdk is a browser SDK for embedding the RampAPI crypto on-ramp and off-ramp widget in web applications without relying on global script state.

Install

npm install @rampapi/sdk

React Usage

The SDK mounts the widget into a DOM element. In React, keep that element in a ref, create the SDK client inside an effect, and destroy it during cleanup.

import { useEffect, useRef } from 'react';
import { createRampapi } from '@rampapi/sdk';

export function RampapiWidget() {
  const hostRef = useRef<HTMLDivElement | null>(null);

  useEffect(() => {
    if (!hostRef.current) return;

    const rampapi = createRampapi({
      onOrderStatusChange: (payload) => {
        console.log('RampAPI order status changed', payload);
      },
    });

    rampapi.run({
      host: hostRef.current,
      project_id: 'your-project-id',
      width: '100%',
      height: '720px',
      radius: {
        component: '16px',
        container: '20px',
        panel: '12px',
        item: '16px',
        control: '10px',
        round: '9999px',
      },
      logo: {
        url: 'https://partner.example/assets/logo.svg',
        size: { width: '120px', height: '32px' },
      },
      theme: 'dark',
      lang: 'en',
      operation: 'buy',
      currency_from: { currency: 'RUB' },
      currency_to: { currency: 'USDT', network: 'TRC-20' },
    });

    return () => {
      rampapi.destroy();
    };
  }, []);

  return <div ref={hostRef} style={{ width: '100%', minHeight: 720 }} />;
}

To update an already mounted widget, call restart() with only the parameters that changed:

rampapi.restart({
  theme: 'light',
  currency_to: { currency: 'USDT', network: 'ERC-20' },
});

Appearance-only parameters can be updated without reloading the iframe:

rampapi.updateAppearance({
  logo: null,
  radius: {
    component: '24px',
    container: '18px',
    panel: '14px',
    item: '12px',
    control: '8px',
    round: '9999px',
  },
});

Vanilla Usage

import { createRampapi } from '@rampapi/sdk';

const host = document.getElementById('rampapi-widget');

if (!(host instanceof HTMLDivElement)) {
  throw new Error('RampAPI host element was not found');
}

const rampapi = createRampapi();

rampapi.run({
  host,
  project_id: 'your-project-id',
  theme: 'dark',
});

In the npm SDK, host and project_id are required at the type level for run() and mount().

API

createRampapi(options?)

Recommended usage is createRampapi() without arguments.

Optional options:

• internalProjectId Advanced option for first-party RampAPI integrations. It enables same-window theme relay only when the running project_id matches this value. Merchants usually do not need it.
• onOrderStatusChange Callback fired when the widget reports an order status update.
• onSellTransferData Callback fired when the widget reports transfer data for sell flows.

rampapi.run(params)

run() mounts the widget and sends the initial configuration.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | host | HTMLDivElement | Yes | DOM element where the SDK will create or reuse the iframe. | | project_id | string | Yes | Merchant project identifier. | | width | string | No | Iframe width and widget content max-width. The iframe defaults to 100%; content defaults to var(--content-width) (420px on desktop and 100% on mobile). | | height | string | No | Iframe height and widget content max-height. The iframe defaults to 100%; content defaults to 670px on desktop and 100% on mobile. | | radius | Radius | No | Partial radius overrides for the widget shell, containers and option tiles, panels, items, compact controls, and round shapes. | | logo | Logo \| null | No | Custom brand logo. Omit it to use NeoPass, or pass null to hide the logo. | | redirect_url | string | No | URL used after flow completion when redirect behavior is enabled. | | partner_token | string | No | Partner JWT for silent user login during widget initialization. | | email | string | No | Prefilled user email. | | order_id | string | No | Existing order UUID used to open status or transfer flow. | | currency_from | PrefillCurrency | No | Source currency prefill. | | currency_to | PrefillCurrency | No | Target currency prefill. | | from_amount | string | No | Source amount prefill. | | fix_from_amount | boolean | No | Locks the source amount field. | | to_amount | string | No | Target amount prefill. | | fix_to_amount | boolean | No | Locks the target amount field. | | operation | 'buy' \| 'sell' | No | Initial widget flow. | | method | 'card' \| 'sbp' \| string | No | Payment method for buy flow. | | fix_method | boolean | No | Locks the selected payment method. | | theme | string | No | Initial widget theme key. | | lang | SupportedLocale | No | Initial widget language. Current values are exported as SUPPORTED_LOCALES. | | palette | Palette | No | Runtime widget palette with custom themes and color tokens. | | share_token | string | No | KYC Share Token used to sync verification. | | addresses | PrefillAddress[] | No | Receive address prefill for current currency pairs. | | refund_addresses | PrefillAddress[] | No | Refund address prefill for sell flow. |

Parameter object shapes:

type PrefillCurrency = {
  currency: string;
  network?: string;
  fixed?: boolean;
};

type PrefillAddress = {
  address: string;
  currency: string;
  network?: string;
  fixed?: boolean;
};

type Radius = {
  component?: string;
  container?: string;
  panel?: string;
  item?: string;
  control?: string;
  round?: string;
};

type Logo = {
  url: string;
  size?: {
    width?: string;
    height?: string;
  };
};

type Palette = Record<
  string,
  {
    text?: Partial<Record<'primary' | 'secondary' | 'white', string>>;
    bg?: Partial<Record<'primary' | 'secondary' | 'white' | 'outside' | 'black', string>>;
    grey?: Partial<Record<'primary', string>>;
    button?: Partial<Record<'primary' | 'text', string>>;
    encore?: Partial<
      Record<'error' | 'success' | 'warning' | 'accent' | 'info' | 'shadow', string>
    >;
  }
>;

Palette theme names may be custom, for example light, dark, or a merchant-specific theme name. Group and token names mirror the RampAPI default design tokens and are converted to CSS variables at runtime, for example bg.primary becomes --color-bg-primary and text.secondary becomes --color-text-secondary.

Unknown groups, unknown tokens, unsafe object keys, and unsafe CSS values are ignored at runtime.

Radius values accept non-negative numbers with px, rem, em, %, vh, vw, vmin, or vmax. Unitless values are converted to pixels ("16" becomes "16px"). Unknown keys, negative values, CSS functions, and malformed values are ignored. Defaults are 16px for component, 20px for container, 12px for panel, 16px for item, 10px for control, and 9999px for round. Without an explicit component override, the responsive mobile shell keeps its existing 0 radius.

panel inherits an explicitly passed container when omitted, and control inherits an explicitly passed item. round keeps circular and pill geometry independently, but an explicit zero item also sets an omitted round to zero. Therefore the existing compact configuration below removes rounding from every widget surface, including inputs, coin options, burger options, avatars, switches, and status indicators:

radius: {
  component: '0',
  container: '0',
  item: '0',
}

Pass round: '9999px' together with zero item when semantic circles and pills should stay round.

In direct URL mode, pass radius as URL-encoded JSON, for example radius=%7B%22component%22%3A%2224px%22%2C%22container%22%3A%2218px%22%2C%22item%22%3A%2212px%22%7D.

Custom logos are rendered as an <img> and never injected as HTML. logo.url must be an absolute HTTPS URL; HTTP is accepted only for localhost, 127.0.0.1, 0.0.0.0, or [::1] during local development. Relative URLs, URL credentials, control characters, and data:, blob:, javascript:, or other schemes are rejected. The image request uses no-referrer, and a rejected URL or image loading error falls back to the NeoPass logo. Use logo: null when the logo must be hidden intentionally.

Logo sizes accept non-negative unitless pixel values or px, rem, em, %, vh, vw, vmin, and vmax. Values are capped at 4096px, 256rem/em, or 100%/viewport units. Negative values, CSS functions, unknown keys, and malformed values are ignored. Without size, custom logos keep the default maximum width of 103px and automatic height.

In direct URL mode, pass a custom logo as URL-encoded JSON. Pass logo=null to hide it:

logo=%7B%22url%22%3A%22https%3A%2F%2Fpartner.example%2Flogo.svg%22%2C%22size%22%3A%7B%22width%22%3A%22120px%22%2C%22height%22%3A%2232px%22%7D%7D

rampapi.restart(params)

Updates the existing iframe configuration using the current params as a base. You only need to pass fields that should change.

rampapi.updateAppearance(params)

Updates lang, logo, palette, radius, or theme without reloading the iframe.

rampapi.destroy()

Removes the iframe and detaches SDK event listeners.

Versioning

The package version is written to dist/sdk/package.json during yarn build:sdk.

Version priority:

1. RAMPAPI_SDK_VERSION, for example 1.2.3 or v1.2.3.
2. CI_COMMIT_TAG, for example v1.2.3 or sdk/v1.2.3.
3. Non-tag CI builds use the root package.json version as a base and increment it from CI_PIPELINE_IID or CI_PIPELINE_ID. With the current root version 0.0.0, pipeline 1 becomes 0.0.1, 99 becomes 0.0.99, and 100 becomes 0.1.0.
4. Local builds without CI variables fall back to 0.0.1.

The GitLab publish job is currently manual on the master branch. For a tag-based npm release, run the publish job in a tag pipeline or set RAMPAPI_SDK_VERSION explicitly for the publish pipeline.