Open API

This is the OpenAPI Specification for the Coinq Pay API. Each request must be authenticated using Ed25519 signature. Any request that doesn't include authentication headers will return an error.

Coin

Get coin list.

Get the supported coin list.

GET https://api.coinqpay.com/api/v1/supported_coins

Response Body

Name	Type	Description
coin	string	The coin unique name
chain	string	The chain code of the coin
display_code	string	The display code of the coin, not unique
contract_address	string	The contract address of the coin
decimal	int	The decimal of the coin
can_pay	bool	The coin can be used to pay
minimum_pay_amount	string	The minimum pay amount of the coin
withdrawal_fixed_fee	string	The withdrawal fixed fee
withdrawal_percentage_fee	string	The withdrawal percentage fee (e.g., 1.5 means 1.5%)

Response Example

200 Get coin list success

{
    "success": true,
    "result": [
        {
            "coin": "BSC_USDC",
            "chain": "BSC",
            "display_code": "USDC",
            "contract_address": "0x64544969ed7ebf5f083679233325356ebe738930",
            "decimal": 18,
            "can_pay": true,
            "minimum_pay_amount": "1",
            "withdrawal_fixed_fee": "0.1",
            "withdrawal_percentage_fee": "0"
        },
        {
            "coin": "ETH",
            "chain": "ETH",
            "display_code": "ETH",
            "contract_address": "",
            "decimal": 18,
            "can_pay": true,
            "minimum_pay_amount": "0.001",
            "withdrawal_fixed_fee": "4.1",
            "withdrawal_percentage_fee": "0.1"
        }
    ]
}

500 Internal Server Error

{
    "success": false,
    "error_code": 1000,
    "error_message": "Unknown internal error ",
    "error_id": "520e9222cf1a44e893b15a9695c5e3e3",
    "error_description": "Unknown internal error "
}

Get coin price.

Get the coin price with the currency.

GET https://api.coinqpay.com/api/v1/coin_price

Query Parameters (URL Query)

Name	Type	Description
currency*	string	The currency code, only support USD HKD
coin	string	The coin unique name, if not set, return all coins price

Response Body

Name	Type	Description
coin	string	The coin unique name in coinq pay
currency	string	The currency code
price	string	The coin price in the currency
update_time	int	The price update UNIX seconds timestamp

Response Example

200 Get coin price success

{
    "success": true,
    "result": [
        {
            "coin": "ETH",
            "currency": "USD",
            "price": "3111.5",
            "update_time": 1720102180
        },
        {
            "coin": "ETH_USDT",
            "currency": "USD",  
            "price": "0.998236",
            "update_time": 1720102180
        },
        {
            "coin": "ETH_USDC",
            "currency": "USD",
            "price": "0.998646",
            "update_time": 1720102180
        }
    ]
}

401 Permission denied

{
    "success": false,
    "error_code": 12003,
    "error_message": "Permission deny",
    "error_id": "b42316d1c5e34af9ba5f172c445b7a4e",
    "error_description": "No such key:f773ebcd9b2ead7d1be98c45e3158aa7652c19dc6f5fa1c70ed78d4b4ef9e2f8"
}

Get coin balance.

Query the balance of the coin.

GET https://api.coinqpay.com/api/v1/coin_balance

Query Parameters (URL Query)

Name	Type	Description
coin	string	The coin unique name, if not set, return all coins balance

Response Body

Name	Type	Description
coin	string	The coin unique name in coinq pay
balance	string	The available balance of the coin

Response Example

200 Get balance success

{
    "success": true,
    "result":
    [
        {
            "coin": "ETH",
            "balance": "0.1"
        },
        {
            "coin": "BNB",
            "balance": "10"
        },
        {
            "coin": "ETH_USDT",
            "balance": "102"
        }
    ]
}

Pay order

Create pay order.

POST https://api.coinqpay.com/api/v1/pay_order

Creates a new pay order.

Request Body (application/json)

Name	Type	Description
coin*	string	The coin unique name in coinq pay, length 1-50
order_id*	string	The id of the merchant generated order, length 1-64, unique
amount*	string	The payment amount, must be greater than 0

