Skip to main content

On-ramp & Off-ramp API

The On-ramp and Off-ramp API provides 10 methods for buying crypto with fiat (on-ramp) and selling crypto to fiat (off-ramp). It covers quotes, session management, status tracking, and querying supported currencies and payment methods.

On-ramp Methods​

MethodParametersReturnsDescription
getOnrampQuote(request)request: OnrampQuoteRequestApiResponse<OnrampQuote>Gets a price quote for buying crypto with fiat.
createOnrampSession(request)request: OnrampSessionRequestApiResponse<OnrampSession>Creates a payment session and returns a checkout URL or widget config.
getOnrampStatus(sessionId)sessionId: stringApiResponse<OnrampTransaction>Returns the current status of an on-ramp transaction.
getSupportedCurrencies(chainId?)chainId?: stringApiResponse<OnrampCurrency[]>Lists crypto currencies available for purchase, optionally filtered by chain.
getSupportedFiatCurrencies()--ApiResponse<FiatCurrency[]>Lists fiat currencies accepted for on-ramp payments.
getSupportedPaymentMethods(fiatCurrency?)fiatCurrency?: stringApiResponse<PaymentMethod[]>Lists payment methods (card, bank, mobile money) for on-ramp.

Off-ramp Methods​

MethodParametersReturnsDescription
getOfframpQuote(request)request: OfframpQuoteRequestApiResponse<OfframpQuote>Gets a price quote for selling crypto to fiat.
createOfframpTransaction(request)request: OfframpRequestApiResponse<OfframpTransaction>Initiates an off-ramp transaction.
getOfframpStatus(transactionId)transactionId: stringApiResponse<OfframpTransaction>Returns the current status of an off-ramp transaction.
getSupportedPayoutMethods(fiatCurrency?)fiatCurrency?: stringApiResponse<PayoutMethod[]>Lists payout methods (bank, mobile money) for off-ramp.

Types​

OnrampQuoteRequest​

interface OnrampQuoteRequest {
  /** Fiat currency code (e.g. "USD", "NGN"). */
  fiatCurrency: string;
  /** Crypto token to purchase (e.g. "USDC", "ETH"). */
  cryptoCurrency: string;
  /** Fiat amount to spend. */
  fiatAmount: string;
  /** Chain for delivery. */
  chainId: string;
  /** Payment method identifier. */
  paymentMethod?: string;
}

OnrampQuote​

interface OnrampQuote {
  quoteId: string;
  fiatCurrency: string;
  fiatAmount: string;
  cryptoCurrency: string;
  /** Estimated crypto amount the user will receive. */
  cryptoAmount: string;
  /** Exchange rate (crypto per fiat). */
  exchangeRate: string;
  /** Fee in fiat. */
  fee: string;
  /** Total fiat charge (fiatAmount + fee). */
  totalFiatCharge: string;
  /** Quote expiry timestamp. */
  expiresAt: string;
}

OnrampSessionRequest​

interface OnrampSessionRequest {
  /** Quote ID from a previous getOnrampQuote call. */
  quoteId: string;
  /** Wallet address to receive the crypto. */
  walletAddress: string;
  /** Payment method to use. */
  paymentMethod: string;
  /** Optional redirect URL after payment completes. */
  redirectUrl?: string;
}

OnrampSession​

interface OnrampSession {
  sessionId: string;
  /** URL to redirect the user to for payment. */
  checkoutUrl: string;
  /** Alternative: widget configuration for embedded checkout. */
  widgetConfig?: Record<string, unknown>;
  status: 'created' | 'awaiting_payment' | 'processing' | 'completed' | 'failed' | 'expired';
  expiresAt: string;
}

OnrampTransaction​

interface OnrampTransaction {
  sessionId: string;
  status: 'awaiting_payment' | 'processing' | 'completed' | 'failed' | 'expired';
  fiatCurrency: string;
  fiatAmount: string;
  cryptoCurrency: string;
  /** Actual crypto amount delivered (available once completed). */
  cryptoAmount?: string;
  txHash?: string;
  walletAddress: string;
  createdAt: string;
  completedAt?: string;
}

OfframpQuoteRequest​

interface OfframpQuoteRequest {
  /** Crypto token to sell (e.g. "USDC"). */
  cryptoCurrency: string;
  /** Amount of crypto to sell. */
  cryptoAmount: string;
  /** Target fiat currency (e.g. "USD", "NGN"). */
  fiatCurrency: string;
  /** Chain the crypto is on. */
  chainId: string;
  /** Payout method identifier. */
  payoutMethod?: string;
}

