List Agreements API

HTTP Request

GET /v5/pay/agreement/list

Query agreement list under merchant with pagination and filtering support.

---

Request Parameters

Parameter	Type	Required	Description
merchantId	string	Yes	Merchant ID
userId	string	No	Platform user ID (filter by user)
agreementType	string	No	Sign type: CYCLE / NON_CYCLE / SINGLE (query all if not provided)
status	string	No	Status filter: INIT / PENDING / PROCESSING / SIGNED / SUSPENDED / UNSIGNED / EXPIRED / REJECTED / FAILED / TIMEOUT
sceneCode	string	No	Scene code filter
startTime	string	No	Sign start time (ISO8601)
endTime	string	No	Sign end time (ISO8601)
pageNo	int	Yes	Page number, minimum 1
pageSize	int	Yes	Page size, range 1-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.list	array	Agreement list
result.list[].agreementNo	string	Platform agreement number
result.list[].externalAgreementNo	string	Merchant agreement number
result.list[].userId	string	Platform user ID
result.list[].merchantUserId	string	Merchant-side user ID
result.list[].agreementType	string	Sign type
result.list[].sceneCode	string	Scene code
result.list[].status	string	Agreement status
result.list[].signTime	string	Sign time
result.list[].validTime	string	Validity period

---

Request Examples

List All Active Agreements

GET /v5/pay/agreement/list?merchantId=M123456789&status=SIGNED&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 Agreements for Specific User

GET /v5/pay/agreement/list?merchantId=M123456789&userId=U_123456789&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 Agreements by Scene and Time Range

GET /v5/pay/agreement/list?merchantId=M123456789&sceneCode=SUBSCRIPTION&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}

---

Response Example

{
  "retCode": 20000,
  "retMsg": "Success",
  "result": {
    "total": 150,
    "pageNo": 1,
    "pageSize": 20,
    "list": [
      {
        "agreementNo": "AGR202601070001",
        "externalAgreementNo": "MERCHANT_AGR_001",
        "userId": "U_123456789",
        "merchantUserId": "merchant_user_123",
        "agreementType": "CYCLE",
        "sceneCode": "SUBSCRIPTION",
        "status": "SIGNED",
        "signTime": "2026-01-07T10:30:00Z",
        "validTime": "2027-01-07T10:30:00Z"
      },
      {
        "agreementNo": "AGR202601060001",
        "externalAgreementNo": "MERCHANT_AGR_002",
        "userId": "U_987654321",
        "merchantUserId": "merchant_user_456",
        "agreementType": "CYCLE",
        "sceneCode": "TAXI",
        "status": "SIGNED",
        "signTime": "2026-01-06T15:20:00Z",
        "validTime": "2027-01-06T15:20:00Z"
      }
    ]
  }
}

---

Notes

• Use pagination for large result sets to avoid timeout
• Combine filters for efficient querying
• signTime is used for time range filtering