3.0 SDK Return Result Format

{
    "code": 0,
    "msg": "success",
    "count": 0,
    "data": {}
}

Parameter	Type	Description
code	int	Request result: 0 = success, other = failure
msg	string	Error message: "success" for success, error details for failure
count	int	Number of elements when data is JSON array
data	object	Returned data: single JSON object or JSON array

3.1 Query Supported Chain Information

HashNut supports multiple chains and currencies. Query supported chains before creating orders.

curl --location --request POST 'https://testnet-web3.hashnut.io/api/v2.0.0/config/queryAllChainInfo'

The returned information is as follows:

{
    "code": 0,
    "msg": "success",
    "ui": null,
    "version": null,
    "count": 0,
    "data": [
        {
            "id": 1,
            "chain": "ETH",
            "chainDesc": "BlockChain Ethereum",
            "enable": true,
            "receiptAddress": "0x8126ac362f08ec6a58b43e537f3dbbb474c70595",
            "txConfirmCount": "3",
            "walletConnectEnable": true,
            "bridgeServerAddress": "https://bridge.hashnut.io",
            "decimals": 18,
            "baseChainSymbol": "Ethereum",
            "env": 1,
            "chainId": "11155111",
            "baseChainCoin": "ETH",
            "createTime": 1710938845128,
            "updateTime": 1710938845128,
            "eip712ChainId": "0",
            "eip1559Support": true
        }
        ...
    ]
}

Parameter	Type	Description
chain	string	Chain abbreviation: ETH, BSC, TRON, POLYGON
chainDesc	string	Chain description
enable	boolean	Whether chain is available
receiptAddress	string	HashNut platform receiving address
txConfirmCount	int	Required confirmations for valid transactions
walletConnectEnable	boolean	Whether chain supports walletconnect protocol
bridgeServerAddress	string	Walletconnect bridge server address
decimals	int	Chain precision (ETH=18, TRON=6)
baseChainSymbol	string	Base chain name
env	int	Environment: 0=Production, 1=Testing, 2=Development
chainId	long	EVM chain ID (POLYGON=137, Mumbai=80001)
baseChainCoin	string	Base currency (ETH, MATIC)
eip712ChainId	string	EIP712 chain ID (valid for EIP712 chains)
eip1559Support	boolean	Whether EIP1559 is supported

3.2 Query Supported Chain and Currency Information

After obtaining chain code, query currencies supported by that chain (e.g., ERC20 currencies).

curl --location --request POST 'https://testnet-web3.hashnut.io/api/v2.0.0/config/queryAllCoinInfo'

The returned information is as follows:

{
    "code": 0,
    "msg": "success",
    "ui": null,
    "version": null,
    "count": 0,
    "data": [
        {
            "id": 1,
            "chain": "ETH",
            "chainCode": "erc20",
            "coinCode": "usdt",
            "isToken": true,
            "enable": true,
            "contractAddress": "0xe2d7250b2ec3cd208ac5b42886edd162411529c4",
            "coinDesc": "tether usdt",
            "gateWayEnable": true,
            "decimals": "6",
            "createTime": 1710938845130,
            "updateTime": 1710938845130,
            "nftmarket": "opensea"
        }
        ...
    ]
}

Parameter	Type	Description
chain	string	Chain name (e.g., ETH)
chainCode	string	Chain code: erc20, trc20, bep20, polygon-erc20
coinCode	string	Currency code: erc20=usdt/usdc, bep20=busd/hashnut, trc20=usdt
isToken	boolean	Whether currency is token (false for base tokens like ETH, BSC, TRX)
enable	boolean	Whether currency is available (unavailable currencies cannot create orders)
contractAddress	string	Currency smart contract address
coinDesc	string	Currency description
gateWayEnable	boolean	Whether gateway payments supported (Binance app)
decimals	int	Currency precision (USDT=6, BUSD=18)

3.3 Query Supported Currency Information by Type

