List Transactions API

HTTP Request

GET /v5/pay/agreement/transaction/list

Query deduction transaction and refund record lists under an agreement with pagination and time range filtering support.

---

Request Parameters

Parameter	Type	Required	Description
merchantId	string	Yes	Merchant ID
userId	string	Yes	Platform user ID
agreementType	string	Yes	Sign type: CYCLE / NON_CYCLE / SINGLE
agreementNo	string	Yes	Platform agreement number
recordType	string	No	Record type: PAY (default) / REFUND
status	string	No	Status filter: SUCCESS / FAILED / PROCESSING
startTime	string	No	Start time (ISO8601)
endTime	string	No	End time (ISO8601)
pageNo	int	No	Page number, default 1
pageSize	int	No	Page size, default 20, max 100

---

Response Parameters

Parameter	Type	Description
retCode	int	Response code
retMsg	string	Response message
result	object	Response data
result.total	int	Total record count
result.pageNo	int	Current page number
result.pageSize	int	Page size
result.tradeList	array	Deduction transaction entries in the current page
result.tradeList[].tradeNo	string	Platform trade number
result.tradeList[].outTradeNo	string	Merchant order number
result.tradeList[].status	string	Transaction status: PROCESSING / SUCCESS / FAILED / TIMEOUT
result.tradeList[].amount	object	Merchant requested amount
result.tradeList[].amount.total	string	Amount (minimum unit)
result.tradeList[].amount.currency	string	Currency code
result.tradeList[].amount.currencyType	string	Currency type: FIAT / CRYPTO
result.tradeList[].amount.chain	string	Chain network
result.tradeList[].cryptoPayment	object	Defined by the response schema but not populated by the current list implementation
result.tradeList[].payTime	string	Payment time
result.tradeList[].refundAmount	object	Defined by the response schema but not populated by the current list implementation
result.refundList	array	Refund entries in the current page
result.refundList[].refundNo	string	Platform refund number
result.refundList[].outRefundNo	string	Merchant refund number
result.refundList[].tradeNo	string	Original trade number
result.refundList[].status	string	Refund status: PROCESSING / SUCCESS / FAILED / TIMEOUT
result.refundList[].refundAmount	object	Refund amount
result.refundList[].refundAmount.total	string	Refund amount (minimum unit)
result.refundList[].refundAmount.currency	string	Currency code
result.refundList[].refundAmount.currencyType	string	Currency type: FIAT / CRYPTO
result.refundList[].refundTime	string	Refund success time
result.refundList[].failureReason	string	Failure reason (returned on failure)

---

Request Examples

信息

The examples retain recordType for request compatibility. The current list implementation does not use this parameter as a filter, so it does not guarantee that only one record type is returned.

List Successful Transactions

GET /v5/pay/agreement/transaction/list?merchantId=M123456789&userId=U_123456789&agreementType=CYCLE&agreementNo=AGR202601070001&recordType=PAY&status=SUCCESS&pageNo=1&pageSize=20 HTTP/1.1
Host: api.bybit.com
X-Request-Id: 550e8400-e29b-41d4-a716-446655440000
X-Timestamp: 1736233200000
X-Signature: {signature}
Authorization: Bearer {access_token}

List All Transactions with Time Range

GET /v5/pay/agreement/transaction/list?merchantId=M123456789&userId=U_123456789&agreementType=CYCLE&agreementNo=AGR202601070001&recordType=PAY&startTime=2026-01-01T00:00:00Z&endTime=2026-01-31T23:59:59Z&pageNo=1&pageSize=50 HTTP/1.1
Host: api.bybit.com
X-Request-Id: 550e8400-e29b-41d4-a716-446655440000
X-Timestamp: 1736233200000
X-Signature: {signature}
Authorization: Bearer {access_token}

List Refund Records

GET /v5/pay/agreement/transaction/list?merchantId=M123456789&userId=U_123456789&agreementType=CYCLE&agreementNo=AGR202601070001&recordType=REFUND&pageNo=1&pageSize=20 HTTP/1.1
Host: api.bybit.com
X-Request-Id: 550e8400-e29b-41d4-a716-446655440000
X-Timestamp: 1736233200000
X-Signature: {signature}
Authorization: Bearer {access_token}

---

Response Examples

Deduction Transaction List

{
  "retCode": 20000,
  "retMsg": "Success",
  "result": {
    "total": 50,
    "pageNo": 1,
    "pageSize": 20,
    "tradeList": [
      {
        "tradeNo": "PAY202601070001",
        "outTradeNo": "ORDER20260107001",
        "status": "SUCCESS",
        "amount": {
          "total": "2350",
          "currency": "USDT",
          "currencyType": "CRYPTO",
          "chain": "TRC20"
        },
        "payTime": "2026-01-07T10:30:00Z"
      }
    ],
    "refundList": []
  }
}

Refund Record List

{
  "retCode": 20000,
  "retMsg": "Success",
  "result": {
    "total": 10,
    "pageNo": 1,
    "pageSize": 20,
    "tradeList": [],
    "refundList": [
      {
        "refundNo": "RF202601070001",
        "outRefundNo": "REFUND20260107001",
        "tradeNo": "PAY202601070001",
        "status": "SUCCESS",
        "refundAmount": {
          "total": "2350",
          "currency": "USDT",
          "currencyType": "CRYPTO"
        },
        "refundTime": "2026-01-07T11:30:00Z",
        "failureReason": ""
      }
    ]
  }
}

---

Notes

• Use pagination for large result sets
• Combine status and time range filters for efficient querying
• The response includes both tradeList and refundList; either list can be empty depending on the current page contents