Skip to main content

​
Core Concepts

This page explains the fundamental concepts and entities in NowRamp.

​
Multi-Tenancy Model

NowRamp uses a hierarchical multi-tenant architecture:

​
Partners

Partners are top-level tenants representing companies using the platform. Each partner has:
  • Unique identifier and branding
  • One or more projects
  • API key management
  • Webhook configurations

​
Projects

Projects are sub-tenants under partners, typically representing different applications or environments (staging, production). Projects have:
  • Isolated customer base
  • Custom provider configurations
  • Specific currency and limit settings
  • Widget branding options

​
Customers

Customers are end users under a project. They’re identified by an externalUserId that you provide, allowing you to link them to users in your system.

​
Order Flow

The order lifecycle follows this flow:
1

Quote

Customer requests a quote with amount, source currency, and target cryptocurrency. Quotes are valid for a limited time and include real-time exchange rates.
2

Order Creation

Customer accepts a quote, creating an order. The system generates an execution plan with required steps.
3

Execution Plan

The workflow engine executes the plan steps:
  • KYC verification (if required)
  • Payment processing
  • Crypto transfer
4

Completion

Order completes when crypto is sent to the customer’s wallet. Webhooks notify your system of status changes.

​
Order Status Flow

​
Provider Architecture

NowRamp uses a pluggable provider system:
Provider TypePurposeExamples
KYCIdentity verificationKYCAID, Ondato
RatesExchange rate dataCoinGecko
ScreeningWallet AML screeningChainalysis
PaymentFiat payment processingComing soon
Each project can configure which providers to use via Provider Instances.

​
Wallets

Customer wallets store cryptocurrency addresses. When added, wallets are automatically:
  1. Validated - Address format checked for the specific blockchain
  2. Screened - AML compliance check via Chainalysis
  3. Stored - Associated with the customer for future orders
Wallets flagged by screening cannot be used for orders.

​
KYC Cases

KYC (Know Your Customer) cases track identity verification:
StatusDescription
pendingKYC process not started
in_progressCustomer is completing verification
approvedIdentity verified successfully
rejectedVerification failed
expiredVerification link expired

​
Compliance

Built-in compliance features include:
  • Policy Packs - Configurable compliance rules per project
  • Transaction Limits - Daily, weekly, and monthly limits
  • Wallet Screening - AML checks on all wallet addresses
  • Audit Logging - Complete audit trail of all operations

​
Idempotency

All write operations support idempotency keys to prevent duplicate processing: 
curl -X POST https://api.nowramp.com/v1/orders \
  -H "X-API-Key: your_api_key" \
  -H "Idempotency-Key: unique_request_id" \
  -d '{"quoteId": "quote_123"}'
Requests with the same idempotency key within 24 hours return the original response.