curl --location 'https://testnet-web3.hashnut.io/api/v2.0.0/config/querySupportCoinsByChainCode' \
--header 'Content-Type: application/json' \
--data '{
    "chainCode":"erc20"
}'

The returned information is as follows:

{
    "code": 0,
    "msg": "success",
    "ui": null,
    "version": null,
    "count": 0,
    "data": [
        {
            "id": 2,
            "chain": "ETH",
            "chainCode": "erc20",
            "coinCode": "usdc",
            "isToken": true,
            "enable": true,
            "contractAddress": "0x4ca772bb3e6326647b8dd02ddbc758773aa7c650",
            "coinDesc": "usdc",
            "gateWayEnable": true,
            "decimals": "6",
            "createTime": 1710938845132,
            "updateTime": 1710938845132,
            "nftmarket": "opensea"
        },
        ...
    ]
}

Request Parameters:

Parameter	Type	Description
chainCode	string	Token type: erc20, trc20, bep20, polygon-erc20

Response Parameters:

Parameter	Type	Description
chain	string	Chain name (e.g., ETH)
chainCode	string	Chain code: erc20, trc20, bep20, polygon-erc20
coinCode	string	Currency code: erc20=usdt/usdc, bep20=busd/hashnut, trc20=usdt
isToken	boolean	Whether currency is token (false for base tokens)
enable	boolean	Whether currency is available
contractAddress	string	Currency smart contract address
coinDesc	string	Currency description
gateWayEnable	boolean	Whether gateway payments supported
decimals	int	Currency precision (USDT=6, BUSD=18)

3.5 Create Order

HashNut supports multi-currency payments. Merchants can create orders and choose payment channels.

Request:

curl --location 'https://testnet-web3.hashnut.io/api/v2.0.0/pay/createPayOrderWithApiKey' \
--header 'hashnut-request-uuid: xxxx' \
--header 'hashnut-request-timestamp: xxxx' \
--header 'hashnut-request-sign: xxxx' \
--header 'Content-Type: application/json' \
--data '{
    "accessKeyId": "ACC_1156690317534035968",
    "merchantOrderId": "100000",
    "chainCode": "polygon-erc20",
    "coinCode": "usdt",
    "amount": 1.13,
    "receiptAddress": "0x1a580cca96a3d1070cb23b63480b3afafe0bf025"
}'

Request Body Parameters:

Parameter	Type	Description
accessKeyId	string	Merchant API KEY ID
merchantOrderId	string	Unique merchant order ID
chainCode	string	Chain code
coinCode	string	Currency code
amount	Decimal(20)	Payment amount (max 2 decimal places)
receiptAddress	string	Merchant's deployed smart contract address

Request Headers:

Header	Type	Description
hashnut-request-uuid	string	UUID generated by merchant
hashnut-request-timestamp	string	Timestamp
hashnut-request-sign	string	Signature (uuid+timestamp+body) with API secret key

The code for generating hashnut-request-sign is as follows:

    String uuid=request.getHeader("hashnut-webhook-uuid");
    String timeStamp=request.getHeader("hashnut-webhook-timestamp");
    // body is body is the JSON-serialized string of the request content
    String dataToSign=String.format("%s%s%s",uuid,timeStamp,body);
    String sign= PayDigestUtil.HMACSHA256Base64(HashNutConfig.secretKey,dataToSign);

the PayDigestUtil.HMACSHA256Base64 code:

    public static String HMACSHA256Base64(String key,String data) throws Exception {
        Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secret_key = new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
        sha256_HMAC.init(secret_key);
        sha256_HMAC.update(data.getBytes());
        byte[] array = sha256_HMAC.doFinal();
        return Base64.getEncoder().encodeToString(array);
    }

The returned information is as follows:

