SDK Configuration

Pass a config object to new RampnowSdk(config), useRampnowSdk(config) or RampnowSdk.createRedirectUrl(config). The SDK sends each order and display option to the widget as a URL parameter of the same name, so these are the same parameters the Widget takes.

const sdk = new RampnowSdk({
  apiKey: 'pk_YOUR_API_KEY',
  widgetUrl: 'https://app.sandbox.rampnow.io',
  orderType: 'buy',
  srcCurrency: 'EUR',
  srcChain: 'fiat',
  srcAmount: '250',
  dstCurrency: 'ETH',
  dstChain: 'ethereum',
  paymentMode: 'card',
  walletAddress: '0xUserWalletAddress',
  lockFields: ['dstAsset'],
  externalOrderId: 'your-order-1001',
})

SDK options

These options control the SDK itself and are not sent to the widget:

Option	Type	Default	Description
`widgetUrl`	`string`	`https://app.rampnow.io`	Widget host. Set `https://app.sandbox.rampnow.io` for sandbox.
`containerId`	`string`	—	DOM element ID for embedded mode. Omit for an overlay.
`width`	`string \| number`	`450`	Iframe width (px)
`height`	`string \| number`	`700`	Iframe height (px)

apiKey is required: the constructor throws [RampnowSdk] apiKey is required without it.

Order and display options

In the SDK, lockFields is an array (['srcAsset', 'dstAsset']) and boolean options take true. You don’t need to set prefill; the SDK adds it whenever paymentMode is set.

Order details

Parameter	Type	Description
`apiKey`	string	Required. Your public partner key. Without it the order isn’t attributed to your account.
`orderType`	`buy` \| `sell`	Order direction. Defaults to `buy`.
`srcCurrency`	string	Currency the user spends: fiat for `buy` (e.g. `EUR`), crypto for `sell` (e.g. `USDT`). Uppercase code. Needs `srcChain`.
`srcChain`	string	Chain of `srcCurrency`. Use `fiat` for fiat currencies, otherwise a chain code such as `ethereum`, `bitcoin` or `arbitrum-one`. Needs `srcCurrency`.
`dstCurrency`	string	Currency the user receives: crypto for `buy` (e.g. `ETH`), fiat for `sell` (e.g. `EUR`). Uppercase code. Needs `dstChain`.
`dstChain`	string	Chain of `dstCurrency`. `fiat` for fiat currencies. Needs `dstCurrency`.
`srcAmount`	string	Amount in the source currency, e.g. `250`.
`paymentMode`	string	Payment method for `buy`, payout method for `sell`. Lowercase, e.g. `card`, `apple_pay`, `google_pay`, `sepa`, `open_banking`, `pix`, `upi`, `ach`.
`walletAddress`	string	The user’s wallet address for `buy`. Pre-selected or pre-filled once the user signs in.
`walletAddressTag`	string	Memo or tag for chains that need one (XRP, XLM, etc.).
`externalOrderId`	string	Your own order ID. Stored on the order and returned as `externalOrderUid` in webhooks.

Currencies only take effect with their chain. srcCurrency is ignored unless srcChain is also set, and dstCurrency is ignored unless dstChain is also set. For example, pre-select EUR with srcCurrency=EUR&srcChain=fiat, not srcCurrency=EUR alone.

Defaults. Every parameter except apiKey is optional, and a missing or invalid value never shows an error to the user. Rampnow fills the gaps from your account’s live configuration: the first listed asset for the direction (usually the user’s local fiat for buy), a typical amount for that currency, and the first active payment or payout method for the asset. Pass the values you care about rather than relying on these. Valid currency and chain codes, and the payment methods enabled for your account, are listed under What’s Supported. Values are case-sensitive: paymentMode=SEPA is ignored, paymentMode=sepa works.

Display options

Parameter	Type	Description
`prefill`	`true`	Shows the `paymentMode` you passed as already selected. Without it, the user picks the method themselves. The SDK sets this for you whenever `paymentMode` is set.
`lockFields`	comma-separated list	Makes fields read-only: `srcAsset`, `srcAmount`, `dstAsset`, `paymentMode`, `walletAddress`. Locking doesn’t set a value, so pass the matching parameter too (e.g. `dstCurrency` + `dstChain` for `dstAsset`). `paymentMode` and `walletAddress` locks are ignored without a value.
`hideOrderTabs`	`true`	Hides the Buy/Sell tabs. Use with `orderType` to pin the widget to one direction.
`hideMenu`	`true`	Hides the menu button in the widget header, so users stay in the order flow.

Attribution

Parameter	Type	Description
`utm_source`	string	UTM source, stored on the user and the order
`utm_medium`	string	UTM medium
`utm_campaign`	string	UTM campaign

`skipPaymentInstructions`

SDK option, boolean. On a sell order, skips the crypto transfer instructions screen and shows a waiting screen instead. Use it when your wallet sends the crypto itself after the ORDER_CREATED event, then pass the hash with the UPDATE_PAYMENT_DETAIL command.

Next: Display modes

Overlay, embedded or redirect

Build with AI

Learn about Rampnow

What's Supported

Integrations

Help

SDK options

Order and display options

Order details

Display options

Attribution

`skipPaymentInstructions`

Next: Display modes

​SDK options

​Order and display options

​Order details

​Display options

​Attribution

​skipPaymentInstructions

Next: Display modes

SDK options

Order and display options

Order details

Display options

Attribution

`skipPaymentInstructions`