> ## 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.

# Onramp & Offramp SDK

> Embed the Rampnow onramp and offramp widget from JavaScript or TypeScript, with events and a React hook

The `@rampnow/sdk` package opens the Rampnow widget inside your web app with a few lines of code. It is a typed wrapper around the [Widget](/quickstart/ramp-widget/overview): the same buy and sell flow, the same parameters, plus browser events, programmatic open and close, and a React hook.

<div style={{display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '1rem'}}>
  <Card title="Overlay Mode" icon="layer-group" href="/quickstart/ramp-sdk/display-modes#overlay-mode">
    Full-screen modal overlay. Quickest setup, no container needed
  </Card>

  <Card title="Embedded Mode" icon="window" href="/quickstart/ramp-sdk/display-modes#embedded-mode">
    Mount the widget inside any DOM element in your layout
  </Card>

  <Card title="Redirect Mode" icon="arrow-up-right-from-square" href="/quickstart/ramp-sdk/display-modes#redirect-mode">
    Generate a URL to open in a new tab, for native apps or email links
  </Card>

  <Card title="React Hook" icon="react" href="/quickstart/ramp-sdk/installation#react">
    First-class React support via `useRampnowSdk`
  </Card>
</div>

<Tip>
  Try the SDK live at [demo.rampnow.io](https://demo.rampnow.io/).
</Tip>

## How it works

<Steps>
  <Step title="Create an SDK instance">
    Pass your partner key and any order details you already know (direction, asset, amount, wallet address). See [Configuration](/quickstart/ramp-sdk/configuration).
  </Step>

  <Step title="Subscribe to events">
    React in your UI as the order moves, for example when it is created or completed. See [Events & commands](/quickstart/ramp-sdk/events).
  </Step>

  <Step title="Open the widget">
    Call `init()`. The user completes sign-in, KYC and payment inside the Rampnow widget. See [Display modes](/quickstart/ramp-sdk/display-modes).
  </Step>

  <Step title="Confirm on your backend">
    Browser events are for UI only. Use [webhooks](/api-reference/webhook) as the source of truth for order status.
  </Step>
</Steps>

## Your partner API key

Every widget session, whether opened by URL, iframe or the SDK, carries your **partner API key** as `apiKey`. That key is what makes the order yours:

* Orders placed through your integration are attributed to your account in the [Partner Dashboard](https://partner.rampnow.io)
* Order status webhooks go to your endpoint
* The partner fee agreed with Rampnow for your account applies to each order. It can be zero if you integrate for visibility only

Use the **public key** from the Partner Dashboard under **API Hub**. Sandbox and production keys are different, and each only works against its own environment.

<Note>
  The public key is safe to ship in client-side code. You don't need a backend, an API secret or request signing to open the widget. The API key and secret pair (with `X-RAMPNOW-SIGN`) is only for the [Onramp & Offramp Intent](/quickstart/ramp-intent/overview) REST API.
</Note>

## When to use the SDK

<AccordionGroup>
  <Accordion title="Ideal for" icon="check">
    * Web apps that need event callbacks as the order moves
    * Programmatic control: open and close the widget from your own buttons
    * React apps, through the `useRampnowSdk` hook
    * Type-safe configuration with TypeScript
  </Accordion>

  <Accordion title="Consider something else when" icon="triangle-exclamation">
    * You only need a link or an iframe: the [Widget](/quickstart/ramp-widget/overview) needs no JavaScript
    * You want to build the pre-checkout journey yourself and create orders server-to-server: use [Onramp & Offramp Intent](/quickstart/ramp-intent/overview)
  </Accordion>
</AccordionGroup>

See [Integrations Overview](/quickstart/integrations/overview) for a side-by-side comparison.

<Card title="Next: Installation & setup" icon="arrow-right" href="/quickstart/ramp-sdk/installation">
  Install the package and open your first widget session
</Card>


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