# Exchange API Documentation
# 1. How to get API Key
The user logs in to the cash register -> Developer Center -> API Key -> Create API key. API Key has a separate configuration page and is bound to a fixed IP address ("0.0.0.0" means no IP interception and filtering, and any IP can be accessed), and different API Keys can be configured to meet different needs. Please do not disclose your Access Key and Secret Key to avoid asset loss. After the Secret Key is generated, it cannot be viewed again. Please save it in time. If you forget the Secret Key, please recycle the key pair in the backstage of the merchant and apply for a new key pair.
# 1.1 How to create an API KEY
• Click Developer Center - API Key
• 1 Choose whether to enable the debug mode (After debugging mode is enabled, you will have a standard prompt message and log view address for any errors)
• 2Select API Key permissions
• 3Enter the whitelist address (0.0.0.0 means that any IP address can be accessed)
Note: (When entering the whitelist domain name, you should pay attention to using "," to isolate multiple IPs.)
• 4 click create to generate API KEY
(After the API KEY is generated, you can copy, view, edit, and delete it in the My API KEY list below. Note that the Secret key only appears once when it is generated. Please save it properly. If you forget the Secret Key, please recycle it key pair and apply for a new key pair.)
• Click Edit to close or open [Start Debugging] and modify API Key permissions and whitelist addresses. After modification, click Save
Note: Please wait patiently for 90 seconds for the API Key to take effect after creating or editing the API Key
# 2. How to use API Key
The current API Key is to add a parameter list in the header of the request
| parameter name | Parameter Description | type | Is it necessary |
|---|---|---|---|
| access_key | Api Key access key (eg: TPhoa7ZQ) | String | yes |
| timestamp | Millisecond time stamp (13 digits such as: 1679669488472) | String | yes |
| nonce | UUID (36 bits such as: 02f7a04f-53cc-47d4-bb3f-fae69dab49ac) The five parts are 8 characters, 4 characters, 4 characters, 4 characters, and 12 characters, separated by "-" | String | yes |
| sign | Parameter signature (eg: GXx2wYUD6UVr+zcmeCSFFPzcBLA=) | String | yes |
# 3. Technical side parameter access process
# 4. How to sign the interface
# Signature instructions
API requests are very likely to be tampered with during transmission over the internet. In order to ensure that the request has not been changed, all private interfaces except the public interface (basic information, market data, etc.) must use your API Key for signature authentication to verify Check whether the parameter or parameter value has changed in transit.
A legitimate request consists of the following parts:
- access_key: API access key;
- secret_key: the key used for signature encryption (only visible once when applying for an API Key in the background, please copy and save it in a safe place, and cannot disclose it);
- timestamp: The time (UTC time) when you made the request. Such as: 1632811287325 (13 digits). Including this value in a query request helps prevent third parties from intercepting your request;
- nonce: random UUID string. Such as: 053a1b81-48a0-4bb1-96b2-60f6e509d911 (36 bits);
- sign: The value calculated by the signature, which is used to ensure that the signature is valid and has not been tampered with;
- All interfaces need to pass the above public parameters except secret_key in the http request header (header) . The public parameters include (access_key, timestamp, nonce, sign) and other signature parameters are subject to the API interface description.
# Signature steps
1. Define a Map dictionary type object, and put the parameters in the request into it in the form of key-value
2. Put access_key, timestamp, and nonce into the Map defined in the first step
3. Sort the attributes in the Map in ascending order (lexicographic order) according to the ASCII code and convert the Map to a string in the form of "key1=value1&key2=value2"
4. Encrypt the character string converted in the previous step with secret_key by HMAC_SHA1 and perform Base64 transcoding to obtain the value of the sign parameter. secret_key is the information in the apikey created on the cashier platform
5. Add the sign value and other required parameters to the request header, and send the request to the target interface
# Signature Debugging Tool
SignUtil: User login to cash register -> Developer Center -> API Documentation -> Signature Tool The Signature tool page is displayed (Please use a valid access_key for the access_key in the tool and please set the IP whitelist that allows this access_key to access to 0.0.0.0, we strongly recommend that the used access_key be discarded after debugging )
# 5. Interface list
# 5.1 Test interface connectivity
request method
Get
Request URL
/ping
response data
{ "version" : "1.0.1" , "timestamp" : 1688116827306 }
Response parameter description
| Param | type | Desc |
|---|---|---|
| version | String | If this parameter is returned, all interfaces in this document can be requested normally |
| timestamp | int64 | Unix timestamp |
# 5.2 Fiat currency exchange encryption
request method
post
Request URL
/api/v3/exchange/fiat/to/wallet
Request type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
request header
| Param | Desc | Sample |
|---|---|---|
| access_key | Merchant background acquisition | pFqV75X3 |
| timestamp | Unix timestamp 13 digit milliseconds | 1679724896223 |
| nonce | UUID V4 | 794c26b0-d33c-4394-b2bb-c485eca16d9e |
| sign | computed signature | kAXyh+eerqrefyaF8dyFB0M4FVo= |
request parameters
{
"addressTo" : "0x0CBFD17AE9E1d6D881b2CAde71277f48aBf64D24" ,
"chainType" : "ETH" ,
"tokenType" : "USDT" ,
"currencyAmount" : 1 ,
"currencyType" : "BRL" ,
"externalOrderId" : "469170783478455217" ,
"remark" : "123"
}
Description of request parameters
| Param | Desc | require |
|---|---|---|
| addressTo | Payment address (String) | required |
| chainType | Main chain type (String) oneof=ETH TRON BSC | required |
| tokenType | Token type oneof=USDT (String) | required |
| currencyAmount | The legal currency amount cannot be less than 1 (String) | required |
| currencyType | Fiat currency type oneof=BRL MXN(String) | required |
| externalOrderId | Merchant order ID (String) | required |
| remark | Note max=255 (String) | optional |
response type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
response data
{
"code" : "200" ,
"success" : true ,
"msg" : "Success" ,
"msgEn" : "SUCCESS" ,
"data" : {
"orderId" : "OCURREXCH202307180805431689667543340DOCKER020000000200000250" ,
"symbolType" : "CURRENCY TO TOKEN" ,
"externalOrderId" : "469170783478455217" ,
"currencyType" : "BRL" ,
"tokenType" : null ,
"chainType" : "ETH" ,
"currencyAmount" : 1 ,
"tokenAmount" : 0.145985
}
}
Response parameter description
| Param | type | Desc |
|---|---|---|
| orderId | String | order ID |
| symbolType | String | benchmark type |
| externalOrderId | String | Merchant order ID |
| currencyType | String | Fiat currency type |
| tokenType | String | token type |
| chainType | String | main chain type |
| currencyAmount | int64 | Fiat amount |
| tokenAmount | float64 | token amount |
# 5.3 Query Fiat exchange Crypto orders
request method
post
Request URL
/api/v3/exchange/query/exchange/orderinfo
Request type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
request header
| Param | Desc | Sample |
|---|---|---|
| access_key | Merchant background acquisition | pFqV75X3 |
| timestamp | Unix timestamp 13 digit milliseconds | 1679724896223 |
| nonce | UUID V4 | 794c26b0-d33c-4394-b2bb-c485eca16d9e |
| sign | computed signature | kAXyh+eerqrefyaF8dyFB0M4FVo= |
request parameters
{
"externalOrderId" : "469170783478455217" ,
"orderId" : "OCURREXCH202307180805431689667543340DOCKER020000000200000250"
}
Description of request parameters
| Param | Desc | require |
|---|---|---|
| externalOrderId | Merchant order number max=64 (String) | required |
| orderId | Order ID (String) | required |
response type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
response data
{
"code" : "200" ,
"success" : true ,
"msg" : "Success" ,
"msgEn" : "SUCCESS" ,
"data" : {
"tokenAmount" : "0.145985" ,
"currencyAmount" : "1.00" ,
"orderAmount" : "1" ,
"orderActualAmount" : null ,
"orderFee" : null ,
"orderPayTime" : null ,
"orderCompleteTime" : null ,
"currencyType" : "BRL" ,
"tokenType" : "USDT" ,
"chainType" : "ETH" ,
"exSymbolType" : "CURRENCY TO TOKEN" ,
"exchangeRate" : "6.85" ,
"addressTo" : "0x0CBFD17AE9E1d6D881b2CAde71277f48aBf64D24" ,
"remark" : "123" ,
"tradeHash" : "" ,
"errorMsg" : null ,
"errorMsgEn" : null ,
"orderId" : "OCURREXCH202307180805431689667543340DOCKER020000000200000250" ,
"externalOrderId" : "469170783478455217" ,
"orderStatus" : 2
}
}
Response parameter description
| Param | type | Desc |
|---|---|---|
| tokenAmount | String | Token amount |
| currencyAmount | String | Fiat amount |
| orderAmount | String | Order amount |
| orderActualAmount | float64 | Actual order amount |
| orderFee | float64 | Order handling fee |
| orderPayTime | int64 | order payment time |
| orderCompleteTime | int64 | order completion time |
| currencyType | String | Fiat currency type |
| tokenType | String | token type |
| chainType | String | main chain type |
| exSymbolType | String | benchmark type |
| exchangeRate | String | Exchange rate at the time of order generation |
| addressTo | String | Receiving address |
| remark | String | Remark |
| tradeHash | String | transaction hash |
| errorMsg | String | error message |
| errorMsgEn | String | error message en |
| orderId | String | order ID |
| externalOrderId | String | Merchant order ID |
| orderStatus | int64 | Order status 1-Wait pay currency 2-receiving currency 4-Wait receive token 8-Exchange complete 32-Exchange fail |
# 5.4 Cryptocurrency exchange for fiat currency
Request method
Post
Request URL
/api/v3/exchange/wallet/to/fiat
Request type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
Request header
| Param | Desc | Sample |
|---|---|---|
| access_key | Obtain from merchant background | pFqV75X3 |
| timestamp | Unix timestamp 13 digit milliseconds | 1679724896223 |
| nonce | UUID V4 | 794c26b0-d33c-4394-b2bb-c485eca16d9e |
| sign | calculated signature | kAXyh+eerqrefyaF8dyFB0M4FVo= |
Request parameters
{
"tokenAmount": 1010,
"chainType": "TRON",
"addressFrom": "TBoG3wMvQhFUYQdcrHF6M3s7TKNHvCdW4w",
"currencyType": "BRL",
"tokenType": "USDT",
"externalOrderId": "2564895864",
"notifyUrl": "",
"remark": "TEST"
}
Request parameter description
| Param | Desc | Require |
|---|---|---|
| tokenAmount | Token amount (String) | required |
| chainType | Main chain type oneof=TRON (String) | required |
| addressFrom | Withdrawal address (String) | required |
| currencyType | Legal currency type oneof=BRL (String) | required |
| tokenType | Token type oneof=USDT (String) | required |
| externalOrderId | Merchant order ID (String) | optional |
| notifyUrl | Notification address (String) | optional |
| remark | Remarks (String) | optional |
response type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
response data
{
"code": "200",
"success": true,
"msg" : "success" ,
"msgEn": "SUCCESS",
"data": {
"orderId": "OCRYPEXCH202310090612161696831936686DEV001OO0000000200000250",
"symbolType": "TOKEN TO CURRENCY",
"externalOrderId": "11705714",
"currencyType": "BRL",
"tokenType": "USDT",
"chainType": "TRON",
"currencyAmount": 5171.2,
"tokenAmount": 1010,
"addressTo": "TNZEyuAhvDX1YoHpGPVzD5gBqK7e56tbF5"
}
}
Response parameter description
| Param | Type | Desc |
|---|---|---|
| orderId | String | Order ID |
| symbolType | String | Base type |
| externalOrderId | String | Merchant order ID |
| currencyType | String | Fiat currency type |
| tokenType | String | Token type |
| chainType | String | Main chain type |
| currencyAmount | int64 | Legal currency amount |
| tokenAmount | float64 | Token amount |
| addressTo | String | Payment address |
# 5.5 Query crypto-to-fiat currency orders
Request method
Post
Request URL
/api/v3/exchange/query/wallet/exchange/orderinfo
Request type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
Request header
| Param | Desc | Sample |
|---|---|---|
| access_key | Obtain from merchant background | pFqV75X3 |
| timestamp | Unix timestamp 13 digit milliseconds | 1679724896223 |
| nonce | UUID V4 | 794c26b0-d33c-4394-b2bb-c485eca16d9e |
| sign | calculated signature | kAXyh+eerqrefyaF8dyFB0M4FVo= |
Request parameters
{
"externalOrderId": "2564895864",
"orderId": "OCRYPEXCH202310090610471696831847220DEV001OO0000000200000249"
}
Request parameter description
| Param | Desc | Require |
|---|---|---|
| externalOrderId | Merchant order number max=64 (String) | required |
| orderId | Order ID (String) | required |
response type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
response data
{
"code": "200",
"success": true,
"msg" : "success" ,
"msgEn": "SUCCESS",
"data": {
"tokenAmount": "1010",
"currencyAmount": "5171.20",
"orderAmount": "1010",
"orderActualAmount": null,
"orderFee": "0",
"orderPayTime" : null ,
"orderCompleteTime": null,
"currencyType": "BRL",
"tokenType": "USDT",
"chainType": "TRON",
"exSymbolType": "TOKEN TO CURRENCY",
"exchangeRate": "5.12",
"addressTo": "TNZEyuAhvDX1YoHpGPVzD5gBqK7e56tbF5",
"remark": "TEST",
"notifyUrl": "https://tofficeapi.hambit.io/api/v1/hambit/hambit-operate/testNotify",
"tradeHash": "",
"errorMsg" : null ,
"errorMsgEn": null,
"orderId": "OCRYPEXCH202310090610471696831847220DEV001OO0000000200000249",
"externalOrderId": "33857163",
"orderStatus": 4
}
}
Response parameter description
| Param | Type | Desc |
|---|---|---|
| tokenAmount | String | Token amount |
| currencyAmount | String | Legal currency amount |
| orderAmount | String | order amount |
| orderActualAmount | float64 | Actual amount of order |
| orderFee | String | Order handling fee |
| orderPayTime | int64 | Order payment time |
| orderCompleteTime | int64 | order completion time |
| currencyType | String | Fiat currency type |
| tokenType | String | Token type |
| chainType | String | Main chain type |
| exSymbolType | String | Base type |
| exchangeRate | String | Exchange rate when order is generated |
| addressTo | String | Payment address |
| remark | String | Remark |
| tradeHash | String | transaction hash |
| errorMsg | String | error message |
| errorMsgEn | String | Error message |
| orderId | String | Order ID |
| externalOrderId | String | Merchant order ID |
| orderStatus | int64 | Order status 1-Wait pay currency 2-receiving currency 4-Wait receive token 8-Exchange complete 32-Exchange fail |
Note that the http response status_code has the highest priority as long as the response status_code=200 is received and the response data is ignored
# 6. Public Response Code
| filed | type | Default value and comment |
|---|---|---|
| code | String | Success "200" Other please refer to the failure code |
| success | Bool | Success is true, failure is false, and code is kept in sync |
| msg | String | The textual description returned by the first-level code |
| data | object | Refer to the interface list chapter |
# 7. Failure code
| Code | Desc |
|---|---|
| 200 | normal |
| 300 | Parameter exception |
| 301 | IP has no authority |
| 307 | signature error |
| 500 | system error |