法币出入金 API

法币出入金 API 提供了 10 个方法，用于使用法币购买加密货币（入金）和将加密货币兑换为法币（出金）。涵盖报价、会话管理、状态跟踪，以及查询支持的货币和支付方式。

入金方法

方法	参数	返回值	描述
`getOnrampQuote(request)`	`request: OnrampQuoteRequest`	`ApiResponse<OnrampQuote>`	获取使用法币购买加密货币的报价。
`createOnrampSession(request)`	`request: OnrampSessionRequest`	`ApiResponse<OnrampSession>`	创建支付会话并返回结账 URL 或小组件配置。
`getOnrampStatus(sessionId)`	`sessionId: string`	`ApiResponse<OnrampTransaction>`	返回入金交易的当前状态。
`getSupportedCurrencies(chainId?)`	`chainId?: string`	`ApiResponse<OnrampCurrency[]>`	列出可购买的加密货币，可选按链筛选。
`getSupportedFiatCurrencies()`	--	`ApiResponse<FiatCurrency[]>`	列出入金支付接受的法币币种。
`getSupportedPaymentMethods(fiatCurrency?)`	`fiatCurrency?: string`	`ApiResponse<PaymentMethod[]>`	列出入金支付方式（银行卡、银行转账、移动支付）。

出金方法

方法	参数	返回值	描述
`getOfframpQuote(request)`	`request: OfframpQuoteRequest`	`ApiResponse<OfframpQuote>`	获取将加密货币兑换为法币的报价。
`createOfframpTransaction(request)`	`request: OfframpRequest`	`ApiResponse<OfframpTransaction>`	发起一笔出金交易。
`getOfframpStatus(transactionId)`	`transactionId: string`	`ApiResponse<OfframpTransaction>`	返回出金交易的当前状态。
`getSupportedPayoutMethods(fiatCurrency?)`	`fiatCurrency?: string`	`ApiResponse<PayoutMethod[]>`	列出出金的提现方式（银行转账、移动支付）。

类型

`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;
}

辅助类型

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;
}

示例

入金：购买加密货币

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

出金：卖出加密货币

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

列出支持的货币

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

后续步骤

Swap API -- 在加密代币之间进行兑换。
Bills & Staking API -- 支付账单和质押加密货币。

入金方法​

出金方法​

类型​

OnrampQuoteRequest​

OnrampQuote​

OnrampSessionRequest​

OnrampSession​

OnrampTransaction​

OfframpQuoteRequest​

OfframpQuote​

OfframpRequest​

OfframpTransaction​

辅助类型​

示例​

入金：购买加密货币​

出金：卖出加密货币​

列出支持的货币​

后续步骤​

入金方法

出金方法

类型

`OnrampQuoteRequest`

`OnrampQuote`

`OnrampSessionRequest`

`OnrampSession`

`OnrampTransaction`

`OfframpQuoteRequest`

`OfframpQuote`

`OfframpRequest`

`OfframpTransaction`

辅助类型

示例

入金：购买加密货币

出金：卖出加密货币

列出支持的货币

后续步骤