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

# JavaScript SDK

> Programmatic access to the NowRamp Onramp API via @nowramp/sdk

# JavaScript SDK

The `@nowramp/sdk` package provides the `RampApi` client for fetching quotes, creating checkouts, and tracking transactions across multiple payment gateways.

## Installation

```bash theme={null}
npm install @nowramp/sdk
# or
yarn add @nowramp/sdk
# or
pnpm add @nowramp/sdk
```

## Quick Start

```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();

// 2. Get ranked quotes from all gateways
const quotes = await api.getQuotes({
  fiatCurrency: 'USD',
  fiatAmount: '100',
  cryptoCurrency: 'ETH',
  network: 'ethereum'
});

// 3. Create checkout with the best quote's gateway
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;
```

## RampApi Class

### Constructor

```typescript theme={null}
new RampApi(config: RampApiConfig)
```

### Configuration

```typescript theme={null}
interface RampApiConfig {
  projectId: string;       // Your project ID (required)
  apiKey?: string;         // Optional pk_ key for higher rate limits
  apiUrl?: string;         // Default: https://api.nowramp.com
}
```

***

## Methods

### getSupported(params?)

Get supported configuration (gateways, currencies, payment methods) across all enabled providers.

```javascript theme={null}
const config = await api.getSupported({ orderType: 'buy', country: 'US' });

console.log(config.gateways);       // Available payment gateways
console.log(config.fiats);          // Supported fiat currencies with min/max
console.log(config.cryptos);        // Supported cryptocurrencies with networks
console.log(config.paymentMethods); // Available payment methods
console.log(config.defaultGateway); // Project's default gateway
```

**Parameters:**

| Parameter   | Type              | Description                                                  |
| ----------- | ----------------- | ------------------------------------------------------------ |
| `orderType` | `'buy' \| 'sell'` | Filter by order type (default: `'buy'`)                      |
| `country`   | `string`          | ISO 2-letter country code (auto-detected from IP if omitted) |

### getQuotes(params)

Get quotes from all enabled gateways, ranked by best rate.

```javascript theme={null}
const result = await api.getQuotes({
  fiatCurrency: 'USD',
  fiatAmount: '100',
  cryptoCurrency: 'ETH',
  network: 'ethereum',
  paymentMethodId: 'debit-credit-card', // optional
  country: 'US'                         // optional
});

console.log(result.bestQuote);             // Best exchange rate
console.log(result.fastestQuote);          // Shortest processing time
console.log(result.cheapestFees);          // Lowest total fees
console.log(result.quotes);               // All quotes, ranked
console.log(result.unavailableGateways);  // Gateways that couldn't quote
```

**Parameters:**

| Parameter         | Type     | Required     | Description                            |
| ----------------- | -------- | ------------ | -------------------------------------- |
| `fiatCurrency`    | `string` | Yes          | Fiat currency code (e.g., `'USD'`)     |
| `cryptoCurrency`  | `string` | Yes          | Crypto currency code (e.g., `'ETH'`)   |
| `network`         | `string` | Yes          | Network ID (e.g., `'ethereum'`)        |
| `fiatAmount`      | `string` | One required | Fiat amount (for buy orders)           |
| `cryptoAmount`    | `string` | One required | Crypto amount (for sell orders)        |
| `orderType`       | `string` | No           | `'buy'` or `'sell'` (default: `'buy'`) |
| `paymentMethodId` | `string` | No           | Filter by payment method               |
| `country`         | `string` | No           | ISO 2-letter country code              |

### createCheckoutIntent(params)

Create a checkout with a specific gateway. Returns a checkout URL for iframe or redirect.

```javascript theme={null}
const intent = await api.createCheckoutIntent({
  gateway: 'gateway_id',
  fiatCurrency: 'USD',
  fiatAmount: '100',
  cryptoCurrency: 'ETH',
  network: 'ethereum',
  walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f1bD21',
  externalCustomerId: 'user_123',
  email: 'user@example.com',
  redirectUrl: 'https://myapp.com/complete'
});

console.log(intent.orderId);            // Order ID for tracking
console.log(intent.checkout.method);     // 'iframe' | 'redirect' | 'widget'
console.log(intent.checkout.url);        // Checkout URL
```