{
    "code": 0,
    "msg": "success",
    "ui": null,
    "version": null,
    "count": 0,
    "data": {
        "mchAddress": "0x6a0b7b0b95ce640b3fe3fede6ebfed4de9293019",
        "chain": "POLYGON",
        "chainCode": "polygon-erc20",
        "coinCode": "usdt",
        "createChannel": 1,
        "accessChannel": 0,
        "merchantOrderId": "10000",
        "payOrderId": "01HSKATBCK7CE20N88B25870M5",
        "tokenAddress": "0x0de51eb069fd04f5ff6fb48f1dad6766ac558b33",
        "receiptAddress": "0x78f43ee9985aacd8da1c6dd099213b402aa98672",
        "amount": 1.160000,
        "state": 4,
        "accessSign": "24625267842A4074D6332A59A7BE49069C63B0392340171F1E2F1FF8C6AA9879",
        "payTxId": "0xd77cd2e8488e3b8db02dc5e3f2bdac2da99795fbcf91408b6eae68da50d752fb",
        "confirmCount": "3",
        "walletConnectEnable": true,
        "bridgeServerAddress": "https://bridge.hashnut.io",
        "eip712ChainId": "0",
        "chainId": "80001",
        "createTime": "0",
        "rate": 80,
        "obtainAmount": 1.15072,
        "platformFee": 0.00928
    }
}

The parameters in the response include

Variable Name	Type	Description
chain	string	Chain where the payment order token is located
mchAddress	string	Merchant address for placing orders, which is the merchant address that created the payment smart contract
chainCode	string	Chain code
coinCode	string	Currency code
createChannel	int	Channel through which the merchant created the order, 0-Merchant system 1-ApiKey, since the order is created through the API key, the value is 1
accessChannel	byte	The channel through which the end user pays for the order, since it is a blockchain payment, the value is 0
merchantOrderId	string	Merchant order number, a unique order ID generated by the merchant
payOrderId	string	Hashnut's platform order number, a unique receiving address generated by Hashnut
contractAddress	string	The smart contract address of the currency, when users send transactions, 'to' needs to be filled with the smart contract address of the currency
receiptAddress	string	Smart contract address used to receive user funds
inputData	string	Input data of the transaction, encoded using web3j, including: Hashnut receiving address and order amount
accessSign	string	Signature of (platformId+mchOrderId) using the API key

Merchant concatenates the payment order URL

Merchants use the accessSign, merchantOrderId, and payOrderId from the create order response to concatenate a payment URL to send to the end user, for example:

https://testnet-web3.hashnut.io/pay?accessSign=42889E72DAAE0C4275F804DDDFA4707823FE30EB4D4BB6064859CB65AA3E6305&merchantOrderId=10000&payOrderId=01HSKATBCK7CE20N88B25870M5

The parameters in the URL are:

Variable Name	Type	Description
accessSign	string	Signature of (platformId+merchantOrderId) using the api key
merchantOrderId	string	Merchant order ID
payOrderId	string	HashNut platform order ID, a unique order ID generated by HashNut

3.6 Callback notification

Callback notification

The callback URL can be configured in the Create ApiKey interface, including backend callback URL and frontend callback URL, both of which contain the following parameters:

Variable Name	Type	Description
payOrderId	string	HashNut platform order ID, a unique order ID generated by HashNut

3.7 Query order

Query order information

After receiving the payment order URL, users need to use accessSign to query the order information first to confirm if the order has been paid to prevent duplicate payments

Request:

curl --location 'https://testnet-web3.hashnut.io/api/v2.0.0/pay/queryPayOrderWithAccessSign' \
--header 'Content-Type: application/json' \
--data '{
    "merchantOrderId": "a89206d0-7883-48dd-9316-e494f2679e72",
    "payOrderId": "01HSKATBCK7CE20N88B25870M5",
    "accessSign": "24625267842A4074D6332A59A7BE49069C63B0392340171F1E2F1FF8C6AA9879"
}'

The requested parameters include:

Variable Name	Type	Description
merchantOrderId	string	Merchant order number, a unique order ID generated by the merchant
payOrderId	string	Platform order number of hashnut
accessSign	string	Signature of (platformId+mchOrderId) using the API key

The returned information is as follows:

