入金（购买加密货币）

入金流程允许用户使用法币支付方式（如信用卡/借记卡、银行转账和移动支付）购买加密货币。ONE SDK（@one_deploy/sdk v1.1.0）提供了即插即用的 React widget 和完整的 API 方法集。

Widget 用法（Web）

OneOnrampWidget

主 widget，渲染完整的购买加密货币流程：货币选择、金额输入、报价预览、支付方式选择和交易状态。

import { OneOnrampWidget } from '@one_deploy/sdk';

function BuyCryptoPage() {
  return (
    <OneOnrampWidget
      defaultFiatCurrency="USD"
      defaultCryptoCurrency="USDT"
      defaultFiatAmount={100}
      allowedCryptoCurrencies={['USDT', 'USDC', 'ETH', 'BTC']}
      allowedPaymentMethods={['card', 'bank_transfer']}
      walletAddress="0xYourUserWalletAddress"
      chainId={1}
      onSuccess={(result) => {
        console.log('Purchase complete:', result.transactionId);
      }}
      onError={(error) => {
        console.error('Purchase failed:', error.message);
      }}
      onClose={() => {
        console.log('Widget closed');
      }}
      theme="light"
    />
  );
}

OneOnrampWidgetProps

interface OneOnrampWidgetProps {
  /** ISO 4217 法币货币代码，用于默认选择 */
  defaultFiatCurrency?: string;
  /** 默认选择的加密代币符号 */
  defaultCryptoCurrency?: string;
  /** 预填充的法币金额 */
  defaultFiatAmount?: number;
  /** 限制用户可购买的加密代币 */
  allowedCryptoCurrencies?: string[];
  /** 限制显示的法币币种 */
  allowedFiatCurrencies?: string[];
  /** 限制可用的支付方式 */
  allowedPaymentMethods?: PaymentMethodType[];
  /** 购买代币的目标钱包地址 */
  walletAddress: string;
  /** 代币交付的目标链 ID */
  chainId?: number;
  /** 购买成功完成时调用 */
  onSuccess?: (result: OnrampTransaction) => void;
  /** 购买失败时调用 */
  onError?: (error: { code: string; message: string }) => void;
  /** 用户关闭 widget 时调用 */
  onClose?: () => void;
  /** Widget 颜色主题 */
  theme?: 'light' | 'dark' | 'auto';
  /** 覆盖根元素的 CSS 类名 */
  className?: string;
}

type PaymentMethodType =
  | 'card'
  | 'bank_transfer'
  | 'mobile_money'
  | 'apple_pay'
  | 'google_pay';

预设 Widget

SDK 提供了常见购买流程的预设 widget，锁定目标代币：

import {
  OneBuyUSDTWidget,
  OneBuyUSDCWidget,
  OneBuyETHWidget,
  OneBuyBTCWidget,
} from '@one_deploy/sdk';

// Each preset accepts the same props as OneOnrampWidget
// minus defaultCryptoCurrency (already set).

function QuickBuyPage() {
  return (
    <>
      {/* Buy USDT -- card only */}
      <OneBuyUSDTWidget
        walletAddress="0xAbc..."
        defaultFiatCurrency="USD"
        defaultFiatAmount={50}
        allowedPaymentMethods={['card']}
        onSuccess={(tx) => console.log('USDT purchased', tx)}
      />

      {/* Buy USDC */}
      <OneBuyUSDCWidget
        walletAddress="0xAbc..."
        defaultFiatCurrency="EUR"
        onSuccess={(tx) => console.log('USDC purchased', tx)}
      />

      {/* Buy ETH */}
      <OneBuyETHWidget
        walletAddress="0xAbc..."
        chainId={1}
        onSuccess={(tx) => console.log('ETH purchased', tx)}
      />

      {/* Buy BTC */}
      <OneBuyBTCWidget
        walletAddress="0xAbc..."
        onSuccess={(tx) => console.log('BTC purchased', tx)}
      />
    </>
  );
}

API 方法（全平台）

在需要完全控制或在浏览器外运行时，直接使用 OneEngineClient。

getOnrampQuote

获取使用法币购买加密货币的报价。

import { OneEngineClient } from '@one_deploy/sdk';

const engine = new OneEngineClient({
  apiKey: 'YOUR_API_KEY',
  projectId: 'YOUR_PROJECT_ID',
});

const quote: OnrampQuote = await engine.getOnrampQuote(
  'USD',           // fiatCurrency
  100,             // fiatAmount
  'USDT',          // cryptoCurrency
  'card'           // paymentMethod (optional)
);

console.log(quote);
// {
//   fiatCurrency: 'USD',
//   fiatAmount: 100,
//   cryptoCurrency: 'USDT',
//   cryptoAmount: '99.45',
//   exchangeRate: 0.9945,
//   fee: { amount: 2.50, currency: 'USD' },
//   paymentMethod: 'card',
//   expiresAt: '2026-02-02T12:05:00Z',
//   quoteId: 'quote_abc123',
// }

createOnrampSession

根据报价创建购买会话。返回一个包含跳转 URL 或内联支付详情的会话对象。

const session: OnrampSession = await engine.createOnrampSession({
  quoteId: quote.quoteId,
  walletAddress: '0xAbc...',
  chainId: 1,
  redirectUrl: 'https://myapp.com/payment/callback',
  metadata: { userId: 'user_42' },
});

