出金（出售加密货币）

出金流程允许用户将加密货币兑换回法币，并通过银行转账、移动支付或其他本地方式接收款项。ONE SDK（@one_deploy/sdk v1.1.0）提供了用于 Web 的即插即用 widget 和全平台的 API 方法。

Widget 用法（Web）

OneOfframpWidget

功能完整的出售加密货币 widget，处理代币选择、金额输入、报价展示、提现方式选择和交易追踪。

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

function SellCryptoPage() {
  return (
    <OneOfframpWidget
      defaultCryptoCurrency="USDT"
      defaultFiatCurrency="USD"
      defaultCryptoAmount="100"
      allowedCryptoCurrencies={['USDT', 'USDC', 'ETH']}
      allowedPayoutMethods={['bank_transfer', 'mobile_money']}
      walletAddress="0xYourUserWalletAddress"
      chainId={137}
      onSuccess={(result) => {
        console.log('Sale complete:', result.transactionId);
      }}
      onError={(error) => {
        console.error('Sale failed:', error.message);
      }}
      onClose={() => {
        console.log('Widget closed');
      }}
      theme="dark"
    />
  );
}

OneOfframpWidgetProps

interface OneOfframpWidgetProps {
  /** 默认出售的加密代币 */
  defaultCryptoCurrency?: string;
  /** 默认提现的法币币种（ISO 4217） */
  defaultFiatCurrency?: string;
  /** 预填充的出售加密货币数量 */
  defaultCryptoAmount?: string;
  /** 限制用户可出售的加密代币 */
  allowedCryptoCurrencies?: string[];
  /** 限制可用于提现的法币币种 */
  allowedFiatCurrencies?: string[];
  /** 限制可用的提现方式 */
  allowedPayoutMethods?: PayoutMethodType[];
  /** 持有加密货币的源钱包地址 */
  walletAddress: string;
  /** 源链 ID */
  chainId?: number;
  /** 出售成功完成时调用 */
  onSuccess?: (result: OfframpTransaction) => void;
  /** 出售失败时调用 */
  onError?: (error: { code: string; message: string }) => void;
  /** 用户关闭 widget 时调用 */
  onClose?: () => void;
  /** Widget 颜色主题 */
  theme?: 'light' | 'dark' | 'auto';
  /** 覆盖根元素的 CSS 类名 */
  className?: string;
}

type PayoutMethodType =
  | 'bank_transfer'
  | 'mobile_money'
  | 'card_refund'
  | 'paypal';

预设 Widget

锁定源代币，提供简化的出售体验：

import {
  OneSellUSDTWidget,
  OneSellUSDCWidget,
  OneSellETHWidget,
} from '@one_deploy/sdk';

function QuickSellPage() {
  return (
    <>
      {/* Sell USDT to USD via bank transfer */}
      <OneSellUSDTWidget
        walletAddress="0xAbc..."
        defaultFiatCurrency="USD"
        allowedPayoutMethods={['bank_transfer']}
        onSuccess={(tx) => console.log('USDT sold', tx)}
      />

      {/* Sell USDC to EUR */}
      <OneSellUSDCWidget
        walletAddress="0xAbc..."
        defaultFiatCurrency="EUR"
        onSuccess={(tx) => console.log('USDC sold', tx)}
      />

      {/* Sell ETH to NGN via mobile money */}
      <OneSellETHWidget
        walletAddress="0xAbc..."
        defaultFiatCurrency="NGN"
        allowedPayoutMethods={['mobile_money']}
        chainId={1}
        onSuccess={(tx) => console.log('ETH sold', tx)}
      />
    </>
  );
}

API 方法（全平台）

getOfframpQuote

获取出售报价 -- 用户出售一定数量的加密货币可以收到多少法币。

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

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

const quote: OfframpQuote = await engine.getOfframpQuote(
  'USDT',            // cryptoCurrency
  '500',             // cryptoAmount
  'USD',             // fiatCurrency
  'bank_transfer'    // payoutMethod (optional)
);

console.log(quote);
// {
//   quoteId: 'oq_def456',
//   cryptoCurrency: 'USDT',
//   cryptoAmount: '500',
//   fiatCurrency: 'USD',
//   fiatAmount: 496.25,
//   exchangeRate: 0.9985,
//   fee: { amount: '2.50', currency: 'USDT' },
//   payoutMethod: 'bank_transfer',
//   expiresAt: '2026-02-02T12:10:00Z',
// }

createOfframpTransaction

根据报价发起出售交易。用户需要在此流程中批准链上代币转移。

const tx: OfframpTransaction = await engine.createOfframpTransaction({
  quoteId: quote.quoteId,
  walletAddress: '0xAbc...',
  chainId: 137,
  payoutDetails: {
    method: 'bank_transfer',
    bankName: 'Example Bank',
    accountNumber: '1234567890',
    routingNumber: '021000021',
    accountName: 'Alice Smith',
  },
  metadata: { userId: 'user_42' },
});