Response Body

Name	Type	Description
payment_id	string	The unique payment id in coinq pay
order_id	string	The id of the merchant generated order
coin	string	The coin unique name in coinq pay
chain	string	The chain code of the coin
amount	string	The original payment amount
address	string	The payment address
expire_time	int	The payment expire UNIX seconds timestamp
create_time	int	The payment create UNIX seconds timestamp

Response Example

200 Pay order successfully created

{
    "success": true,
    "result": {
        "payment_id": "1808862046989713408",
        "order_id": "OR00000001",
        "coin": "ETH",
        "chain": "ETH",
        "amount": "0.001",
        "address": "0xb9a78dd2bc989cff715e1d8d95bb3474b61aeb9c",
        "expire_time": 1720102193,
        "create_time": 1720101293,
    }
}

400 Bad Request

{
    "success": false,
    "error_code": 1003,
    "error_message": "Unexpected Request",
    "error_id": "badf9c805cd04ca59e75fd5bd284885d",
    "error_description": "order_id too long"
}

Query pay order.

Query the created pay order by order id.

GET https://api.coinqpay.com/api/v1/pay_order

Query Parameters (URL Query)

Name	Type	Description
order_id*	string	The id of the merchant generated order, length 1-64, unique

Response Body

Name	Type	Description
payment_id	string	The unique payment id in coinq pay
order_id	string	The id of the merchant generated order
coin	string	The coin unique name in coinq pay
chain	string	The chain code of the coin
original_amount	string	The original payment amount, float string
pay_amount	string	The actual payment amount, float string, null if not paid yet
address	string	The payment address
tx_hash	string	The transaction hash
status	int	The payment status, 1: unpaid, 2: pending, 3: paid success, 4: paid failed, 5: expired, 6: exception
expire_time	int	The payment expire UNIX seconds timestamp
create_time	int	The payment create UNIX seconds timestamp
success_time	int	The payment success UNIX seconds timestamp, 0 if not success yet

pay_amount: The actual payment amount, may be different from the original amount due to the paid status is exception. You should check the status to determine the payment status.

Response Example

200 Query success

{
    "success": true,
    "result": {
        "payment_id": "1808862986631249920",
        "order_id": "OR00000002",
        "coin": "TRON_USDT",
        "chain": "TRON",
        "original_amount": "10",
        "pay_amount": null,
        "address": "TEELyKT4XCVZAcGujYaKm7F9uHp2fFipRH",
        "tx_hash": "20c0469e418bc0b7b26396fcac4cc3e3b471c0f2f336f168eaf3af7f169f9f72",
        "status": 1,
        "expire_time": 1720102418000,
        "create_time": 1720101518000,
        "success_time": 0
    }
}

405 Method Not Allowed

{
    "success": false,
    "error_code": 1002,
    "error_message": "Unexpected Request ",
    "error_id": "7192a1f4265441f9a5c8de0f6a385e5f",
    "error_description": "Request method 'DELETE' is not supported,use [GET, POST]"
}

Pay order webhook.

The webhook URL is used to notify the merchant when the payment status changes. Merchants can configure the webhook URL in the merchant administration web interface.

The webhook uses the POST method, and the request body is a JSON string. The content of the request body matches the response body of the "Query Pay Order" API result.

The webhook response must return an HTTP status code of 200 with the response body containing the string OK. If the response does not return 200 OK, the system will retry the webhook up to 20 times, with each retry occurring at 60-second intervals. If all retry attempts fail, the webhook notification will be marked as unsuccessful. In such cases, merchants can manually initiate an additional retry via the merchant administration web interface.

Request Body (application/json) Example

{
    "payment_id": "1809047750516539392",
    "order_id": "XET00000205",
    "coin": "ETH",
    "chain": "ETH",
    "original_amount": "0.01"
    "pay_amount": "0.01",
    "address": "0xb9a78dd2bc989cff715e1d8d95bb3474b61aeb9c",
    "tx_hash": "0xe3847ba9b6907157f431cd6d2cd37096acc1024b2ecf347a1ea32a9b5d1d0802",
    "status": 3,
    "expire_time": 1720146469,
    "create_time": 1720145569,
    "success_time": 1720150983,
}

