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

# Quickstart

> Integrate NowRamp in minutes using React components, the JavaScript SDK, or raw API calls.

# Integrate NowRamp in Minutes

Choose the integration path that fits your stack. All three approaches use the same Onramp API — they differ in how much UI NowRamp handles for you.

## Prerequisites

* A partner account with a **project ID**
* Optional: a public key (`pk_live_...`) for higher rate limits

<Info>
  The Onramp API is public — no API key is required. Pass your `projectId` as a query parameter.
</Info>

***

## Option 1: React Components

The fastest path. The `@nowramp/form` package provides a complete checkout form that handles currency selection, quote comparison, wallet input, and provider checkout.

```bash theme={null}
npm install @nowramp/form
```

```tsx theme={null}
import { RampForm } from '@nowramp/form';

function BuyCrypto() {
  return (
    <RampForm
      projectId="your_project_id"
      apiUrl="https://api.nowramp.com"
      customerId="user_123"
      theme="light"
      defaultFiatAmount="100"
      defaultFiatCurrency="USD"
      onComplete={(tx) => {
        console.log('Purchase complete:', tx.orderId);
      }}
    />
  );
}
```

With full branding:

```tsx theme={null}
<RampForm
  projectId="your_project_id"
  apiUrl="https://api.nowramp.com"
  customerId="user_123"
  theme="dark"
  accentColor="#6366F1"
  bgColor="#1a1a2e"
  surfaceColor="#16213e"
  inputBgColor="#0f3460"
  textColor="#e0e0e0"
  borderColor="#333333"
  borderRadius="10px"
  showFlowToggle={false}
  defaultFiatAmount="250"
  onComplete={(tx) => console.log('Done!', tx.orderId)}
  onError={(err) => console.error(err.message)}
/>
```

See the [React Components guide](/sdk/form) for full props reference, hooks, and theming.

***

## Option 2: JavaScript SDK

For non-React apps or when you want full UI control. The `@nowramp/sdk` package provides a `RampApi` client for all onramp endpoints.

```bash theme={null}
npm install @nowramp/sdk
```

```javascript theme={null}
import { RampApi } from '@nowramp/sdk';

const api = new RampApi({ projectId: 'your_project_id' });

// 1. Get supported currencies and payment methods
const supported = await api.getSupported();
console.log(supported.gateways);      // Available payment gateways
console.log(supported.fiats);         // Supported fiat currencies
console.log(supported.cryptos);       // Supported cryptocurrencies

// 2. Get ranked quotes from all gateways
const quotes = await api.getQuotes({
  fiatCurrency: 'USD',
  cryptoCurrency: 'ETH',
  network: 'ethereum',
  fiatAmount: '100'
});
console.log(quotes.bestQuote);        // Best exchange rate
console.log(quotes.fastestQuote);     // Shortest processing time

// 3. Create checkout with the user's chosen quote
const intent = await api.createCheckoutIntent({
  gateway: quotes.bestQuote.gatewayId,
  fiatCurrency: 'USD',
  fiatAmount: '100',
  cryptoCurrency: 'ETH',
  network: 'ethereum',
  walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f1bD21'
});

// 4. Redirect user to the gateway's checkout
window.location.href = intent.checkout.url;

// 5. Poll transaction status
const tx = await api.getTransaction(intent.orderId);
console.log(tx.status);               // 'pending' | 'processing' | 'completed' | ...
```

See the [JavaScript SDK guide](/sdk/js-sdk) for the full API client reference.

***

## Option 3: Session-Based Checkout (Hosted)

The most secure integration. Create a checkout session server-side with your secret key (`sk_`), then redirect users to our hosted checkout page. No frontend code required — we handle the full checkout UI.

This is ideal for:

* **Gaming platforms** — redirect players to buy crypto without building a checkout UI
* **Backend-only integrations** — mobile apps, game servers, API-first flows
* **Maximum security** — wallet address and amount are locked server-side

```bash theme={null}
# 1. Create session from your backend (secret key required)
curl -X POST https://api.nowramp.com/v1/sessions \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalCustomerId": "player_12345",
    "sourceAmount": "100",
    "sourceCurrency": "USD",
    "destinationCurrency": "ETH",
    "network": "ethereum",
    "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f1bD21",
    "redirectUrl": "https://yoursite.com/payment-complete",
    "type": "onramp"
  }'
```

```json theme={null}
{
  "type": "session",
  "id": "sess_abc123",
  "attributes": {
    "sessionId": "sess_abc123",
    "projectId": "your-project-uuid",
    "clientSecret": "sess_secret_xyz789",
    "status": "pending",
    ...
  }
}
```

