Query Balance

Used to query the available balance of the application to which the current API Key belongs. The queried application is determined by the API Key, and there is no need to pass the application ID in the request.

Request URL

GET https://otp.api.engagelab.cc/v1/balance

Authentication

Please refer to Authentication to learn how to perform API authentication.

Request Example

Request Header

GET /v1/balance HTTP/1.1 Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

              
              GET /v1/balance HTTP/1.1
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

This code block in the floating window

Request Parameters

No request parameters.

Response Parameters

Success Response

Field	Type	Option	Description
currency	String	Required	Settlement currency, currently fixed to `USD` (US Dollars)
balance	String	Required	Normal balance (obtained through recharge)
gift_balance	String	Required	Gift balance (obtained through activities/gifts, may have an expiration date, not counted after expiration)
total_balance	String	Required	Total balance, equal to `balance` + `gift_balance`

{ "currency": "USD", "balance": "123.4500", "gift_balance": "1.0000", "total_balance": "124.4500" }

              
              {
    "currency": "USD",
    "balance": "123.4500",
    "gift_balance": "1.0000",
    "total_balance": "124.4500"
}

This code block in the floating window

Field Description

Amounts are all string decimals, retaining 4 decimal places. This design is to avoid precision errors during transmission and parsing of floating-point numbers. Please use high-precision decimal types (such as BigDecimal / Decimal in various languages) for parsing, and do not calculate directly as floating-point numbers.
Currency: Currently, all applications are settled in US Dollars (USD).
Balance may be negative: For applications that have activated an overdraft quota, the balance / total_balance may return a negative value (such as "-12.3400") after overdraft, indicating that it is in arrears. Please recharge in time.
total_balance is consistently calculated by the server at the same moment and can be directly used for display and reconciliation.

Failure Response

The HTTP status code is 4xx or 5xx, and the response body contains the following fields:

Field	Type	Option	Description
code	int	Required	Error code, please refer to the error code description for details
message	String	Required	Error details

{ "code": 2001, "message": "invalid token" }

              
              {
    "code": 2001,
    "message": "invalid token"
}

This code block in the floating window

Error Codes

Error Code	http code	Description
1000	500	Internal error, please try again later
2001	401	Authentication failed, incorrect token carried
2002	401	Authentication failed, token has expired or been disabled
2002	403	Application unavailable (deleted or disabled)