在区块链世界，每一笔交易都被永久记录在分布式账本上。无论是个人用户追踪资金流向，还是开发者构建数据分析工具，掌握如何高效查询特定地址的交易历史都是一项核心技能。本文将深入解析通过地址维度查询交易历史的方法，帮助您快速获取并按时间降序排列的完整链上活动记录。
核心查询接口与路径
查询交易历史的核心 API 接口采用 GET 请求方式，其路径为：
https://web3.okx.com/api/v5/wallet/post-transaction/transactions-by-address此接口专为按地址检索链上交易而设计，返回结果默认按时间倒序排列，确保您最先看到最新的交易活动。
主要请求参数详解
向接口发送请求时，您需要提供一系列参数来精确限定查询范围。
必需参数
- address: 需要查询交易历史的区块链地址。这是唯一必须提供的参数。
可选参数
- chainIndex: 目标链的唯一标识符。例如，ETH 主网的链索引为 3。不提供时，将在其支持的多个链上查询该地址。
- tokenAddress: 代币合约地址。用于筛选与特定代币相关的交易。留空则查询主网币交易；不传入此参数则查询所有交易。
- begin: 查询的起始时间（Unix 时间戳，毫秒单位）。仅返回此时间点之后的交易记录。
- end: 查询的结束时间（Unix 时间戳，毫秒单位）。仅返回此时间点之前的交易记录。若
begin与end均未提供，默认查询当前时间之前的所有记录。 - limit: 单次返回的记录条数，默认返回最近20条。注意：单链查询最多支持20条，多链查询最多支持100条。
- cursor: 游标，用于分页获取大量数据。
合理组合这些参数，您可以实现高度定制化的交易历史查询，👉查看实时链上数据工具以获得更直观的体验。
响应结果解析
API 调用成功后，将返回一个结构化的 JSON 对象，主要包含以下信息：
交易列表 (transactionList)
这是一个对象数组，每一项代表一笔具体的交易，包含极其丰富的链上数据：
- chainIndex: 该笔交易发生的链 ID。
- txHash: 交易的哈希值，是交易在区块链上的唯一标识。
iType: 交易类型。主要分为：
0: 外部主网币转账1: 合约内部主网币转账2: 代币转账
- methodId: 调用的合约函数标识。
- txTime: 交易发生的时间（Unix 时间戳，毫秒单位）。
- from: 交易输入方数组，包含发送地址和金额。
- to: 交易输出方数组，包含接收地址和金额。
- tokenAddress: 涉及代币的合约地址。
- amount & symbol: 交易金额及其对应的货币符号。
- txFee: 该笔交易支付的手续费。
- txStatus: 交易状态：
success(成功),fail(失败),pending(待处理)。 - hitBlacklist: 布尔值，标识相关地址是否涉及黑名单。
游标 (cursor)
当一次查询无法返回全部结果时，此游标用于获取下一页数据，实现完整的历史记录遍历。
常见问题 (FAQ)
Q1: 如何只查询某一条特定链（如以太坊）上的交易？
A: 在请求参数中指定 chainIndex 即可。例如，查询以太坊主网则传入 3，系统将只返回该链上的交易记录。
Q2: 能否查询与某个特定代币（如USDT）的所有交易？
A: 可以。您需要找到该代币的合约地址，并将其作为 tokenAddress 参数的值传入，查询结果将自动过滤，只显示与该代币相关的转账和交易。
Q3: 单次最多能查询多少条交易记录？
A: 这取决于查询模式。如果指定了单条链(chainIndex)，最多返回20条记录；如果不指定链（进行多链查询），最多可返回100条记录。如需更多历史数据，请使用 cursor 参数进行分页查询。
Q4: 交易状态中的 pending 是什么意思？
A: pending 状态表示该笔交易已被广播到网络，但尚未被矿工（或验证者）打包进区块，因此交易尚未最终确认。它可能成功，也可能因 gas 不足等原因失败。
Q5: 查询到的黑名单标签是什么意思？
A: 这是一个已弃用(Deprecated)的字段。当前更可靠的指标是 hitBlacklist 字段。若为 true，表明该交易涉及的某个地址被识别为风险地址（如 phishing 钓鱼地址、存在漏洞的合约等），处理此类资产时需格外谨慎。
通过熟练掌握上述接口和参数，您将能高效地探索区块链上的数据海洋，为投资分析、安全审计或应用开发提供坚实的数据支撑。