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

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

{
  "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.

Either fiatAmount or cryptoAmount must be provided.

Response

{
  "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

{
  "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

{
  "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

{
  "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

The providerStatus field contains the gateway’s original status string, while status is normalized across all gateways.

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:

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 for full API client documentation, or React Components for React hooks.

Overview

Sessions

Onramp

Onramp API

Onramp API

How It Works

Base URL

Get Supported Configuration

Query Parameters

Response

Provider Features

Get Quotes

Query Parameters

Response

Quote Fields

Ranked Results

Create Checkout Intent

Request Body

Request Example

Response

Checkout Methods

Get Transaction

Path Parameters

Response

Transaction Statuses

GeoIP Country Detection

Using the SDK

Overview

Sessions

Onramp

​Onramp API

​How It Works

​Base URL

​Get Supported Configuration

​Query Parameters

​Response

​Provider Features

​Get Quotes

​Query Parameters

​Response

​Quote Fields

​Ranked Results

​Create Checkout Intent

​Request Body

​Request Example

​Response

​Checkout Methods

​Get Transaction

​Path Parameters

​Response

​Transaction Statuses

​GeoIP Country Detection

​Using the SDK

Onramp API

How It Works

Base URL

Get Supported Configuration

Query Parameters

Response

Provider Features

Get Quotes

Query Parameters

Response

Quote Fields

Ranked Results

Create Checkout Intent

Request Body

Request Example

Response

Checkout Methods

Get Transaction

Path Parameters

Response

Transaction Statuses

GeoIP Country Detection

Using the SDK