**Parameters:**

| Parameter            | Type     | Required     | Description                      |
| -------------------- | -------- | ------------ | -------------------------------- |
| `gateway`            | `string` | Yes          | Gateway ID from supported config |
| `fiatCurrency`       | `string` | Yes          | Fiat currency code               |
| `cryptoCurrency`     | `string` | Yes          | Crypto currency code             |
| `network`            | `string` | Yes          | Network ID                       |
| `fiatAmount`         | `string` | One required | Fiat amount                      |
| `cryptoAmount`       | `string` | One required | Crypto amount                    |
| `walletAddress`      | `string` | Yes (buy)    | Destination wallet address       |
| `externalCustomerId` | `string` | No           | Your user ID                     |
| `email`              | `string` | No           | Customer email                   |
| `redirectUrl`        | `string` | No           | URL after checkout               |
| `metadata`           | `object` | No           | Key-value metadata               |

### getTransaction(transactionId)

Get transaction status, synced with the gateway's latest data.

```javascript theme={null}
const tx = await api.getTransaction('order-uuid-here');

console.log(tx.status);            // 'pending' | 'processing' | 'completed' | 'failed' | ...
console.log(tx.cryptoAmount);      // Crypto amount received
console.log(tx.transactionHash);   // Blockchain TX hash (if available)
```

### validateAddress(params)

Validate a wallet address format.

```javascript theme={null}
const result = await api.validateAddress({
  address: '0x742d35Cc6634C0532925a3b844Bc9e7595f1bD21',
  network: 'ethereum'
});

console.log(result.isValid);       // true
console.log(result.chainType);     // 'evm'
```

### getSupportedNetworks()

Get supported networks for address validation.

```javascript theme={null}
const networks = await api.getSupportedNetworks();
// [{ id: 'ethereum', name: 'Ethereum', chainType: 'evm' }, ...]
```

***

## Standalone Functions

Common API functions are also exported as standalone functions for minimal setup:

```javascript theme={null}
import {
  getSupported,
  getQuotes,
  createCheckoutIntent,
  getTransaction,
  validateAddress,
  getSupportedNetworks
} from '@nowramp/sdk';

const config = await getSupported(
  { projectId: 'your_project_id' }
);

const quotes = await getQuotes(
  { projectId: 'your_project_id' },
  { fiatCurrency: 'USD', fiatAmount: '100', cryptoCurrency: 'ETH', network: 'ethereum' }
);

const intent = await createCheckoutIntent(
  { projectId: 'your_project_id' },
  {
    gateway: quotes.bestQuote.gatewayId,
    fiatCurrency: 'USD',
    fiatAmount: '100',
    cryptoCurrency: 'ETH',
    network: 'ethereum',
    walletAddress: '0x...'
  }
);

const tx = await getTransaction(
  { apiUrl: 'https://api.nowramp.com' },
  intent.orderId
);
```

***

## TypeScript Support

The SDK includes full TypeScript definitions:

```typescript theme={null}
import type {
  RampApi,
  RampApiConfig,
  FlowType,
  QuoteData,
  CheckoutIntent,
  Transaction
} from '@nowramp/sdk';
```

***

## UMD Build

For non-bundled usage via CDN:

```html theme={null}
<script src="https://unpkg.com/@nowramp/sdk/dist/index.umd.js"></script>
<script>
  const api = new NowRamp.RampApi({
    projectId: 'your_project_id'
  });

  api.getQuotes({
    fiatCurrency: 'USD',
    fiatAmount: '100',
    cryptoCurrency: 'ETH',
    network: 'ethereum'
  }).then(quotes => {
    console.log('Best rate:', quotes.bestQuote);
  });
</script>
```

***

## Browser Support

| Browser | Version |
| ------- | ------- |
| Chrome  | 80+     |
| Firefox | 75+     |
| Safari  | 13+     |
| Edge    | 80+     |