console.log(tx);
// {
//   transactionId: 'otx_ghi789',
//   status: 'pending',
//   cryptoAmount: '500',
//   cryptoCurrency: 'USDT',
//   fiatAmount: 496.25,
//   fiatCurrency: 'USD',
//   createdAt: '2026-02-02T12:00:00Z',
// }

getOfframpStatus

检查出金交易的当前状态。

const status: OfframpTransaction = await engine.getOfframpStatus('otx_ghi789');

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

getSupportedPayoutMethods

列出指定国家可用的提现方式。

const methods = await engine.getSupportedPayoutMethods('NG');
// [
//   { type: 'bank_transfer', name: 'Bank Transfer', currencies: ['NGN'] },
//   { type: 'mobile_money', name: 'Mobile Money', currencies: ['NGN'] },
// ]

// Omit country for global list
const allMethods = await engine.getSupportedPayoutMethods();

类型

interface OfframpQuote {
  /** 服务器生成的报价标识符 */
  quoteId: string;
  /** 出售的加密代币 */
  cryptoCurrency: string;
  /** 出售的加密货币数量（字符串以保证精度） */
  cryptoAmount: string;
  /** 用户将收到的法币币种（ISO 4217） */
  fiatCurrency: string;
  /** 扣除手续费后用户将收到的法币金额 */
  fiatAmount: number;
  /** 加密货币到法币的汇率 */
  exchangeRate: number;
  /** 手续费明细 */
  fee: {
    amount: string;
    currency: string;
  };
  /** 此报价的提现方式 */
  payoutMethod: PayoutMethodType;
  /** 此报价过期的 ISO 8601 时间戳 */
  expiresAt: string;
}

interface OfframpRequest {
  /** 来自 getOfframpQuote 的报价 ID */
  quoteId: string;
  /** 持有加密货币的钱包地址 */
  walletAddress: string;
  /** 源代币的链 ID */
  chainId?: number;
  /** 提现目标详情 */
  payoutDetails: PayoutDetails;
  /** 任意元数据 */
  metadata?: Record<string, string>;
}

interface PayoutDetails {
  /** 提现方式类型 */
  method: PayoutMethodType;
  /** 银行名称（用于 bank_transfer） */
  bankName?: string;
  /** 银行账号 */
  accountNumber?: string;
  /** 路由号 / 分类代码 */
  routingNumber?: string;
  /** 账户持有人姓名 */
  accountName?: string;
  /** 手机号码（用于 mobile_money） */
  mobileNumber?: string;
  /** 移动支付提供商 */
  mobileProvider?: string;
  /** PayPal 邮箱（用于 paypal） */
  paypalEmail?: string;
}

interface OfframpTransaction {
  /** 唯一交易标识符 */
  transactionId: string;
  /** 当前状态 */
  status: PaymentStatus;
  /** 从钱包扣除的加密货币数量 */
  cryptoAmount: string;
  /** 加密代币符号 */
  cryptoCurrency: string;
  /** 提现的法币金额 */
  fiatAmount: number;
  /** 法币币种代码 */
  fiatCurrency: string;
  /** 使用的提现方式 */
  payoutMethod: PayoutMethodType;
  /** 加密货币扣款的链上交易哈希 */
  txHash?: string;
  /** 提现参考号（银行参考号、移动支付 ID 等） */
  payoutReference?: string;
  /** 链 ID */
  chainId: number;
  /** ISO 8601 创建时间戳 */
  createdAt: string;
  /** ISO 8601 最后更新时间戳 */
  updatedAt: string;
}

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

完整示例：纯 API 出金

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

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

async function sellUSDT(wallet: string, amount: string) {
  // 1. Check supported payout methods for Nigeria
  const methods = await engine.getSupportedPayoutMethods('NG');
  console.log('Available methods:', methods.map((m) => m.type));

  // 2. Get a quote
  const quote = await engine.getOfframpQuote('USDT', amount, 'NGN', 'bank_transfer');
  console.log(`You will receive ₦${quote.fiatAmount} (rate: ${quote.exchangeRate})`);

  // 3. Create the sell transaction
  const tx = await engine.createOfframpTransaction({
    quoteId: quote.quoteId,
    walletAddress: wallet,
    chainId: 137,
    payoutDetails: {
      method: 'bank_transfer',
      bankName: 'GTBank',
      accountNumber: '0123456789',
      accountName: 'Alice Adeyemi',
    },
  });

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

  if (current.status === 'completed') {
    console.log(`Payout sent -- ref: ${current.payoutReference}`);
  } else {
    console.error('Sale failed:', current.status);
  }
}

参见

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