跳至主要内容

点对点转账

点对点转账允许用户将加密货币直接发送到任意钱包地址。ONE SDK（@one_deploy/sdk v1.1.0）提供了用于 Web 应用的 OneSendWidget 和全平台的 sendTransaction API 方法。

Widget 用法（Web）​

OneSendWidget​

完整的发送加密货币 widget，处理收款方输入、代币选择、金额录入、Gas 估算、确认和交易追踪。

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

function SendPage() {
  return (
    <OneSendWidget
      walletAddress="0xSenderWalletAddress"
      chainId={1}
      defaultToken={{ symbol: 'ETH', chainId: 1 }}
      defaultRecipient=""
      allowedTokens={[
        { symbol: 'ETH', chainId: 1 },
        { symbol: 'USDC', chainId: 1, address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' },
        { symbol: 'USDT', chainId: 1, address: '0xdAC17F958D2ee523a2206206994597C13D831ec7' },
      ]}
      onSuccess={(result) => {
        console.log('Transfer sent:', result.txHash);
      }}
      onError={(error) => {
        console.error('Transfer failed:', error.message);
      }}
      onClose={() => {
        console.log('Widget closed');
      }}
      theme="light"
    />
  );
}

OneSendWidgetProps​

interface OneSendWidgetProps {
  /** 发送方钱包地址 */
  walletAddress: string;
  /** 转账的链 ID */
  chainId: number;
  /** 默认发送的代币 */
  defaultToken?: TokenIdentifier;
  /** 预填充的收款方地址 */
  defaultRecipient?: string;
  /** 预填充的金额 */
  defaultAmount?: string;
  /** 限制用户可发送的代币 */
  allowedTokens?: TokenIdentifier[];
  /** 启用 ENS / 地址簿解析（默认: true） */
  enableAddressResolution?: boolean;
  /** 转账在链上确认时调用 */
  onSuccess?: (result: EngineTransactionResponse) => void;
  /** 转账失败时调用 */
  onError?: (error: { code: string; message: string }) => void;
  /** 用户关闭 widget 时调用 */
  onClose?: () => void;
  /** Widget 颜色主题 */
  theme?: 'light' | 'dark' | 'auto';
  /** 覆盖 CSS 类名 */
  className?: string;
}

interface TokenIdentifier {
  symbol: string;
  chainId: number;
  address?: string;
}

API 方法：sendTransaction​

OneEngineClient 上的 sendTransaction 方法处理原生代币转账、ERC-20 代币转账和任意合约调用。

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

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

发送 ETH（原生代币）​

const result: EngineTransactionResponse = await engine.sendTransaction({
  from: '0xSenderAddress',
  to: '0xRecipientAddress',
  chainId: 1,
  value: '0.1',              // amount in ETH (human-readable)
  currency: 'native',
});

console.log(result);
// {
//   transactionId: 'etx_abc123',
//   txHash: '0x1234abcd...',
//   status: 'processing',
//   from: '0xSender...',
//   to: '0xRecipient...',
//   value: '0.1',
//   chainId: 1,
//   gasUsed: '21000',
//   createdAt: '2026-02-02T12:00:00Z',
// }

发送 USDC（ERC-20 代币）​

const result = await engine.sendTransaction({
  from: '0xSenderAddress',
  to: '0xRecipientAddress',
  chainId: 1,
  value: '250.00',            // amount in USDC (human-readable)
  currency: 'token',
  tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
});

console.log(`Sent 250 USDC -- tx: ${result.txHash}`);

发送自定义代币​

const result = await engine.sendTransaction({
  from: '0xSenderAddress',
  to: '0xRecipientAddress',
  chainId: 137,
  value: '1000',
  currency: 'token',
  tokenAddress: '0xYourCustomTokenAddress',
  tokenDecimals: 18,          // specify if non-standard discovery is needed
});

console.log(`Custom token transfer: ${result.txHash}`);

类型​

interface EngineTransactionRequest {
  /** 发送方钱包地址 */
  from: string;
  /** 接收方钱包地址 */
  to: string;
  /** 交易的链 ID */
  chainId: number;
  /** 发送金额（人类可读字符串） */
  value: string;
  /** 货币类型：'native' 为链原生代币，'token' 为 ERC-20 */
  currency: 'native' | 'token';
  /** ERC-20 合约地址（currency 为 'token' 时必填） */
  tokenAddress?: string;
  /** 代币精度覆盖（省略时自动检测） */
  tokenDecimals?: number;
  /** 可选数据载荷，用于原始合约调用 */
  data?: string;
  /** Gas limit 覆盖 */
  gasLimit?: string;
  /** 每 gas 最大费用（单位 wei，EIP-1559） */
  maxFeePerGas?: string;
  /** 每 gas 最大优先费用（单位 wei，EIP-1559） */
  maxPriorityFeePerGas?: string;
  /** 任意元数据 */
  metadata?: Record<string, string>;
}

interface EngineTransactionResponse {
  /** 内部交易标识符 */
  transactionId: string;
  /** 链上交易哈希 */
  txHash: string;
  /** 当前交易状态 */
  status: TransactionStatus;
  /** 发送方地址 */
  from: string;
  /** 接收方地址 */
  to: string;
  /** 转账金额（人类可读） */
  value: string;
  /** 链 ID */
  chainId: number;
  /** 使用的 Gas（单位 wei，字符串） */
  gasUsed?: string;
  /** 有效 gas 价格（单位 wei，字符串） */
  effectiveGasPrice?: string;
  /** 区块号（确认后可用） */
  blockNumber?: number;
  /** ISO 8601 创建时间戳 */
  createdAt: string;
  /** ISO 8601 最后更新时间戳 */
  updatedAt: string;
}

type TransactionStatus =
  | 'pending'
  | 'processing'
  | 'confirmed'
  | 'failed'
  | 'dropped';

追踪交易状态​

使用 getTransactionStatus 轮询确认状态：

async function waitForConfirmation(transactionId: string): Promise<EngineTransactionResponse> {
  let tx = await engine.getTransactionStatus(transactionId);

  while (tx.status === 'pending' || tx.status === 'processing') {
    await new Promise((r) => setTimeout(r, 3000));
    tx = await engine.getTransactionStatus(transactionId);
    console.log(`Status: ${tx.status}`);
  }

  return tx;
}

// Usage
const result = await engine.sendTransaction({
  from: '0xSender...',
  to: '0xRecipient...',
  chainId: 1,
  value: '0.5',
  currency: 'native',
});

const confirmed = await waitForConfirmation(result.transactionId);

if (confirmed.status === 'confirmed') {
  console.log(`Confirmed in block ${confirmed.blockNumber}`);
  console.log(`Gas used: ${confirmed.gasUsed}`);
} else {
  console.error(`Transaction ${confirmed.status}`);
}

完整示例：多代币转账​

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

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

const TOKENS = {
  USDC: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  USDT: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
  DAI: '0x6B175474E89094C44Da98b954EedeAC495271d0F',
};

async function sendPayment(
  from: string,
  to: string,
  amount: string,
  token: 'ETH' | 'USDC' | 'USDT' | 'DAI'
) {
  const isNative = token === 'ETH';

  const result = await engine.sendTransaction({
    from,
    to,
    chainId: 1,
    value: amount,
    currency: isNative ? 'native' : 'token',
    tokenAddress: isNative ? undefined : TOKENS[token],
  });

  console.log(`Sending ${amount} ${token} to ${to}`);
  console.log(`Transaction hash: ${result.txHash}`);

  // Wait for confirmation
  let tx = await engine.getTransactionStatus(result.transactionId);
  while (tx.status === 'pending' || tx.status === 'processing') {
    await new Promise((r) => setTimeout(r, 3000));
    tx = await engine.getTransactionStatus(result.transactionId);
  }

  if (tx.status === 'confirmed') {
    console.log(`${amount} ${token} delivered to ${to} in block ${tx.blockNumber}`);
  } else {
    throw new Error(`Transfer failed with status: ${tx.status}`);
  }

  return tx;
}

// Send 100 USDC
await sendPayment('0xSender...', '0xRecipient...', '100', 'USDC');

// Send 0.05 ETH
await sendPayment('0xSender...', '0xRecipient...', '0.05', 'ETH');

参见​