console.log(session);
// {
//   sessionId: 'sess_xyz789',
//   status: 'pending',
//   paymentUrl: 'https://pay.one23.io/s/sess_xyz789',
//   expiresAt: '2026-02-02T12:15:00Z',
// }

getOnrampStatus

轮询或检查入金交易的状态。

const tx: OnrampTransaction = await engine.getOnrampStatus('sess_xyz789');

console.log(tx.status); // 'processing' | 'completed' | 'failed' | ...

getSupportedCurrencies

列出所有支持入金的加密货币。

const cryptos = await engine.getSupportedCurrencies();
// [{ symbol: 'USDT', name: 'Tether', chains: [1, 137, 42161] }, ...]

getSupportedFiatCurrencies

列出所有支持入金的法币币种。

const fiats = await engine.getSupportedFiatCurrencies();
// [{ code: 'USD', name: 'US Dollar', symbol: '$' }, ...]

getSupportedPaymentMethods

列出指定国家可用的支付方式。

const methods = await engine.getSupportedPaymentMethods('US');
// [{ type: 'card', name: 'Credit / Debit Card', currencies: ['USD'] }, ...]

// Omit country for all available methods globally
const allMethods = await engine.getSupportedPaymentMethods();

类型

interface OnrampQuote {
  /** 服务器生成的报价标识符 */
  quoteId: string;
  /** 来源法币币种（ISO 4217） */
  fiatCurrency: string;
  /** 用户将支付的法币金额 */
  fiatAmount: number;
  /** 目标加密代币符号 */
  cryptoCurrency: string;
  /** 用户预计收到的加密货币数量（字符串以保证精度） */
  cryptoAmount: string;
  /** 法币到加密货币的汇率 */
  exchangeRate: number;
  /** 手续费明细 */
  fee: {
    amount: number;
    currency: string;
  };
  /** 此报价使用的支付方式 */
  paymentMethod: PaymentMethodType;
  /** 此报价过期的 ISO 8601 时间戳 */
  expiresAt: string;
}

interface OnrampSessionRequest {
  /** 来自 getOnrampQuote 的报价 ID */
  quoteId: string;
  /** 代币交付的钱包地址 */
  walletAddress: string;
  /** 代币交付的目标链 */
  chainId?: number;
  /** 支付后重定向用户的 URL（银行卡/银行转账流程） */
  redirectUrl?: string;
  /** 附加到会话的任意元数据 */
  metadata?: Record<string, string>;
}

interface OnrampSession {
  /** 唯一会话标识符 */
  sessionId: string;
  /** 当前会话状态 */
  status: PaymentStatus;
  /** 完成支付的 URL（用于基于重定向的支付方式） */
  paymentUrl?: string;
  /** ISO 8601 过期时间 */
  expiresAt: string;
}

interface OnrampTransaction {
  /** 会话 / 交易 ID */
  transactionId: string;
  /** 当前状态 */
  status: PaymentStatus;
  /** 扣收的法币金额 */
  fiatAmount: number;
  /** 法币币种代码 */
  fiatCurrency: string;
  /** 交付的加密货币数量 */
  cryptoAmount: string;
  /** 加密代币符号 */
  cryptoCurrency: string;
  /** 目标钱包地址 */
  walletAddress: string;
  /** 链上交易哈希（完成后可用） */
  txHash?: string;
  /** 代币交付的链 ID */
  chainId: number;
  /** ISO 8601 创建时间戳 */
  createdAt: string;
  /** ISO 8601 最后更新时间戳 */
  updatedAt: string;
}

type PaymentStatus =
  | 'pending'
  | 'processing'
  | 'completed'
  | 'failed'
  | 'expired'
  | 'refunded';

完整示例：纯 API 入金

不使用 widget 的完整服务端流程：

import { OneEngineClient } from '@one_deploy/sdk';

const engine = new OneEngineClient({
  apiKey: process.env.ONE_API_KEY!,
  projectId: process.env.ONE_PROJECT_ID!,
});

async function buyUSDT(userWallet: string, amountUSD: number) {
  // 1. Get a quote
  const quote = await engine.getOnrampQuote('USD', amountUSD, 'USDT', 'card');
  console.log(`Rate: 1 USD = ${quote.exchangeRate} USDT, fee: $${quote.fee.amount}`);

  // 2. Create a session
  const session = await engine.createOnrampSession({
    quoteId: quote.quoteId,
    walletAddress: userWallet,
    chainId: 137, // Polygon
    redirectUrl: 'https://myapp.com/payment/done',
  });

  // 3. Redirect user to paymentUrl (or embed in iframe)
  console.log('Send user to:', session.paymentUrl);

  // 4. Poll for completion
  let tx = await engine.getOnrampStatus(session.sessionId);
  while (tx.status === 'pending' || tx.status === 'processing') {
    await new Promise((r) => setTimeout(r, 5000));
    tx = await engine.getOnrampStatus(session.sessionId);
  }

  if (tx.status === 'completed') {
    console.log(`Delivered ${tx.cryptoAmount} USDT -- tx: ${tx.txHash}`);
  } else {
    console.error('Purchase failed:', tx.status);
  }
}

参见

• 支付概览
• 出金（出售加密货币）
• Pay Widget -- 包含入金模式的统一支付组件。