Query Agreement API

HTTP Request

GET /v5/bybitpay/agreement/query

Query single agreement status and details.

---

Request Parameters

Parameter	Type	Required	Description
merchant_id	string	Yes	Merchant ID
user_id	string	Yes	Platform user ID
agreement_type	string	Yes	Sign type: CYCLE / NON_CYCLE / SINGLE
agreement_no	string	Either	Platform agreement number
external_agreement_no	string	Either	Merchant agreement number

info

Either agreement_no or external_agreement_no must be provided.

---

Response Parameters

Parameter	Type	Description
retCode	int	Response code
retMsg	string	Response message
result	object	Response data
result.agreement_no	string	Platform agreement number
result.external_agreement_no	string	Merchant agreement number
result.user_id	string	Platform user ID
result.merchant_user_id	string	Merchant-side user ID
result.status	string	Agreement status
result.sign_time	string	Sign time
result.valid_time	string	Validity period
result.single_limit	object	Single transaction limit
result.period_limits	array	Period limits list
result.used_quota	object	Used quota

---

Request Example

GET /v5/bybitpay/agreement/query?merchant_id=M123456789&user_id=U_123456789&agreement_type=CYCLE&agreement_no=AGR202601070001 HTTP/1.1
Host: api2.bybit.com
X-BAPI-API-KEY: xxxxxxxxxxxxxxxxxx
X-BAPI-TIMESTAMP: 1736233200000
X-BAPI-SIGN: {signature}
X-BAPI-RECV-WINDOW: 5000

---

Response Example

{
  "retCode": 20000,
  "retMsg": "Success",
  "result": {
    "agreement_no": "AGR202601070001",
    "external_agreement_no": "MERCHANT_AGR_001",
    "user_id": "U_123456789",
    "merchant_user_id": "merchant_user_123",
    "status": "SIGNED",
    "sign_time": "2026-01-07T10:30:00Z",
    "valid_time": "2027-01-07T10:30:00Z",
    "single_limit": {
      "amount": "100000",
      "currency": "USDT",
      "currency_type": "CRYPTO",
      "chain": "TRC20"
    },
    "period_limits": [
      {
        "period_type": "DAY",
        "amount": "500000",
        "currency": "USDT",
        "currency_type": "CRYPTO",
        "chain": "TRC20"
      },
      {
        "period_type": "MONTH",
        "amount": "5000000",
        "currency": "USDT",
        "currency_type": "CRYPTO",
        "chain": "TRC20"
      }
    ],
    "used_quota": {
      "day_used": "50000",
      "month_used": "150000",
      "currency": "USDT",
      "currency_type": "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
FAILED	Sign failed	No
TIMEOUT	Sign link expired	No

---

Notes

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