OfframpQuote​

interface OfframpQuote {
  quoteId: string;
  cryptoCurrency: string;
  cryptoAmount: string;
  fiatCurrency: string;
  /** Estimated fiat amount the user will receive. */
  fiatAmount: string;
  exchangeRate: string;
  fee: string;
  /** Net fiat payout after fees. */
  netFiatAmount: string;
  expiresAt: string;
}

OfframpRequest​

interface OfframpRequest {
  /** Quote ID from a previous getOfframpQuote call. */
  quoteId: string;
  /** Wallet address sending the crypto. */
  walletAddress: string;
  /** Payout method to use. */
  payoutMethod: string;
  /** Payout details (bank account, mobile number, etc.). */
  payoutDetails: Record<string, string>;
}

OfframpTransaction​

interface OfframpTransaction {
  transactionId: string;
  status: 'pending_crypto' | 'crypto_received' | 'processing_payout' | 'completed' | 'failed';
  cryptoCurrency: string;
  cryptoAmount: string;
  fiatCurrency: string;
  fiatAmount?: string;
  payoutMethod: string;
  txHash?: string;
  createdAt: string;
  completedAt?: string;
}

Supporting Types​

interface OnrampCurrency {
  symbol: string;
  name: string;
  chainId: string;
  contractAddress?: string;
  logoUrl?: string;
  minAmount: string;
  maxAmount: string;
}

interface FiatCurrency {
  code: string;
  name: string;
  symbol: string;
  minAmount: string;
  maxAmount: string;
}

interface PaymentMethod {
  id: string;
  name: string;
  type: 'card' | 'bank_transfer' | 'mobile_money';
  fiatCurrencies: string[];
  processingTime: string;
}

interface PayoutMethod {
  id: string;
  name: string;
  type: 'bank_transfer' | 'mobile_money';
  fiatCurrencies: string[];
  processingTime: string;
}

Examples​

On-ramp: Buy Crypto​

// 1. Get a quote
const quoteRes = await engine.getOnrampQuote({
  fiatCurrency: 'USD',
  cryptoCurrency: 'USDC',
  fiatAmount: '100',
  chainId: 'ethereum',
});

if (!quoteRes.success) {
  console.error('Quote failed:', quoteRes.error);
  return;
}

const quote = quoteRes.data!;
console.log(`Buy ~${quote.cryptoAmount} USDC for $${quote.totalFiatCharge}`);

// 2. Create a payment session
const sessionRes = await engine.createOnrampSession({
  quoteId: quote.quoteId,
  walletAddress: '0xABC...',
  paymentMethod: 'card',
  redirectUrl: 'https://myapp.com/payment-complete',
});

if (sessionRes.success && sessionRes.data) {
  // Redirect user to checkout
  window.location.href = sessionRes.data.checkoutUrl;
}

// 3. Poll for completion
const statusRes = await engine.getOnrampStatus(sessionRes.data!.sessionId);
if (statusRes.success) {
  console.log('Status:', statusRes.data!.status);
}

Off-ramp: Sell Crypto​

// 1. Get a quote
const quoteRes = await engine.getOfframpQuote({
  cryptoCurrency: 'USDC',
  cryptoAmount: '500',
  fiatCurrency: 'NGN',
  chainId: 'ethereum',
});

const quote = quoteRes.data!;
console.log(`Sell 500 USDC -> ${quote.fiatCurrency} ${quote.netFiatAmount}`);

// 2. Create the off-ramp transaction
const txRes = await engine.createOfframpTransaction({
  quoteId: quote.quoteId,
  walletAddress: '0xABC...',
  payoutMethod: 'bank_transfer',
  payoutDetails: {
    bankCode: '058',
    accountNumber: '0123456789',
    accountName: 'Jane Doe',
  },
});

if (txRes.success) {
  console.log('Off-ramp initiated:', txRes.data!.transactionId);
}

// 3. Poll for payout
const statusRes = await engine.getOfframpStatus(txRes.data!.transactionId);
console.log('Status:', statusRes.data!.status);

List Supported Currencies​

// Crypto currencies available on Ethereum
const cryptoRes = await engine.getSupportedCurrencies('ethereum');
// Fiat currencies
const fiatRes = await engine.getSupportedFiatCurrencies();
// Payment methods for USD
const methodsRes = await engine.getSupportedPaymentMethods('USD');
// Payout methods for NGN
const payoutRes = await engine.getSupportedPayoutMethods('NGN');

Next Steps​