{
    "code": 0,
    "msg": "success",
    "ui": null,
    "version": null,
    "count": 0,
    "data": {
        "mchAddress": "0x6a0b7b0b95ce640b3fe3fede6ebfed4de9293019",
        "chain": "POLYGON",
        "chainCode": "polygon-erc20",
        "coinCode": "usdt",
        "createChannel": 1,
        "accessChannel": 0,
        "merchantOrderId": "a89206d0-7883-48dd-9316-e494f2679e72",
        "payOrderId": "01HSKATBCK7CE20N88B25870M5",
        "tokenAddress": "0x0de51eb069fd04f5ff6fb48f1dad6766ac558b33",
        "receiptAddress": "0x78f43ee9985aacd8da1c6dd099213b402aa98672",
        "amount": 1.160000,
        "state": 4,
        "accessSign": "24625267842A4074D6332A59A7BE49069C63B0392340171F1E2F1FF8C6AA9879",
        "payTxId": "0xd77cd2e8488e3b8db02dc5e3f2bdac2da99795fbcf91408b6eae68da50d752fb",
        "confirmCount": "3",
        "walletConnectEnable": true,
        "bridgeServerAddress": "https://bridge.hashnut.io",
        "eip712ChainId": "0",
        "chainId": "80001",
        "callBackUrl": "https://testnet-web3.hashnut.io/shop/payFinish?payOrderId=01HSKATBCK7CE20N88B25870M5&chain=POLYGON&amount=1160000&chainCode=polygon-erc20&sign=CAD9387C2D51389B2512C324932B1277F68B177E6C3933BC5EA686FB3A935C8C&merchantOrderId=a89206d0-7883-48dd-9316-e494f2679e72&accessSign=24625267842A4074D6332A59A7BE49069C63B0392340171F1E2F1FF8C6AA9879&obtainAmount=1150720&payTxId=0xd77cd2e8488e3b8db02dc5e3f2bdac2da99795fbcf91408b6eae68da50d752fb&receiptAddress=0x78f43ee9985aacd8da1c6dd099213b402aa98672&merchantAddress=0x6a0b7b0b95ce640b3fe3fede6ebfed4de9293019&confirmCount=3&state=4&coinCode=usdt&paySuccessTime=",
        "createTime": "0",
        "rate": 80,
        "obtainAmount": 1.150720,
        "platformFee": 0.009280
    }
}

The response parameters include:

Variable Name	Type	Description
chain	string	Chain where the payment order token is located
mchAddress	string	Merchant address for placing orders, which is the merchant address that created the receiving smart contract
chainCode	string	Chain code
coinCode	string	Currency code
createChannel	int	Channel through which the merchant created the order, 0-merchant system 1-ApiKey, as the order was created through an API key, the value is 1
accessChannel	byte	Channel through which the end user pays the order, as it is a gateway payment, the value is 1
mchOrderId	string	Merchant order number, a unique order ID generated by the merchant
platformId	string	Platform order number of hashnut, a unique order number generated by hashnut
contractAddress	string	The smart contract address of the currency, users need to fill in 'to' with the smart contract address of the currency when sending transactions
receiptAddress	string	The smart contract address that receives user funds
inputData	string	The input data of the transaction, encoded using web3j, including: hashnut receiving address and order amount
accessSign	string	Signature of (platformId+mchOrderId) using the api key
qrcodeLink	string	Gateway payment QR code image address
qrContent	string	This value is ignored
walletConnectEnable	boolean	Whether this order supports walletconnect launch
bridgeServerAddress	string	If walletConnectEnable is true, this value represents the walletconnect bridge server address

When replying to the user, the user needs to pay attention to the state of the order. If the state is greater than 0, it means that the payment has already been made, and further payment will be rejected

For a more concise and detailed usage method, please refer to Test Case Source Code In ServiceTest.java

3.1 Query Supported Chain Information

3.2 Query Supported Chain and Currency Information

3.3 Query Supported Currency Information by Type

3.5 Create Order

Merchant concatenates the payment order URL​

3.6 Callback notification

Callback notification​

3.7 Query order

Query order information​

Merchant concatenates the payment order URL

Callback notification

Query order information