注册商户

GET · /api/v1/wallet/transaction/status

查询链上交易状态

按 chainCode + txHash 向链上节点实时查询交易状态、确认数及出块时间。适合自助核查某笔 tx 是否成功上链。

实时查询，非快照

本接口直接调用对应链的 RPC 节点查询，返回当前最新确认状态。 对于刚广播的交易，status 可能短暂为 PENDING， 请按需轮询（建议间隔 ≥ 5 秒）。
GET/api/v1/wallet/transaction/status HMAC

Header 参数

X-Api-Key
string required
应用 apiKey。沙箱前缀 pk_test_，正式 pk_live_。
例： pk_test_4f9d8ab1c0e74...
X-Timestamp
integer (UNIX 毫秒) required
请求发起时刻的 UNIX 毫秒时间戳（13 位整数）。与服务端时差不能超过 ±300000ms（5 分钟）。
例： 1746450000000
X-Nonce
string required
本次请求的随机串，建议 UUID v4 或 16 字节 hex。同一 (apiKey, nonce) 在 10 分钟窗口内不可重复。
例： 8e3a1c2f7b6d4a90
X-Signature
string required
HMAC-SHA256 签名（小写 hex，64 字符）。算法：HMAC(secret, METHOD + "\n" + PATH + "\n" + ts + "\n" + nonce + "\n" + SHA256(body))。详见 鉴权章节。
例： 6e4a8c1f...（64 字符）

Query 参数

chainCode
string required
公链 code，必须是该应用已开通的公链。
例： ETH
txHash
string required
链上交易哈希（含 0x 前缀，EVM 系；其他链按原始格式传）。
例： 0x9ab8c4f7e2d1a3b0...

请求示例

# 签名算法（stringToSign / 4 个 header）见 /docs/api/auth
API_KEY=pk_live_xxx
SECRET=sk_live_xxx
METHOD=GET
REQ_PATH=/api/v1/wallet/transaction/status
QUERY="chainCode=ETH&txHash=0x9ab8c4f7e2d1a3b0..."
TS=$(( $(date +%s) * 1000 ))
NONCE=$(uuidgen | tr -d '-' | tr '[:upper:]' '[:lower:]')
BODY_SHA=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
# 签名 PATH 不含 query string
SIG=$(printf "%s\n%s\n%s\n%s\n%s" "$METHOD" "$REQ_PATH" "$TS" "$NONCE" "$BODY_SHA" \
  | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}')

curl "https://api.pqpa.com$REQ_PATH?$QUERY" \
  -H "X-Api-Key:    $API_KEY" \
  -H "X-Timestamp:  $TS" \
  -H "X-Nonce:      $NONCE" \
  -H "X-Signature:  $SIG"

响应

Response
200OK
{
  "code": 0,
  "data": {
    "chainCode": "ETH",
    "txHash": "0x9ab8c4f7e2d1a3b0...",
    "exists": true,
    "onChain": true,
    "success": true,
    "blockHeight": 19283746,
    "confirmations": 32,
    "blockTime": "2026-05-05T12:34:56",
    "status": "SUCCESS",
    "rawError": null
  },
  "msg": ""
}

data 字段说明

chainCode
string required
公链 code。
例： ETH
txHash
string required
交易哈希，原样回显。
exists
boolean required
节点是否找到该交易（false 时其余状态字段均为默认值）。
例： true
onChain
boolean required
是否已被打包上链。
例： true
success
boolean required
链上执行是否成功（仅 onChain=true 时有意义）。
例： true
blockHeight
integer | null required
所在块高；交易尚未上链时为 null。
例： 19283746
confirmations
integer required
当前确认数；exists=false 时为 0。
例： 32
blockTime
string | null required
出块时间（LocalDateTime，格式 yyyy-MM-ddTHH:mm:ss）；未上链时为 null。
例： "2026-05-05T12:34:56"
status
string required
交易状态枚举，见下方说明。
例： SUCCESS
取值：NOT_FOUNDPENDINGSUCCESSFAILEDERROR
rawError
string | null required
链上或 RPC 返回的原始错误信息；status=ERROR / FAILED 时可能有值，其余为 null。

status 枚举说明

值含义
NOT_FOUND节点未找到该交易（可能还未广播或 hash 有误）。
PENDING已在节点内存池中，尚未被打包进区块。
SUCCESS已上链且链上执行成功。
FAILED已上链但链上执行失败（如合约 revert），rawError 含原因。
ERRORRPC 查询过程本身出错，非交易本身状态问题，rawError 含详情。

下一步