## Bundle Size

| Build          | Size   |
| -------------- | ------ |
| ESM (minified) | \~15KB |
| UMD (minified) | \~18KB |
| Gzipped        | \~5KB  |

## Legacy Methods (Deprecated)

<Warning>
  The methods below are **deprecated** and will be removed in a future release. They query a single payment provider instead of comparing across all gateways. Use [`getQuotes()`](#getquotesparams) and [`getSupported()`](#getsupportedparams) instead.
</Warning>

### getRate(params) — deprecated

Get a conversion rate from a single provider. Returns one rate instead of comparing across gateways.

```javascript theme={null}
// Deprecated — use getQuotes() instead
const rate = await api.getRate({
  from: 'USD',
  to: 'ETH',
  amount: 100,
  flowType: 'buy' // optional, default: 'buy'
});

console.log(rate.rate);                // Exchange rate
console.log(rate.destinationAmount);   // Crypto amount after fees
console.log(rate.fees.totalFee);       // Total fee
console.log(rate.provider);            // Single provider name
```

**Parameters:**

| Parameter  | Type              | Required | Description                               |
| ---------- | ----------------- | -------- | ----------------------------------------- |
| `from`     | `string`          | Yes      | Source currency code (e.g., `'USD'`)      |
| `to`       | `string`          | Yes      | Destination currency code (e.g., `'ETH'`) |
| `amount`   | `number`          | Yes      | Amount in source currency                 |
| `flowType` | `'buy' \| 'sell'` | No       | Order type (default: `'buy'`)             |

**Returns:** `RateResult`

```typescript theme={null}
interface RateResult {
  rate: number;
  sourceAmount: number;
  sourceCurrency: string;
  destinationAmount: number;
  destinationCurrency: string;
  fees: {
    processingFee: number;
    processingFeePercent: number;
    networkFee: number;
    totalFee: number;
  };
  provider: string;
  expiresAt?: string;
}
```

**Migration:** Replace `getRate()` with `getQuotes()` to compare rates across all gateways:

```javascript theme={null}
// Before (single provider)
const rate = await api.getRate({ from: 'USD', to: 'ETH', amount: 100 });

// After (all providers, ranked)
const { bestQuote, quotes } = await api.getQuotes({
  fiatCurrency: 'USD',
  cryptoCurrency: 'ETH',
  network: 'ethereum',
  fiatAmount: '100'
});
```

### getCurrencies() — deprecated

Get available currencies from a single configured provider.

```javascript theme={null}
// Deprecated — use getSupported() instead
const currencies = await api.getCurrencies();

console.log(currencies.fiat);        // Fiat currencies
console.log(currencies.crypto);      // Crypto currencies
console.log(currencies.provider);    // Single provider name
```

**Migration:** Replace `getCurrencies()` with `getSupported()` to get currencies, payment methods, and gateways across all providers:

```javascript theme={null}
// Before (single provider)
const currencies = await api.getCurrencies();

// After (all providers, with payment methods and gateways)
const supported = await api.getSupported({ orderType: 'buy' });
console.log(supported.fiats);          // All fiat currencies across gateways
console.log(supported.cryptos);        // All crypto currencies with networks
console.log(supported.paymentMethods); // Available payment methods
console.log(supported.gateways);       // Available gateways
```

### Standalone legacy functions

The legacy methods are also available as standalone functions:

```javascript theme={null}
import { getRate, getCurrencies } from '@nowramp/sdk';

// Deprecated — use getQuotes() and getSupported() instead
const rate = await getRate({ projectId: 'your_project_id' }, { from: 'USD', to: 'ETH', amount: 100 });
const currencies = await getCurrencies({ projectId: 'your_project_id' });
```

***

## Next Steps

* [Onramp API](/api/onramp) — Full endpoint documentation
* [React Components](/sdk/form) — Drop-in checkout form with hooks
* [Multi-Provider Quotes](/guides/multi-provider-quotes) — Build a quote comparison UI