Security Tips: Don't trust the webhook request, you should check the payment status in the query pay order API.

Withdrawal.

Create withdrawal

Withdraw the coin to the bind address. You must bind address in the merchant administration web interface before withdrawal.

POST https://api.coinqpay.com/api/v1/withdraw

Request Body (application/json)

Name	Type	Description
coin*	string	The coin unique name in coinq pay, length 1-50
amount*	string	The withdrawal amount, must be greater than 0

Response Body

Name	Type	Description
id	string	The unique withdrawal id in coinq pay
coin	string	The coin unique name in coinq pay
withdraw_amount	string	The withdrawal amount
fee	string	The withdrawal fee
actual_amount	string	The actual withdrawal amount
address	string	The withdrawal address
status	int	The withdrawal status, 1: wait approve
create_time	int	The withdrawal create UNIX seconds timestamp

Response Example

200 Withdrawal success

{
    "success": true,
    "result":
    {
        "id": "1816745214862295040",
        "coin": "TRON_USDT",
        "withdraw_amount": "5",
        "fee": "0.1049",
        "actual_amount": "4.8951",
        "address": "TDD1DYWkAr37thmRjaZntxcjs7tgwUjcd1",
        "status": 1,
        "create_time": 1721980787
    }
}

400 Bad Request

{
    "success": false,
    "error_code": 12015,
    "error_message": "Address does not exist",
    "error_id": "9cbb9b2cfe8c46b19f5486ae9bcc27e5",
    "error_description": "Address does not exist"
}

Create payout

Create payout withdraw to the address.

POST https://api.coinqpay.com/api/v1/payout

Request Body (application/json)

Name	Type	Description
coin*	string	The coin unique name in coinq pay, length 1-50
address*	string	The payout withdrawal address
amount*	string	The withdrawal amount, must be greater than 0

Response Body

Name	Type	Description
id	string	The unique withdrawal id in coinq pay
coin	string	The coin unique name in coinq pay
withdraw_amount	string	The withdrawal amount
fee	string	The withdrawal fee
actual_amount	string	The actual withdrawal amount
address	string	The payout withdrawal address
status	int	The withdrawal status, 1: wait approve
create_time	int	The withdrawal create UNIX seconds timestamp

Response Example

200 Withdrawal success

{
    "success": true,
    "result":
    {
        "id": "1816745214862295040",
        "coin": "TRON_USDT",
        "withdraw_amount": "5",
        "fee": "0.1049",
        "actual_amount": "4.8951",
        "address": "TDD1DYWkAr37thmRjaZntxcjs7tgwUjcd1",
        "status": 1,
        "create_time": 1721980787
    }
}

400 Bad Request

{
    "success": false,
    "error_code": 12012,
    "error_message": "Invalid address",
    "error_id": "f13057a15f334fc0b6ef70d479a5a4fe",
    "error_description": "Invalid address"
}

Query withdrawals.

Query the withdrawal by withdrawal id.

GET https://api.coinqpay.com/api/v1/withdraws

Query Parameters (URL Query)

Name	Type	Description
id	string	The unique withdrawal id in coinq pay, length 1-20, if not set, return all withdrawals

Response Body

Name	Type	Description
id	string	The unique withdrawal id in coinq pay
coin	string	The coin unique name in coinq pay
withdraw_amount	string	The withdrawal amount
fee	string	The withdrawal fee
actual_amount	string	The actual withdrawal amount
address	string	The withdrawal address
tx_hash	string	The transaction hash
status	int	The withdrawal status, 1: wait approve, 2: processing, 3: confirming, 4: success, 5: failed, 6: approve failed, 7: exception 8: risk
create_time	int	The withdrawal create UNIX seconds timestamp

Response Example

200 Query success

