> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rampnow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Installation & Setup

> Install @rampnow/sdk, point it at sandbox or production, and open your first widget session

## Install

<CodeGroup>
  ```bash npm theme={null}
  npm install @rampnow/sdk
  ```

  ```bash yarn theme={null}
  yarn add @rampnow/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @rampnow/sdk
  ```
</CodeGroup>

**CDN (no bundler):**

```html theme={null}
<script src="https://cdn.jsdelivr.net/npm/@rampnow/sdk/dist/rampnow-sdk.umd.js"></script>
```

When loaded from the CDN, the SDK is available as `window.RampnowSdk`.

## Environments

The SDK opens production by default. Set `widgetUrl` to the sandbox host while you build and test.

| Environment | Widget host | Key |
| - | - | - |
| Sandbox | `https://app.sandbox.rampnow.io` | Sandbox public key |
| Production | `https://app.rampnow.io` | Production public key |

Build and test against sandbox first. No real money or mainnet crypto moves there. See [Sandbox Testing](/api-reference/sandbox-testing) for test payments and testnet tokens.

## Open your first session

<Steps>
  <Step title="Create an instance">
    <Tabs>
      <Tab title="Onramp (buy)">
        ```javascript theme={null}
        import { RampnowSdk, RampnowEventType } from '@rampnow/sdk'

        const sdk = new RampnowSdk({
          apiKey: 'pk_YOUR_API_KEY',
          widgetUrl: 'https://app.sandbox.rampnow.io',
          orderType: 'buy',
          srcCurrency: 'EUR',
          srcChain: 'fiat',
          dstCurrency: 'ETH',
          dstChain: 'ethereum',
        })
        ```
      </Tab>

      <Tab title="Offramp (sell)">
        ```javascript theme={null}
        import { RampnowSdk, RampnowEventType } from '@rampnow/sdk'

        const sdk = new RampnowSdk({
          apiKey: 'pk_YOUR_API_KEY',
          widgetUrl: 'https://app.sandbox.rampnow.io',
          orderType: 'sell',
          srcCurrency: 'USDT',
          srcChain: 'ethereum',
          dstCurrency: 'EUR',
          dstChain: 'fiat',
        })
        ```
      </Tab>
    </Tabs>

    Every option is listed in [Configuration](/quickstart/ramp-sdk/configuration).
  </Step>

  <Step title="Subscribe to events">
    ```javascript theme={null}
    sdk.on(RampnowEventType.ORDER_COMPLETED, (e) => {
      console.log('Order completed:', e.payload.orderUid)
    })
    ```

    See [Events & commands](/quickstart/ramp-sdk/events) for the full list.
  </Step>

  <Step title="Open the widget">
    ```javascript theme={null}
    sdk.init()
    ```

    Without `containerId` this opens a full-screen overlay. See [Display modes](/quickstart/ramp-sdk/display-modes) for embedded and redirect.
  </Step>
</Steps>

## React

The SDK ships with a React hook.

<Info>
  React (`>=18`) and ReactDOM (`>=18`) are optional peer dependencies, only required when you use the hook.
</Info>

```tsx theme={null}
import { useRampnowSdk } from '@rampnow/sdk/react'
import { RampnowEventType } from '@rampnow/sdk'
import { useEffect } from 'react'

function BuyCryptoButton() {
  const { init, close, send, on, isOpen } = useRampnowSdk({
    apiKey: 'pk_YOUR_API_KEY',
    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>
}
```

The hook returns the same `init`, `close`, `send`, `on` and `isOpen` as an SDK instance.

## Methods

### `new RampnowSdk(config)`

Creates an SDK instance. Validates the `apiKey` and merges defaults. Does **not** open the widget; call `.init()` to display it.

### `sdk.init(): RampnowSdk`

Opens the widget. If `containerId` is set, mounts the iframe in that element; otherwise creates a full-screen overlay. Returns `this` for chaining.

### `sdk.close(): void`

Closes and removes the widget from the DOM.

### `sdk.on(eventType, callback): RampnowSdk` / `sdk.off(eventType, callback): RampnowSdk`

Subscribe to and unsubscribe from widget events. See [Events](/quickstart/ramp-sdk/events#events).

### `sdk.send(commandType, payload): RampnowSdk`

Send a command to the widget iframe. See [Commands](/quickstart/ramp-sdk/events#commands).

### `sdk.isOpen: boolean`

Read-only. Whether the widget is currently displayed.

### `RampnowSdk.createRedirectUrl(config): string` (static)

Builds a full widget URL from config without opening an iframe. See [Redirect mode](/quickstart/ramp-sdk/display-modes#redirect-mode).

<Card title="Next: Configuration" icon="arrow-right" href="/quickstart/ramp-sdk/configuration">
  Every option you can pass to the SDK
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.