Query Agreement API

HTTP Request

GET /v5/pay/agreement/query

Query single agreement status and details.

---

Request Parameters

Parameter	Type	Required	Description
merchantId	string	Yes	Merchant ID
agreementNo	string	Either	Platform agreement number
externalAgreementNo	string	Either	Merchant agreement number

info

Either agreementNo or externalAgreementNo must be provided.

---

Response Parameters

Parameter	Type	Description
retCode	int	Response code
retMsg	string	Response message
result	object	Response data
result.agreementNo	string	Platform agreement number
result.externalAgreementNo	string	Merchant agreement number
result.userId	string	Platform user ID
result.merchantUserId	string	Merchant-side user ID
result.status	string	Status: INIT/PENDING/SIGNED/SUSPENDED/UNSIGNED/EXPIRED/REJECTED/FAILED/TIMEOUT
result.signTime	string	Sign time
result.validTime	string	Validity period
result.singleLimit	object	Single transaction limit
result.periodLimits	array	Period limits list
result.usedQuota	object	Used quota

---

Request Example

GET /v5/pay/agreement/query?merchantId=M123456789&agreementNo=AGR202601070001 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": {
    "agreementNo": "AGR202601070001",
    "externalAgreementNo": "MERCHANT_AGR_001",
    "userId": "U_123456789",
    "merchantUserId": "merchant_user_123",
    "status": "SIGNED",
    "signTime": "2026-01-07T10:30:00Z",
    "validTime": "2027-01-07T10:30:00Z",
    "singleLimit": {
      "amount": "100000",
      "currency": "USDT",
      "currencyType": "CRYPTO",
      "chain": "TRC20"
    },
    "periodLimits": [
      {
        "periodType": "DAY",
        "amount": "500000",
        "currency": "USDT",
        "currencyType": "CRYPTO",
        "chain": "TRC20"
      },
      {
        "periodType": "MONTH",
        "amount": "5000000",
        "currency": "USDT",
        "currencyType": "CRYPTO",
        "chain": "TRC20"
      }
    ],
    "usedQuota": {
      "dayUsed": "50000",
      "monthUsed": "150000",
      "currency": "USDT",
      "currencyType": "CRYPTO"
    }
  }
}

---

Agreement Status

Status	Description	Deduction Allowed
INIT	Waiting for user scan	No
PENDING	User scanned, verification in progress	No
SIGNED	Agreement active	Yes
SUSPENDED	Temporarily paused	No
UNSIGNED	Terminated	No
EXPIRED	Expired	No
REJECTED	User actively canceled signing	No
FAILED	Sign failed	No
TIMEOUT	Sign link expired	No

---

Notes

• Use this API to check agreement status before deduction
• usedQuota shows current period usage (resets based on period type)
• All states support query operation