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

# Onramp API

> Multi-provider aggregation endpoints for comparing quotes and processing purchases across payment gateways.

# Onramp API

The Onramp API provides multi-provider aggregation for crypto purchases. It fans out requests to all enabled payment gateways, compares quotes, and lets users checkout with their preferred provider.

All endpoints are public and require a `projectId` parameter. No API key is needed.

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant App as Your App
    participant API as NowRamp API
    participant G1 as Gateway A
    participant G2 as Gateway B

    App->>API: GET /onramp/supported
    API-->>App: Providers, currencies, payment methods

    App->>API: GET /onramp/quotes
    API->>G1: Get quote
    API->>G2: Get quote
    G1-->>API: Quote
    G2-->>API: Quote
    API-->>App: Ranked quotes (best rate, cheapest, fastest)

    App->>API: POST /onramp/checkout-intent
    API->>G1: Create order
    G1-->>API: Checkout URL
    API-->>App: Checkout intent (iframe/redirect URL)

    App->>API: GET /onramp/transactions/:id
    API-->>App: Transaction status
```

## Base URL

```
GET|POST /public/v1/onramp/*
```

***

## Get Supported Configuration

Returns available providers, fiat currencies, crypto currencies, payment methods, and countries aggregated across all enabled providers.

```
GET /public/v1/onramp/supported
```

### Query Parameters

| Parameter   | Type          | Required | Description                                                                     |
| ----------- | ------------- | -------- | ------------------------------------------------------------------------------- |
| `projectId` | string (UUID) | Yes      | Your project ID                                                                 |
| `orderType` | string        | No       | `buy` or `sell` (default: `buy`)                                                |
| `country`   | string        | No       | ISO 2-letter country code (e.g., `US`, `GB`). Auto-detected from IP if omitted. |

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "providers": [
      {
        "id": "provider_a",
        "name": "Provider A",
        "logo": "https://...",
        "enabled": true,
        "features": {
          "supportsIframe": true,
          "supportsWidget": false,
          "supportsBuy": true,
          "supportsSell": true,
          "supportsRecurring": false,
          "kycHandledByProvider": true
        }
      },
      {
        "id": "provider_b",
        "name": "Provider B",
        "logo": "https://...",
        "enabled": true,
        "features": {
          "supportsIframe": false,
          "supportsWidget": true,
          "supportsBuy": true,
          "supportsSell": false,
          "supportsRecurring": false,
          "kycHandledByProvider": true
        }
      }
    ],
    "fiats": [
      {
        "code": "USD",
        "name": "US Dollar",
        "symbol": "$",
        "minAmount": "30",
        "maxAmount": "15000",
        "providers": ["provider_a", "provider_b"],
        "paymentMethods": ["debit-credit-card", "apple-pay"]
      }
    ],
    "cryptos": [
      {
        "code": "ETH",
        "name": "Ethereum",
        "networks": [
          {
            "id": "ethereum",
            "name": "Ethereum",
            "minAmount": "0.001",
            "maxAmount": "999999",
            "providers": ["provider_a", "provider_b"]
          },
          {
            "id": "polygon",
            "name": "Polygon",
            "minAmount": "0.01",
            "maxAmount": "999999",
            "providers": ["provider_a"]
          }
        ],
        "providers": ["provider_a", "provider_b"]
      }
    ],
    "paymentMethods": [
      {
        "id": "debit-credit-card",
        "name": "Debit credit card",
        "description": null,
        "supportedFiats": ["USD", "EUR", "GBP"],
        "providers": ["provider_a"]
      }
    ],
    "countries": [
      {
        "code": "US",
        "name": "United States",
        "providers": ["provider_a"]
      }
    ],
    "defaultGateway": "provider_a",
    "detectedCountry": "US"
  }
}
```

### Provider Features

| Feature                | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `supportsIframe`       | Provider checkout can be embedded in an iframe     |
| `supportsWidget`       | Provider provides a JavaScript widget for checkout |
| `supportsBuy`          | Supports fiat-to-crypto (on-ramp)                  |
| `supportsSell`         | Supports crypto-to-fiat (off-ramp)                 |
| `supportsRecurring`    | Supports recurring/subscription purchases          |
| `kycHandledByProvider` | Provider handles identity verification internally  |

***

## Get Quotes

Fetches quotes from all enabled gateways in parallel and returns them ranked by best rate.

```
GET /public/v1/onramp/quotes
```

### Query Parameters

| Parameter         | Type          | Required     | Description                                                  |
| ----------------- | ------------- | ------------ | ------------------------------------------------------------ |
| `projectId`       | string (UUID) | Yes          | Your project ID                                              |
| `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 (e.g., `100`). Required for buy orders.          |
| `cryptoAmount`    | string        | One required | Crypto amount. Required 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. Auto-detected from IP if omitted. |

<Info>
  Either `fiatAmount` or `cryptoAmount` must be provided.
</Info>

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "quotes": [
      {
        "gatewayId": "gateway_a",
        "gatewayName": "Gateway A",
        "gatewayLogo": "https://...",
        "available": true,
        "fiatAmount": "100",
        "fiatCurrency": "USD",
        "cryptoAmount": "0.03842",
        "cryptoCurrency": "ETH",
        "network": "ethereum",
        "fees": {
          "processingFee": "2.50",
          "networkFee": "0.80",
          "totalFee": "3.30",
          "feePercentage": "3.3"
        },
        "exchangeRate": "2602.81",
        "estimatedTime": "5-10 minutes",
        "kycRequired": "light",
        "expiresAt": 1706900000000,
        "rank": 1,
        "isBestRate": true,
        "score": 92
      },
      {
        "gatewayId": "gateway_b",
        "gatewayName": "Gateway B",
        "gatewayLogo": "https://...",
        "available": true,
        "fiatAmount": "100",
        "fiatCurrency": "USD",
        "cryptoAmount": "0.03801",
        "cryptoCurrency": "ETH",
        "network": "ethereum",
        "fees": {
          "processingFee": "3.00",
          "networkFee": "1.00",
          "totalFee": "4.00",
          "feePercentage": "4.0"
        },
        "exchangeRate": "2630.89",
        "estimatedTime": "1-5 minutes",
        "kycRequired": "none",
        "expiresAt": 1706900000000,
        "rank": 2,
        "isBestRate": false,
        "score": 85
      }
    ],
    "bestQuote": { "gatewayId": "gateway_a", "..." : "..." },
    "fastestQuote": { "gatewayId": "gateway_b", "..." : "..." },
    "cheapestFees": { "gatewayId": "gateway_a", "..." : "..." },
    "unavailableGateways": []
  }
}
```

### Quote Fields

| Field           | Type    | Description                                            |
| --------------- | ------- | ------------------------------------------------------ |
| `gatewayId`     | string  | Gateway identifier                                     |
| `gatewayName`   | string  | Display name                                           |
| `gatewayLogo`   | string  | Logo URL                                               |
| `available`     | boolean | Whether this gateway can service the request           |
| `fiatAmount`    | string  | Fiat amount                                            |
| `cryptoAmount`  | string  | Crypto amount the user will receive                    |
| `fees`          | object  | Fee breakdown (processing, network, total, percentage) |
| `exchangeRate`  | string  | Exchange rate (1 crypto = X fiat)                      |
| `estimatedTime` | string  | Estimated processing time                              |
| `kycRequired`   | string  | `none`, `light`, or `full`                             |
| `expiresAt`     | number  | Quote expiry timestamp (milliseconds)                  |
| `rank`          | number  | Ranking position (1 = best)                            |
| `isBestRate`    | boolean | Whether this is the best rate                          |
| `isRecommended` | boolean | Whether this is the recommended gateway                |
| `score`         | number  | Routing score (0-100)                                  |

### Ranked Results

The response includes convenience fields for common selection strategies:

| Field                 | Description                                                   |
| --------------------- | ------------------------------------------------------------- |
| `bestQuote`           | Quote with the best exchange rate (most crypto for your fiat) |
| `fastestQuote`        | Quote with the shortest estimated processing time             |
| `cheapestFees`        | Quote with the lowest total fees                              |
| `unavailableGateways` | Gateways that couldn't provide a quote, with reasons          |

***

## Create Checkout Intent

Creates an order with a specific gateway and returns a checkout URL for payment.

```
POST /public/v1/onramp/checkout-intent
```

### Request Body

| Parameter            | Type          | Required     | Description                                                                                                                                                      |
| -------------------- | ------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `projectId`          | string (UUID) | Yes          | Your project ID                                                                                                                                                  |
| `gateway`            | string        | Yes          | Gateway ID from the 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        | Buy orders   | Destination wallet address (required for buy)                                                                                                                    |
| `customerId`         | string        | No           | Internal customer UUID                                                                                                                                           |
| `externalCustomerId` | string        | No           | Partner's external customer ID                                                                                                                                   |
| `orderType`          | string        | No           | `buy` or `sell` (default: `buy`)                                                                                                                                 |
| `paymentMethodId`    | string        | No           | Payment method ID                                                                                                                                                |
| `email`              | string        | No           | Customer email                                                                                                                                                   |
| `redirectUrl`        | string        | No           | URL to redirect after checkout                                                                                                                                   |
| `metadata`           | object        | No           | Provider-facing string map, passed to provider's `createOrder()`. Not persisted in order metadata.                                                               |
| `partnerMetadata`    | object        | No           | Partner data (`Record<string, unknown>`). Persisted as `order.metadata.partnerMetadata` and included in webhook payloads. Max 20 keys, 4KB, 2 levels of nesting. |
| `country`            | string        | No           | ISO 2-letter country code                                                                                                                                        |

### Request Example

```json theme={null}
{
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "gateway": "gateway_a",
  "fiatCurrency": "USD",
  "fiatAmount": "100",
  "cryptoCurrency": "ETH",
  "network": "ethereum",
  "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f1bD21",
  "externalCustomerId": "user_123",
  "email": "user@example.com",
  "redirectUrl": "https://myapp.com/purchase-complete",
  "partnerMetadata": {
    "partnerOrderId": "order_abc",
    "campaign": "summer2026"
  }
}
```

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "gateway": "gateway_a",
    "status": "pending",
    "checkout": {
      "method": "iframe",
      "url": "https://checkout.gateway-a.com/...",
      "expiresAt": 1706903600000,
      "allowedFeatures": ["payment"]
    }
  }
}
```

### Checkout Methods

| Method     | Description                     | How to Use                           |
| ---------- | ------------------------------- | ------------------------------------ |
| `iframe`   | Embed checkout in an iframe     | Load `checkout.url` in an `<iframe>` |
| `redirect` | Redirect user to gateway        | Navigate to `checkout.url`           |
| `widget`   | Use gateway's JavaScript widget | Use `widgetConfig` to initialize     |

***

## Get Transaction

Returns the current status of an order, syncing with the gateway's latest status.

```
GET /public/v1/onramp/transactions/:transactionId
```

### Path Parameters

| Parameter       | Type          | Required | Description                                |
| --------------- | ------------- | -------- | ------------------------------------------ |
| `transactionId` | string (UUID) | Yes      | The order ID returned from checkout intent |

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "provider": "gateway_a",
    "status": "completed",
    "providerStatus": "complete",
    "fiatAmount": "100",
    "fiatCurrency": "USD",
    "cryptoAmount": "0.03842",
    "cryptoCurrency": "ETH",
    "network": "ethereum",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f1bD21",
    "transactionHash": "0xabc123...",
    "createdAt": "2025-02-01T10:30:00.000Z",
    "completedAt": "2025-02-01T10:38:00.000Z"
  }
}
```

### Transaction Statuses

| Status       | Description                                             |
| ------------ | ------------------------------------------------------- |
| `pending`    | Order created, awaiting payment                         |
| `processing` | Payment received, processing crypto transfer            |
| `completed`  | Crypto delivered to wallet                              |
| `failed`     | Order failed (payment declined, compliance issue, etc.) |
| `cancelled`  | Order cancelled by user or system                       |
| `expired`    | Order expired before payment                            |
| `refunded`   | Payment refunded to customer                            |

<Info>
  The `providerStatus` field contains the gateway's original status string, while `status` is normalized across all gateways.
</Info>

***

## GeoIP Country Detection

All onramp endpoints automatically detect the user's country from their IP address. This is used to:

* Filter supported currencies and payment methods by region
* Provide region-specific pricing and availability
* Comply with geographic restrictions

You can override auto-detection by passing the `country` parameter explicitly.

***

## Using the SDK

The `@nowramp/sdk` provides convenient methods for all onramp endpoints:

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

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

// Get supported config
const config = await api.getSupported();

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

// 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'
});

// Poll transaction
const tx = await api.getTransaction(intent.orderId);
```

See the [JavaScript SDK](/sdk/js-sdk) for full API client documentation, or [React Components](/sdk/form) for React hooks.