交易历史
ONE SDK 的 engine client 提供了获取钱包交易历史的 API，支持筛选、分页和实时状态跟踪。
getWalletTransactions
获取钱包地址的交易历史，支持可选的筛选和分页。
import { useOneClient } from '@one_deploy/sdk';
function TransactionList() {
const { engineClient } = useOneClient();
const loadHistory = async () => {
const result = await engineClient.getWalletTransactions(
'0x1234...abcd'
);
result.transactions.forEach((tx) => {
console.log(`${tx.type}: ${tx.value} ${tx.currency} - ${tx.status}`);
});
};
return <button onClick={loadHistory}>Load History</button>;
}
方法签名
getWalletTransactions(
walletAddress: string,
options?: TransactionQueryOptions
): Promise<TransactionPage>
参数：
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
walletAddress | string | 是 | 要查询的钱包地址。 |
options | TransactionQueryOptions | 否 | 筛选和分页选项。 |
TransactionQueryOptions
interface TransactionQueryOptions {
/** 按交易类型筛选。 */
type?: TransactionType | TransactionType[];
/** 按交易状态筛选。 */
status?: TransactionStatus | TransactionStatus[];
/** 按链 ID 筛选。 */
chainId?: number;
/** 每页交易数。默认为 20。最大 100。 */
limit?: number;
/** 上一次响应中的分页游标。 */
cursor?: string;
/** 开始日期筛选（ISO 8601）。 */
fromDate?: string;
/** 结束日期筛选（ISO 8601）。 */
toDate?: string;
/** 排序顺序。默认为 'desc'（最新在前）。 */
sortOrder?: 'asc' | 'desc';
}
TransactionPage
interface TransactionPage {
/** 当前页的交易数组。 */
transactions: Transaction[];
/** 下一页的游标，如果没有更多页则为 null。 */
nextCursor: string | null;
/** 匹配查询的交易总数（跨所有页）。 */
totalCount: number;
}
Transaction 类型
interface Transaction {
/** ONE SDK 系统中的唯一交易标识符。 */
id: string;
/** 链上交易哈希。 */
transactionHash: string;
/** 交易类型。 */
type: TransactionType;
/** 当前状态。 */
status: TransactionStatus;
/** 发送方地址。 */
fromAddress: string;
/** 接收方地址。 */
toAddress: string;
/** 交易金额，以十进制字符串表示。 */
value: string;
/** 代币符号（如 'ETH'、'USDC'）。 */
currency: string;
/** 交易时的美元价值。 */
valueUsd: string;
/** 链 ID。 */
chainId: number;
/** 以原生代币支付的 Gas 费用。 */
gasFee: string;
/** Gas 费用的美元价值。 */
gasFeeUsd: string;
/** 交易所在的区块号，待处理时为 null。 */
blockNumber: number | null;
/** ISO 8601 时间戳。 */
timestamp: string;
/** 区块浏览器 URL。 */
explorerUrl: string;
/** 可选的备注或说明。 */
memo: string | null;
}
type TransactionType =
| 'send'
| 'receive'
| 'swap'
| 'buy'
| 'sell'
| 'deposit'
| 'withdraw'
| 'bridge';
type TransactionStatus =
| 'pending'
| 'confirmed'
| 'failed'
| 'cancelled';
分页
使用每次响应中的 cursor 来翻页浏览结果。
import { useState, useCallback } from 'react';
import { useOneClient } from '@one_deploy/sdk';
import type { Transaction, TransactionPage } from '@one_deploy/sdk';
function PaginatedHistory({ walletAddress }: { walletAddress: string }) {
const { engineClient } = useOneClient();
const [transactions, setTransactions] = useState<Transaction[]>([]);
const [nextCursor, setNextCursor] = useState<string | null>(null);
const [totalCount, setTotalCount] = useState(0);
const [loading, setLoading] = useState(false);
const loadPage = useCallback(async (cursor?: string) => {
setLoading(true);
const page: TransactionPage = await engineClient.getWalletTransactions(
walletAddress,
{
limit: 20,
cursor,
sortOrder: 'desc',
}
);
setTransactions((prev) =>
cursor ? [...prev, ...page.transactions] : page.transactions
);
setNextCursor(page.nextCursor);
setTotalCount(page.totalCount);
setLoading(false);
}, [walletAddress, engineClient]);
return (
<div>
<p>Total: {totalCount} transactions</p>
{transactions.map((tx) => (
<div key={tx.id}>
<span>{tx.type}</span>
<span>{tx.value} {tx.currency}</span>
<span>{tx.status}</span>
<span>{new Date(tx.timestamp).toLocaleDateString()}</span>
<a href={tx.explorerUrl} target="_blank" rel="noopener noreferrer">
View
</a>
</div>
))}
{nextCursor && (
<button
onClick={() => loadPage(nextCursor)}
disabled={loading}
>
{loading ? 'Loading...' : 'Load More'}
</button>
)}
</div>
);
}
按类型筛选
仅获取特定类型的交易。
import { useOneClient, CHAIN_IDS } from '@one_deploy/sdk';
function FilteredHistory() {
const { engineClient } = useOneClient();
const loadSendsOnly = async () => {
const page = await engineClient.getWalletTransactions(
'0x1234...abcd',
{ type: 'send' }
);
console.log('Sends:', page.transactions.length);
};
const loadSwapsAndBridges = async () => {
const page = await engineClient.getWalletTransactions(
'0x1234...abcd',
{ type: ['swap', 'bridge'] }
);
console.log('Swaps & bridges:', page.transactions.length);
};
const loadBaseTransactions = async () => {
const page = await engineClient.getWalletTransactions(
'0x1234...abcd',
{
chainId: CHAIN_IDS.BASE,
status: 'confirmed',
fromDate: '2025-01-01T00:00:00Z',
limit: 50,
}
);
console.log('Confirmed Base txs since 2025:', page.transactions.length);
};
return (
<div>
<button onClick={loadSendsOnly}>Sends Only</button>
<button onClick={loadSwapsAndBridges}>Swaps & Bridges</button>
<button onClick={loadBaseTransactions}>Base (2025+)</button>
</div>
);
}
getTransactionStatus
通过 ONE SDK 交易 ID 跟踪特定交易的实时状态。
import { useOneClient } from '@one_deploy/sdk';
function TransactionTracker({ txId }: { txId: string }) {
const { engineClient } = useOneClient();
const checkStatus = async () => {
const tx = await engineClient.getTransactionStatus(txId);
console.log('Status:', tx.status); // 'pending' | 'confirmed' | 'failed' | 'cancelled'
console.log('Hash:', tx.transactionHash);
console.log('Block:', tx.blockNumber);
console.log('Explorer:', tx.explorerUrl);
};
return <button onClick={checkStatus}>Check Status</button>;
}
方法签名
getTransactionStatus(txId: string): Promise<Transaction>
轮询确认
import { useOneClient } from '@one_deploy/sdk';
function useTransactionPolling() {
const { engineClient } = useOneClient();
const waitForConfirmation = async (
txId: string,
intervalMs: number = 3000,
maxAttempts: number = 20
): Promise<Transaction> => {
for (let i = 0; i < maxAttempts; i++) {
const tx = await engineClient.getTransactionStatus(txId);
if (tx.status === 'confirmed' || tx.status === 'failed') {
return tx;
}
await new Promise((resolve) => setTimeout(resolve, intervalMs));
}
throw new Error(`Transaction ${txId} did not confirm within timeout`);
};
return { waitForConfirmation };
}