如何一键查询钱包全量交易记录

在去中心化日益普及的今天，钱包交易记录查询 已不仅仅是开发者的“技术需求”，更是普通用户做资产审计、报税、甚至防风险的基本功。无论你是持有以太坊 NFT 还是比特币原生资产，如果你能快速、准确地拉取某地址的全部交易流水，就能真正做到对自己的链上资产“一目了然”。本篇手把手教你用一条命令，在 多链环境 下获取钱包全量交易记录，并附带示例代码、常见场景与实战技巧，助你 5 分钟上手。

一、为什么必须掌握交易流水调取

资产管理：投资者需要在多个链与多个地址之间切换，统一交易台账可避免资金混淆。
税务申报：多国税务部门已明确要求提供链上交易明细，包括哈希、时间戳、对应法币价值。
风险控制：追踪可疑地址或 DeFi 协议交互历史，及早发现恶意授权。
产品构建：DApp 通过为用户呈现“交互时间线”，可有效提升留存率与信任度。

二、核心接口：tatum.address.getTransactions

关键词： 钱包交易记录、以太坊交易历史、比特币交易列表、链上数据接口

功能亮点	一句话描述
跨链支持	同一套代码即可覆盖 ETH、BTC、Polygon、BSC 等 40+ 公链
无需自建节点	直接调用 HTTP API，免去高昂的节点维护费用
分页 & 过滤	可按地址、交易方向、时间区间、Token 合约精确定位数据

接口结构概览：

interface GetAddressTransactionsQuery {
  address: string
  transactionTypes?: ('fungible' | 'nft' | 'multitoken' | 'native')[]
  transactionDirection?: 'incoming' | 'outgoing'
  fromBlock?: number
  toBlock?: number
  pageSize?: number
  page?: number
  tokenAddress?: string
}

三、以太坊示例：查询测试网地址在 10 分钟内完成

yarn add @tatumio/tatum

异步 ES6 版本：

import { TatumSDK, Network } from '@tatumio/tatum';

(async () => {
  const tatum = await TatumSDK.init({ network: Network.ETHEREUM });
  const txs   = await tatum.address.getTransactions({
    address: '0x514d547c8ac8ccbec29b5144810454bd7d3625ca', // 换成你的地址
    pageSize: 50,        // 默认 10
    fromBlock: 3300000,  // 可选，区块起止高度
  });
  console.table(txs.data);  // 浏览器控制台直接表格化展示
})();

👉 仅用 15 行代码跑通跨链钱包分析，立刻尝鲜 >>>

CommonJS 写法也同步奉上：

const { TatumSDK, Network } = require('@tatumio/tatum');
(async () => {
  try {
    const tatum = await TatumSDK.init({ network: Network.ETHEREUM });
    const { data } = await tatum.address.getTransactions({
      address: '0x514d547c8ac8ccbec29b5144810454bd7d3625ca'
    });
    console.log(data);
  } catch (error) {
    console.error('查询失败：', error.message);
  }
})();

四、比特币 UTXO 网络：代码零改动

对于比特币主网或测试网，仅需把 Network.BITCOIN 改为 Network.BITCOIN_TESTNET，其他参数保持一致即可，大幅减轻跨链开发负担：

const tatum = await TatumSDK.init({ network: Network.BITCOIN_TESTNET });
const txs   = await tatum.address.getTransactions({
  address: 'tb1qrd9jz8ksy3qqm400vt296udlvk89z96p443mv0'
});

五、字段速查：如何阅读返回格式

拿到的每条记录遵循如下 AddressTransaction 结构：

chain ‑ 主网名称
blockNumber ‑ 所在区块高度
hash ‑ 交易哈希
transactionType ‑ incoming / outgoing / zero-transfer
amount ‑ 字符串形式，负值代表转出，正值代表转入
timestamp ‑ UTC 毫秒时间戳
counterAddress ‑ 资金对手地址，比特币可能缺失
tokenAddress & tokenId ‑ ERC-20/ERC-721 时填充合约 & TokenID

示例返回片段（以太坊）：

{
  "chain": "ethereum-sepolia",
  "amount": "1",
  "hash": "0xf4ef...7058",
  "timestamp": 1681982316000,
  "transactionType": "incoming",
  "counterAddress": "0x39...391"
}

六、实战进阶：打造个人链上记账本

1. 自动导出 CSV 报表

用 page 参数遍历所有分页，把每页结果合并后通过 fast-csv 模块写入 CSV，即可生成“日期-收入-支出-备注”四列表格，直接导入 Excel 查看：

const { createWriteStream } = require('fs');
const fastCsv = require('fast-csv');
const ws = createWriteStream('eth-transactions.csv');
fastCsv.write(flattenData, { headers: true }).pipe(ws);

2. 拆分红利计算 DeFi LP 手续费

解析 tokenAddress 字段，筛选涉及 特定流动性池合约 的记录，按 amount 累加即可获得账户在该池赚到的手续费总额。

3. 风险地址预警

将返回对象的 counterAddress 与已知黑名单比对，首次出现高危对手方时立刻推送邮件 / 钉钉 / 飞书通知，预防授权钓鱼。

七、常见问题解答（FAQ）

Q1：UTXO 链（如 BTC / DOGE）返回结果为何缺少 counterAddress？
A：UTXO 一个交易可能有多个输入 & 输出，库目前只选取与查询地址相关的 vout 条目，因此无法精准定位唯一对手方。

Q2：我只想查 NFT 转账，如何过滤？
A：在 transactionTypes 传入 ['nft'] 即可隐藏 ERC-20 或原生币转账，减轻接口负载。

Q3：为何某些链返回最早的记录缺失？
A：部分测试网存在区块链回滚，节点高度回退后早期数据被废弃；使用 fromBlock 并指向近 1 年区块即可规避空值。

Q4：每次最多能拉多少条？
A：目前 pageSize 上限为 50，大批量需结合 page 连续翻页；官方已在 2024 年至 2025 年逐步开放 500 行选项。

Q5：商用是否收费？
A：开发计划默认每日免费 600 次调用；超过后需充值“高速套餐”。建议在生产环境读写分离缓存，降低频次。