{
    "success": true,
    "result":
    [
        {
            "id": "1816745214862295040",
            "coin": "TRON_USDT",
            "withdraw_amount": "5",
            "fee": "0.1049",
            "actual_amount": "4.8951",
            "address": "TDD1DYWkAr37thmRjaZntxcjs7tgwUjcd1",
            "tx_hash": "20c0469e418bc0b7b26396fcac4cc3e3b471c0f2f336f168eaf3af7f169f9f72",
            "status": 1,
            "create_time": 1721980787
        }
    ]
}

Withdrawal result webhook.

The webhook URL is used to notify the merchant when the withdrawal result changes. You can configure the webhook URL in the merchant administration web interface.

The webhook request method is POST and the body is a JSON string. The content of the request body matches the response body of the "Query Withdrawals" API result.

The webhook response must return an HTTP status code of 200 with the response body containing the string OK. If the response does not return 200 OK, the system will retry the webhook up to 20 times, with each retry occurring at 60-second intervals. If all retry attempts fail, the webhook notification will be marked as unsuccessful. In such cases, merchants can manually initiate an additional retry via the merchant administration web interface.

Request Body (application/json)

Name	Type	Description
id	string	The unique withdrawal id in coinq pay
coin	string	The coin unique name in coinq pay
withdraw_amount	string	The withdrawal amount
fee	string	The withdrawal fee
actual_amount	string	The actual withdrawal amount
address	string	The withdrawal address
tx_hash	string	The transaction hash
status	int	The withdrawal result status, 4: success, 5: failed, 6: approve failed, 8: risk
create_time	int	The withdrawal create UNIX seconds timestamp

Request Body (application/json) Example

{
    "id": "1816745214862295040",
    "coin": "TRON_USDT",
    "withdraw_amount": "5",
    "fee": "0.1049",
    "actual_amount": "4.8951",
    "address": "TDD1DYWkAr37thmRjaZntxcjs7tgwUjcd1",
    "tx_hash": "20c0469e418bc0b7b26396fcac4cc3e3b471c0f2f336f168eaf3af7f169f9f72",
    "status": 4,
    "create_time": 1721980787
}

Withdrawal second confirmation webhook.

The withdrawal second confirmation webhook is used after a merchant submits a withdrawal request through the API. This step requires the merchant to confirm the withdrawal request a second time to ensure its authenticity. This measure helps prevent asset loss due to unauthorized requests that might result from the leakage of API private keys. You can configure the webhook URL in the merchant administration web interface. If the webhook URL not set, the system will not send the webhook message.

The webhook response must return an HTTP status code of 200 with the response body containing the string OK. If the response does not return 200 OK, the system will retry the webhook up to 20 times, with each retry occurring at 60-second intervals. If all retry attempts fail, the webhook notification will be marked as unsuccessful. In such cases, merchants can manually initiate an additional retry via the merchant administration web interface.

Request Body (application/json)

Name	Type	Description
id	string	The unique withdrawal id in coinq pay
coin	string	The coin unique name in coinq pay
withdraw_amount	string	The withdrawal amount
fee	string	The withdrawal fee
actual_amount	string	The actual withdrawal amount
address	string	The withdrawal address
create_time	int	The withdrawal create UNIX seconds timestamp

Request Body (application/json) Example

{
    "id": "1816745214862295040",
    "coin": "TRON_USDT",
    "withdraw_amount": "5",
    "fee": "0.1049",
    "actual_amount": "4.8951",
    "address": "TDD1DYWkAr37thmRjaZntxcjs7tgwUjcd1",
    "create_time": 1721980787
}

Error Codes

Response error codes:

• 1000 Unknown internal error

• 1002 A request method is not supported for the requested resource

• 1003 Unexpected Request

• 1004 Request time expired

• 1005 Detected request replay

• 12000 Api signature header missing

• 12001 Api signature verification failed

• 12002 Coin not supported

• 12003 Permission deny

• 12004 Transaction not found

• 12005 Api key has no permission

• 12006 IP not allowed

• 12007 Insufficient balance

• 12008 Coin temporarily unavailable

• 12010 Account has been frozen

• 12011 Amount too small

• 12012 Address is invalid

• 12015 Address does not exist

• 12016 Order not found

• 12017 Order id already exists

• 12204 Exceeds the current coin precision