API Overview

The NowRamp API is a RESTful API that allows you to integrate crypto on/off ramp functionality into your application. This documentation covers the /v1/* and /public/* endpoints available to partners.

Base URL

Environment	Base URL	Description
Production	`https://api.nowramp.com`	Live environment for real transactions
Sandbox	`https://api.sandbox.nowramp.com`	Test environment with mock data

Use the sandbox environment during development and testing. Switch to production when you’re ready to go live.

Authentication

NowRamp uses API keys to authenticate requests. There are two types of API keys:

API Key Types

Key Prefix	Type	Usage
`sk_`	Secret Key	Backend/server-side only. Full API access.
`pk_`	Public Key	Frontend/client-side safe. Limited to public endpoints and widget initialization.

Using Secret Keys (Backend)

Secret keys (sk_*) should only be used in server-side code. Include your secret key in the X-API-Key header:

curl https://api.nowramp.com/v1/orders \
  -H "X-API-Key: sk_live_your_secret_key" \
  -H "Content-Type: application/json"

Never expose secret keys in client-side code, mobile apps, or commit them to version control. Secret keys have full access to your account and can create orders, access customer data, and more.

Using Public Keys (Frontend)

Public keys (pk_*) are safe to use in frontend code. They are limited to:

Initializing the embeddable widget
Fetching public project configuration
Fetching supported currencies

// Safe to use in browser code
const widget = new RampWidget({
  apiKey: 'pk_live_your_public_key',
  projectId: 'proj_abc123'
});

When to Use Each Key Type

Use Case	Key Type
Server-to-server API calls	Secret (`sk_`)
Creating orders	Secret (`sk_`)
Managing customers	Secret (`sk_`)
Webhook signature verification	Secret (`sk_`)
Initializing the widget	Public (`pk_`)
Fetching project config in browser	Public (`pk_`)

Request Format

All requests should use Content-Type: application/json
Request bodies should be JSON-encoded
All timestamps are in ISO 8601 format (UTC)

curl -X POST https://api.nowramp.com/v1/orders \
  -H "X-API-Key: sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"quoteId": "quote_abc123"}'

Rate Limiting

API requests are rate limited to ensure fair usage and platform stability.

Default Limits

Limit Type	Rate
Default	1000 requests per minute

Rate Limit Headers

Every API response includes rate limit information in the headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per window
`X-RateLimit-Remaining`	Remaining requests in current window
`X-RateLimit-Reset`	Unix timestamp when the rate limit resets

Example response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1705123456

Handling Rate Limits

When you exceed the rate limit, the API returns a 429 Too Many Requests response:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry after the rate limit resets."
  }
}

Implement exponential backoff in your integration to handle rate limits gracefully.

Idempotency Keys

For POST, PUT, and DELETE requests, you can include an Idempotency-Key header to ensure the request is only processed once. This is especially important for order creation to prevent duplicate transactions.

Idempotency-Key: <unique-key>

Validity

Idempotency keys are valid for 24 hours. After 24 hours, the same key can be reused for a new request.

Examples

Creating an order with idempotency:

curl -X POST https://api.nowramp.com/v1/orders \
  -H "X-API-Key: sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_user123_1705123456" \
  -d '{"quoteId": "quote_abc123"}'

Use cases for idempotency keys:

Scenario	Recommended Key Format
Order creation	`order_{userId}_{timestamp}`
Customer creation	`customer_{externalId}`
Wallet registration	`wallet_{customerId}_{address}`
Retry after network failure	Same key as original request

If a request with the same idempotency key is received within 24 hours, the API returns the cached response from the original request without reprocessing.

Response Format

All responses follow a consistent structure:

Success Response

{
  "success": true,
  "data": {
    // Response data
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": [
      {
        "field": "fieldName",
        "message": "Field-specific error message"
      }
    ]
  }
}

Common Error Codes

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Request parameters failed validation
`INVALID_API_KEY`	401	API key is missing, invalid, or expired
`UNAUTHORIZED`	401	Authentication required or failed
`FORBIDDEN`	403	API key lacks permission for this action
`NOT_FOUND`	404	Requested resource does not exist
`QUOTE_EXPIRED`	400	Quote has expired, request a new one
`INSUFFICIENT_FUNDS`	400	Customer has insufficient funds
`KYC_REQUIRED`	400	Customer must complete KYC verification
`WALLET_BLOCKED`	400	Wallet failed compliance screening
`DUPLICATE_REQUEST`	409	Duplicate idempotency key with different payload
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error, contact support if persists

Public Endpoints

These endpoints do not require authentication and can be called from client-side code:

Get Project Configuration

Retrieve public configuration for a project, including supported currencies and payment methods.

GET /public/projects/:projectId

Example:

curl https://api.nowramp.com/public/projects/proj_abc123

Response:

{
  "success": true,
  "data": {
    "id": "proj_abc123",
    "name": "My App",
    "supportedFiatCurrencies": ["USD", "EUR", "GBP"],
    "supportedCryptoCurrencies": ["ETH", "USDC", "USDT"],
    "supportedNetworks": ["ethereum", "polygon", "arbitrum"],
    "minOrderAmount": "20.00",
    "maxOrderAmount": "10000.00",
    "kycRequired": true
  }
}

Get Supported Currencies

Retrieve the list of supported fiat and crypto currencies.

GET /public/currencies

Example:

curl https://api.nowramp.com/public/currencies

Pagination

List endpoints support cursor-based pagination:

GET /v1/orders?limit=20&cursor=eyJpZCI6MTIzfQ

Parameters:

Parameter	Type	Description
`limit`	integer	Number of items per page (default: 20, max: 100)
`cursor`	string	Cursor for the next page of results

Response includes pagination info:

{
  "success": true,
  "data": [...],
  "pagination": {
    "hasMore": true,
    "nextCursor": "eyJpZCI6MTQzfQ"
  }
}

Versioning

The API is versioned via the URL path (/v1/). Breaking changes will be released under a new version. We will provide migration guides and deprecation notices before retiring old versions.

SDKs and Tools

Official SDKs are available to simplify your integration:

JavaScript/TypeScript SDK - For server-side Node.js applications
Embeddable Widget - Drop-in UI for your frontend

Next Steps

Quick Start Guide - Get up and running in 5 minutes
Orders API - Create and manage orders
Webhooks - Receive real-time notifications

Overview

Quotes & Orders

Customers

Configuration

API Overview

API Overview

Base URL

Authentication

API Key Types

Using Secret Keys (Backend)

Using Public Keys (Frontend)

When to Use Each Key Type

Request Format

Rate Limiting

Default Limits

Rate Limit Headers

Handling Rate Limits

Idempotency Keys

Header

Validity

Examples

Response Format

Success Response

Error Response

Common Error Codes

Public Endpoints

Get Project Configuration

Get Supported Currencies

Versioning

SDKs and Tools

Next Steps

Overview

Quotes & Orders

Customers

Configuration

​API Overview

​Base URL

​Authentication

​API Key Types

​Using Secret Keys (Backend)

​Using Public Keys (Frontend)

​When to Use Each Key Type

​Request Format

​Rate Limiting

​Default Limits

​Rate Limit Headers

​Handling Rate Limits

​Idempotency Keys

​Header

​Validity

​Examples

​Response Format

​Success Response

​Error Response

​Common Error Codes

​Public Endpoints

​Get Project Configuration

​Get Supported Currencies

​Pagination

​Versioning

​SDKs and Tools

​Next Steps

API Overview

Base URL

Authentication

API Key Types

Using Secret Keys (Backend)

Using Public Keys (Frontend)

When to Use Each Key Type

Request Format

Rate Limiting

Default Limits

Rate Limit Headers

Handling Rate Limits

Idempotency Keys

Header

Validity

Examples

Response Format

Success Response

Error Response

Common Error Codes

Public Endpoints

Get Project Configuration

Get Supported Currencies

Pagination

Versioning

SDKs and Tools

Next Steps