```bash theme={null}
# 2. Redirect user to hosted checkout — that's it!
https://checkout.nowramp.com?sessionId=sess_abc123&clientSecret=sess_secret_xyz789&projectId=your-project-uuid
```

The hosted checkout handles quote comparison, payment, and redirects back to your `redirectUrl` on completion.

<Warning>
  **Save the `clientSecret` immediately** — it's only returned once on creation.
</Warning>

You can also skip hosted checkout and build your own UI using the session endpoints. See the full [Session-Based Checkout guide](/guides/session-checkout) for both variants, field locks, error handling, and more.

***

## Option 4: Raw API

No SDK needed — call the endpoints directly with `fetch` or `curl`.

### Get Supported Configuration

```bash theme={null}
curl "https://api.nowramp.com/public/v1/onramp/supported?projectId=YOUR_PROJECT_ID"
```

### Get Quotes

```bash theme={null}
curl "https://api.nowramp.com/public/v1/onramp/quotes?projectId=YOUR_PROJECT_ID&fiatCurrency=USD&cryptoCurrency=ETH&network=ethereum&fiatAmount=100"
```

### Create Checkout Intent

```bash theme={null}
curl -X POST https://api.nowramp.com/public/v1/onramp/checkout-intent \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "YOUR_PROJECT_ID",
    "gateway": "gateway_id_from_quotes",
    "fiatCurrency": "USD",
    "fiatAmount": "100",
    "cryptoCurrency": "ETH",
    "network": "ethereum",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f1bD21"
  }'
```

### Get Transaction Status

```bash theme={null}
curl "https://api.nowramp.com/public/v1/onramp/transactions/ORDER_ID"
```

### JavaScript (fetch)

```javascript theme={null}
const PROJECT_ID = 'your_project_id';
const BASE = 'https://api.nowramp.com/public/v1/onramp';

// 1. Get supported config
const supported = await fetch(`${BASE}/supported?projectId=${PROJECT_ID}`)
  .then(r => r.json());

// 2. Get quotes
const quotes = await fetch(
  `${BASE}/quotes?projectId=${PROJECT_ID}&fiatCurrency=USD&cryptoCurrency=ETH&network=ethereum&fiatAmount=100`
).then(r => r.json());

// 3. Create checkout intent
const intent = await fetch(`${BASE}/checkout-intent`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    projectId: PROJECT_ID,
    gateway: quotes.data.bestQuote.gatewayId,
    fiatCurrency: 'USD',
    fiatAmount: '100',
    cryptoCurrency: 'ETH',
    network: 'ethereum',
    walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f1bD21'
  })
}).then(r => r.json());

// 4. Redirect to checkout
window.location.href = intent.data.checkout.url;
```

See the [Onramp API reference](/api/onramp) for full request/response documentation.

***

## Configure Webhooks (Recommended)

Webhooks notify your server when transactions complete, fail, or change status. Don't rely solely on polling.

```javascript theme={null}
// Express.js webhook handler
const crypto = require('crypto');

app.post('/webhooks/ramp', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const payload = req.body.toString();

  // Verify signature
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(`${timestamp}.${payload}`)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(payload);

  switch (event.type) {
    case 'transaction.completed':
      // Credit user account, send confirmation email, etc.
      handleTransactionComplete(event.data.transaction);
      break;
    case 'transaction.failed':
      handleTransactionFailed(event.data.transaction);
      break;
  }

  res.status(200).json({ received: true });
});
```

See the [Callback URLs guide](/guides/callback-urls) for full setup instructions.

***

## Test Your Integration

Use the sandbox environment for testing:

| Environment | API URL                           | Description                     |
| ----------- | --------------------------------- | ------------------------------- |
| Sandbox     | `https://api.sandbox.nowramp.com` | Test environment with mock data |
| Production  | `https://api.nowramp.com`         | Live transactions               |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Session-Based Checkout" icon="lock" href="/guides/session-checkout">
    Secure server-side sessions with hosted or custom checkout
  </Card>

  <Card title="Multi-Provider Quotes" icon="ranking-star" href="/guides/multi-provider-quotes">
    Build a quote comparison UI
  </Card>

  <Card title="Onramp API" icon="code" href="/api/onramp">
    Full API reference
  </Card>

  <Card title="Sessions API" icon="key" href="/api/sessions">
    Session endpoints reference
  </Card>

  <Card title="React Components" icon="react" href="/sdk/form">
    Drop-in form with theming and hooks
  </Card>

  <Card title="Callback URLs" icon="webhook" href="/guides/callback-urls">
    Server-side transaction notifications
  </Card>
</CardGroup>