Block Trade Api

General API Information

Endpoint https://api-otc.trubit.com

  • All endpoints return either a JSON object or array.

  • Data is returned in ascending order. Oldest first, newest last.

  • All time and timestamp related fields are in milliseconds.

  • HTTP 4XX return codes are used for for malformed requests; the issue is on the sender's side.

  • HTTP 429 return code is used when breaking a request rate limit.

  • HTTP 418 return code is used when an IP has been auto-banned for continuing to send requests after receiving 429 codes.

  • HTTP 5XX return codes are used for internal errors; the issue is on broker's side. It is important to NOT treat this as a failure operation; the execution status is UNKNOWN and could have been a success.

  • Any endpoint can return an ERROR; the error payload is as follows:

{
  "code": -1121,
  "msg": "Invalid symbol."
}

  • Specific error codes and messages defined in another document.

  • For GET endpoints, parameters must be sent as a query string.

  • For POST, PUT, and DELETE endpoints, the parameters may be sent as a query string or in the request body with content type application/x-www-form-urlencoded. You may mix parameters between both the query string and request body if you wish to do so.

  • Parameters may be sent in any order.

  • If a parameter sent in both the query string and request body, the query string parameter will be used.

Endpoint security type

  • Each endpoint has a security type that determines the how you will interact with it.

  • API-keys are passed into the Rest API via the X-BH-APIKEY header.

  • API-keys and secret-keys are case sensitive.

  • API-keys can be configured to only access certain types of secure endpoints. For example, one API-key could be used for TRADE only, while another API-key can access everything except for TRADE routes.

  • By default, API-keys can access all secure routes.

SIGNED (TRADE and USER_DATA) Endpoint security

  • SIGNED endpoints require an additional parameter, signature, to be sent in the query string or request body.

  • Endpoints use HMAC SHA256 signatures. The HMAC SHA256 signature is a keyed HMAC SHA256 operation. Use your secretKey as the key and totalParams as the value for the HMAC operation.

  • The signature is not case sensitive.

  • totalParams is defined as the query string concatenated with the request body.

SIGNED Endpoint Examples for POST /openapi/v1/order

Here is a step-by-step example of how to send a vaild signed payload from the Linux command line using echo, openssl, and curl.

Key
Value

apiKey

tAQfOrPIZAhym0qHISRt8EFvxPemdBm5j5WMlkm3Ke9aFp0EGWC2CGM8GHV4kCYW

secretKey

lH3ELTNiFxCQTmi9pPcWWikhsjO04Yoqw3euoHUuOLC3GYBW64ZqzQsiOEHXQS76

Parameter
Value

requestBody

{"id":0}

timestamp

1538323200000

Example 1: As a query string

  • queryString: symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000

  • requestBodyString: {"id":0}

  • HMAC SHA256 signature:

[linux]$ echo -n "timestamp=1538323200000{"id":0}" | openssl dgst -sha256 -hmac "lH3ELTNiFxCQTmi9pPcWWikhsjO04Yoqw3euoHUuOLC3GYBW64ZqzQsiOEHXQS76"
(stdin)= 5fafd5098eca1e135037f335fe6a9ec6884271cb6933bd7f5ed6a3582f1f0eea

  • curl command:

(HMAC SHA256)
[linux]$ curl -H "X-BH-APIKEY: tAQfOrPIZAhym0qHISRt8EFvxPemdBm5j5WMlkm3Ke9aFp0EGWC2CGM8GHV4kCYW" -X POST 'https://$HOST?1538323200000&signature=5fafd5098eca1e135037f335fe6a9ec6884271cb6933bd7f5ed6a3582f1f0eea' -d '{"id":0}'

How to obtain apiKey and secretKey

https://www.trubit.com/new/user/interface

After creating the apiKey and secretKey, you need to set the IP whitelist.

图片
图片
图片

Endpoints

1. Base Data

Get Country List with Symbol Rate

  • Endpoint: /openapi/v1/otc/base/symbol_rate/country/list

  • Method: GET

  • Request Query Parameters:

    • hasValid (optional, Integer) - Filters countries by validation status.

  • Response: JSON containing the list of countries with symbol rates.

{
  "countryList": [
    {
        "country": "Mexico",  (string: name of the country)
        "abbr": "MX",  (string: abbreviation of the country)
        "flagUrl": "http://xxx"  (string: url of the country flag)
    }
  ]
}

Example

{
    "countryList": [
        {
            "country": "Mexico",
            "abbr": "MX",
            "flagUrl": "https://xxx.png",
            "buySwitch": 1,
            "sellSwitch": 1
        },
        {
            "country": "Argentina",
            "abbr": "AR",
            "flagUrl": "https://xxx.png",
            "buySwitch": 1,
            "sellSwitch": 1
        },
        {
            "country": "Brazil",
            "abbr": "BR",
            "flagUrl": "https://xxxx.png",
            "buySwitch": 1,
            "sellSwitch": 1
        },
        {
            "country": "Colombia",
            "abbr": "CO",
            "flagUrl": "https://xxxx.png",
            "buySwitch": 0,
            "sellSwitch": 0
        },
        {
            "country": "Hong Kong",
            "abbr": "HK",
            "flagUrl": "https://xxxx.png",
            "buySwitch": 0,
            "sellSwitch": 1
        }
    ]
}

Get Self Data List

  • Endpoint: /openapi/v1/otc/base/symbol/self/list_data

  • Method: GET

  • Request Query Parameters:

    • country (string: name of the country)

    • hasValid (number: whether to query only valid data [0: no (default), 1: yes])

  • Response: JSON containing self data list for symbols.

{
        "fiatList": [ (array: list of fiat currencies)
            {
                "name": "MXN", (string: name of the fiat currency)
                "symbolList": [ (string: association list of crypto currencies)
                    "USDT",
                    "MMXN"
                ]
            },
            {
                "name": "ARS",
                "symbolList": [
                    "USDT",
                    "BTC"
                ]
            }
        ],
        "tokenList": [ (array: list of tokens)
            {
                "name": "USDT",  (string: name of the token)
                "symbolList": [ (string: association list of fiat currencies)
                    "MXN",
                    "ARS",
                    "VES",
                    "COP",
                    "TWD",
                    "MYR"
                ]
            },
            {
                "name": "MMXN",
                "symbolList": [
                    "MXN"
                ]
            }   
        ]
    }

2. Rate Management

Get User Quote

  • Endpoint: /openapi/v1/otc/rate/user_quote/find

  • Method: POST

  • Authorization: Requires signature and account verification

  • Headers: Requires signature

    • X-BH-APIKEY (string: API key)

  • Request Body:

{
  "country": "", (string: name of the country)
  "fiatCurrency": "", (string: name of the fiat currency)
  "cryptoCurrency": "" (string: name of the crypto currency)
}

  • Response: JSON containing user quote information.


{
  "hasOpen": 0,  (number: Whether it is open or not[0: no, 1: yes])
  "fiatCurrency": "",  (string: name of the fiat currency)
  "cryptoCurrency": "",  (string: name of the crypto currency)
  "buyRate": 0.0,  (number: buy rate)
  "sellRate": 0.0  (number: sell rate)
}

3. Payment Management

Get Payment Config List

  • Endpoint: /openapi/v1/otc/payment/list

  • Method: GET

  • Request Query Parameters:

    • country (string: name of the country)

  • Response: JSON containing the list of payment configurations.

 {
        "currencys": [  (array: list of currencies)
            {
                "id": 1, (number: id of the currency)
                "fiatCurrency": "USD" (string: name of the fiat currency)        
            }
        ], 
        "payments": [ (array: list of payments)
            {
                "id": 1,  (number: id of the payment)
                "country": "Mexico", (string: name of the country)
                "paymentType": 0,  (number: type of the payment [0: manual(default), 1: auto])
                "fieldList": [ (array: list of custom fields)
                     {
                        "index": 0, / (number: index of the field)
                        "textType": 1,    (enum: type of the text [1: number, 2: letter, 3: number+letter, 4: string, 5: image])
                        "title": "test",  (string: title of the field)
                        "promptText": "Enter number",  (string: default text of the field)
                        "isAccount": true,  (boolean: whether the field is an account)
                        "isOptional": false, (boolean: whether the field is required [true: required(default), false: optional])
                        "maxLimit": 30,    (number: maximum length of the field)
                        "text": "1234567890" (string: text of the field)
                      }
                 ], 
                "fieldNum": 1,               
                "logo": "http://paypal/123", 
                "paymentName": "Paypal" 
            }
       ]
     }

Example Mexico


{
    "currencys": [
        {
            "id": 1,
            "fiatCurrency": "MXN"
        },
        {
            "id": 3,
            "fiatCurrency": "ARS"
        }
    ],
    "payments": [
        {
            "id": 58,
            "country": "Mexico",
            "paymentName": "Automated SPEI - Arcus",
            "paymentType": 1,       
            "waitPayMoneyMinute": 0,
            "waitReceiveMoneyMinute": 0,
            "fieldList": [
                {
                    "index": 1,
                    "textType": 1,
                    "title": "Cuenta CLABE",
                    "promptText": "Cuenta CLABE de 18 d\u00edgitos",
                    "maxLimit": 100,
                    "text": "",
                    "picUrl": [],
                    "tempPicUrl": [],
                    "isOptional": false,
                    "isAccount": true
                },
                {
                    "index": 2,
                    "textType": 4,
                    "title": "Banco",
                    "promptText": "",
                    "maxLimit": 100,
                    "text": "",
                    "picUrl": [],
                    "tempPicUrl": [],
                    "isOptional": false,
                    "isAccount": false
                }
            ],
            "fieldNum": 2
        }
    ]
}

Add Payment

  • Endpoint: /openapi/v1/otc/payment/add

  • Method: POST

  • Authorization: Requires signature and account verification

  • Headers: Requires signature

    • X-BH-APIKEY (string: API key)

  • Request Body:

{
   "mcId": 1, (number: id of the merchant)
   "country": "Mexico", (string: name of the country)
   "fiatCurrency": "USD",(string: name of the fiat currency)
   "paymentConfigId": 1, (number: id of the payment configuration)
   "paymentLogo": "http://localhost/123",  (string: url of the payment logo)
   "paymentMethodName": "Paypal",  (string: name of the payment method)
   "realName": "xiaoming",  (string: name of the real name)
   "fieldJson": [  (array: list of custom fields)
       {
           "index": 0,  (number: index of the field)
           "textType": 1, (enum: type of the text [1: number, 2: letter, 3: number+letter, 4: string, 5: image])
           "title": "Account",  (string: title of the field)
           "promptText": "",   (string: default text of the field)
           "isAccount": true,  (boolean: whether the field is an account)
           "isOptional": false, (boolean: whether the field is required [true: required(default), false: optional])
           "maxLimit": 30,      (number: maximum length of the field)
           "text": "1234567890",  (string: text of the field)
           "picUrl":["http://localhost/1", "http://localhost/2"], (array: list of image links)
           "tempPicUrl":["http://localhost/1", "http://localhost/2"]             (array: list of temporary image links)
       }
   ],
   "remark": "", (string: remark of the payment method)
}

  • Response: JSON containing the result of the add payment operation.

{
    "result": true,
    "msg": "",
    "data": {
        "id": 1  (number: id of the payment)
    }
}

Get My Payment Methods

  • Endpoint: /openapi/v1/otc/payment/my/list

  • Method: GET

  • Authorization: Requires signature and account verification

  • Headers: Requires signature

    • X-BH-APIKEY (string: API key)

  • Request Query Parameters:

    • mcId (number: id of the merchant)

    • country (optional,string: name of the country)

    • fiat (optional,string: name of the fiat currency)

    • status (optional,enum: status of the payment method [0: all(default), 1: valid, 2: authenticating, 3: authentication failed])

    • currentPage (optional,number: current page number)

    • pageSize (optional,number: number of results per page)

  • Response: JSON containing the list of user's payment methods.

 {
    "currentPage": 1,  (number: current page number)
    "size": 10,  (number: number of results per page)
    "total": 100,  (number: total number of results)
    "record":[ (array: list of payment methods)
      { 
        "id": 1,  (number: id of the payment method)
        "mcId": 1,  (number: id of the merchant)
        "paymentConfigId": 1, (number: id of the base payment method)
        "paymentType": 0,  (enum: type of the payment method [0: manual(default), 1: automatic])
        "country": "Mexico",  (string: name of the country)       
        "fiatCurrency": "USD", (string: name of the fiat currency)
        "paymentMethodName": "xiaoming",  (string: name of the payment method)       
        "realName": "xiaoming", (string: name of the real name)
        "fieldJson": [  (array: list of custom fields)
            {
                "index": 0,  (number: index of the field)
                "textType": 1, (enum: type of the text [1: number, 2: letter, 3: number+letter, 4: string, 5: image])
                "title": "Account",  (string: title of the field)
                "promptText": "",  (string: default text of the field)
                "isAccount": true, (boolean: whether the field is an account)
                "isOptional": false,  (boolean: whether the field is required [true: required(default), false: optional])
                "maxLimit": 30,        (number: maximum length of the field)
                "text": "1234567890",  (string: text of the field)
                "picUrl":["http://localhost/1", "http://localhost/2"],  (array: list of image links)
                "tempPicUrl":["http://localhost/1", "http://localhost/2"],  (array: list of temporary image links)
                "boxSize":"" (string: size of the box)
            }
        ], 
        "status": 1, (enum: status of the payment method [1: normal, 2: authenticating, 3: authentication failed])
        "hasRefundAccount": 0,  (enum: whether the payment method is a refund account [0: no, 1: yes])
        "remark": "",  (string: remark of the payment method)
        "createTime":1234566  (number: creation time of the payment method)
        }        
     ]
}

4. Merchant Management

Get Merchant List

  • Endpoint: /openapi/v1/otc/mc/list

  • Method: GET

  • Authorization: Requires signature and account verification

  • Headers: Requires signature

    • X-BH-APIKEY (string: API key)

  • Request Query Parameters:

    • merchantName (optional,string: name of the merchant)

    • email (optional,string: email)

  • Response: JSON containing the list of merchants.

[
        {    
            "id": 1,  (number: id of the merchant)
            "country": "Mexico",  (string: name of the country)
            "merchantName": "TestMc",  (string: name of the merchant)
            "email": "[email protected]",  (string: email)
            "paymentId": 26,  (number: id of the payment method)
            "paymentMethodName": "Paypal",  (string: name of the payment method)
            "fiat": "MXN",  (string: name of the fiat currency)
            "balance": "100.00",  (number: balance of fiat currency)
            "buyLimit":"10000.00",  (number: buy limit of the fiat currency)
            "buyUsed":"2000.00",  (number:  buy used of the fiat currency)
            "sellLimit":"10000.00",  (number: sell limit of the fiat currency)
            "sellUsed":"2000.00"  (number: sell used of the fiat currency)
        }
]

ADD Merchant Info

  • Endpoint: /openapi/v1/otc/mc/add

  • Method: POST

  • Authorization: Requires signature and account verification

  • Headers: Requires signature

    • X-BH-APIKEY (string: API key)

  • Request Parameters:

Add CLABE Merchant Parameters

{
    "trench": "CLABE", (string: Channel [CVU/CLABE])
    "merchantName": "meap", (string: Merchant Name (Unique))
    "email": "[email protected]",(string: Email (Unique))
    "mcType": "COMPANY", (string: Merchant Type [PERSONAL, COMPANY])
    "remark": "xiaoming",  (string: Remark)  
      
    "curp": "xiaoming",  (string: CURP(curp or rfc choose one to fill in))
    "rfc": "xiaoming",  (string: RFC(curp or rfc choose one to fill in))
    "cardIssueDate": "xiaoming",  (string: Card Issue Date (yyyy-MM-dd))
    "cardExpireDate": "xiaoming",  (string: Card Expiry Date(yyyy-MM-dd))
    "address": "xiaoming",  (string: Address)
    "city": "xiaoming",  (string: City)
    "state": "xiaoming",  (string: State )
    "zipCode": "xiaoming",  (string: Zip Code)
    "phone": "xiaoming",  (string: Phone)
        
    "companyName": "xiaoming",  (string: Company Name (Fill in when mcType value is COMPANY))
    "aliasName": "xiaoming",  (string: Alias Name (Fill in when mcType value is COMPANY))
    "companyType": "xiaoming",  (string: Company Type (Fill in when mcType value is COMPANY))
    "incorporationDate": "xiaoming",  (string: Incorporation Date (yyyy-MM-dd) [Fill in when mcType value is COMPANY])
    
    "birthday": "xiaoming",  (string: Birthday (yyyy-MM-dd) [Fill in when mcType value is PERSONAL])
    "name": "xiaoming",  (string: Name (Fill in when mcType value is PERSONAL))
    "fatherSurname": "xiaoming",  (string: Father's Surname (Fill in when mcType value is PERSONAL))
    "motherSurname": "xiaoming"  (string: Mother's Surname (Fill in when mcType value is PERSONAL))  
}

Add CVU Merchant Parameters

{
    "trench": "CLABE", (string: Channel [CVU/CLABE])
    "merchantName": "meap", (string: Merchant Name (Unique))
    "email": "[email protected]",(string: Email (Unique))
    "mcType": "PERSONAL", (string: Merchant Type [PERSONAL, COMPANY])
    "remark": "xiaoming",  (string: Remark)  
      
    "cuit": "20315085801",  (string: CUIT)
    "name": "xiaoming",  (string: Full Name (Remove Diacritics))
}

  • Response: JSON containing the result of the add merchant operation.

{
    "result": true,
    "msg": "",
    "data": {
        "id": 1  (number: id of the merchant)
    }
}

Get Merchant Transfer List

  • Endpoint: /openapi/v1/otc/mc/tran/list

  • Method: GET

  • Authorization: Requires signature and account verification

  • Headers: Requires signature

    • X-BH-APIKEY (string: API key)

  • Request Parameters:

    • startTime (number: optional, timestamp of the start time(millisecond))

    • endTime (number: optional, timestamp of the end time(millisecond))

    • mcSettingsId (number, optional, id of the merchant)

    • type (number, optional, enum: type [0: all(default), 1: deposit, 2: withdraw, 3: Online Refund, 5: Offline Refund])

    • status (number, optional, enum: status [0: all(default), 1: init, 2: completed, 3: canceled])

    • currentPage (number,default 1)

    • pageSize (number,default 10, max 1000)

  • Response: JSON containing the list of orders.

{
    "currentPage": 1,  (number: current page number)
    "size": 10, (number: number of results per page)
    "total": 100, (number: total number of results)   
    "record":[ (array: list of orders)
        {
            "id": "482242167403036672", (number: id of the order)
            "userId": "1172300499489225472", (number: id of the user)
            "orderId": "482242123023106048", (number: id of the order)
            "bankOrderId": "M67REZ8NPD4L65RN4KVGOP", (string: name of the bank order id)
            "country": "Argentina", (number: id of the merchant)
            "mcSettingsId": 4, (number: id of the merchant)
            "merchantName": "AR. Tracey Ernser", (string: name of the merchant name)
            "fiat": "ARS", (string: name of the fiat currency)
            "amount": "1096.74", (decimal: order amount)
            "type": 2, (enum: order status [1: deposit, 2: withdraw, 3: Online Refund, 5: Offline Refund])
            "status": 2, (enum: status [1: init, 2: completed, 3: canceled])
            "accountNumber": "0000775900000000000123",
            "bankName": "Ar Auto API", (string: name of the bank name)
            "createTime": "1737452292000", (string: timestamp of the create time(millisecond))
            "updateTime": "1737452344000" (string: timestamp of the update time(millisecond))
        }
     ]
    }
}

5. Order Management

Get Order List

  • Endpoint: /openapi/v1/otc/order/list

  • Method: GET

  • Authorization: Requires signature and account verification

  • Headers: Requires signature

    • X-BH-APIKEY (string: API key)

  • Request Parameters:

    • currentPage (number,default 1)

    • pageSize (number,default 10)

    • isPending (optional, boolean: whether the order is pending [true: pending, false: not pending])

  • Response: JSON containing the list of orders.

{
    "currentPage": 1,  (number: current page number)
    "size": 10, (number: number of results per page)
    "total": 100, (number: total number of results)
    "pendingOrders": 4 (number: number of pending orders)
    "record":[ (array: list of orders)
        {
        "orderId": "419798134177140736",  (number: id of the order)
        "userId": "1434127291173059584",  (number: id of the user)
        "accountId": "1434127291173059585",  (number: id of the user account)
        "cryptoCurrency": "USDT", (string: name of the crypto currency)
        "cryptoLogo": "https://xxx.png",  (string: logo of the crypto currency)
        "fiatCurrency": "MXN",  (string: name of the fiat currency)
        "orderPrice": "700.00",  (decimal: order price)
        "quantity": "10.00",  (decimal: order quantity)
        "fiatAmount": "7000.00", (decimal: order amount)
        "orderType": "SELL ",L  (enum: order type [BUY: buy, SELL: sell])
        "orderStatus": "30",  (enum: order status [10: pending, 30: approved, 31: support documents pending, 40: pending payment, 50: paid, 60: released, 70: canceled, 80: rejected by self])
        "deptPaymentMethodName": "Mercadopago (Mexico)",  (string: name of the merchant payment method)
        "deptPaymentMethodColor": "#4658C1", (string: color of the merchant payment method)
        "orderApprovedTime": "1722229752000", (number: timestamp of the order approved)
        "hasRefund": 1, (enum: whether the order is a refund order [0: no, 1: yes])
        "hasSelf": 1,  (enum: whether the order is a self order [0: no, 1: yes])
     ]
    }
}

Get Order Detail

  • Endpoint: /openapi/v1/otc/order/detail

  • Method: GET

  • Authorization: Requires signature and account verification

  • Headers: Requires signature

    • X-BH-APIKEY (string: API key)

  • Request Parameters:

    • orderId (number: id of the order)

    • clientId (string: id of the client)

  • Response: JSON containing the details of the specified order.

{
    "orderId": "1", (number: id of the order)
    "clientId": "ebab8a9663704e7cbbeb",  (string: id of the client)
    "userId": "1", (number: id of the user)
    "accountId": "1", (number: id of the user account)
    "cryptoCurrency": "token", (string: name of the crypto currency)
    "cryptoLogo": "token logo", (string: logo of the crypto currency)
    "fiatCurrency": "MXN", (string: name of the fiat currency)
    "orderPrice": "1", (decimal: order price)
    "quantity": "1", (decimal: order quantity)
    "fiatAmount": "1", (decimal: order amount)
    "orderType": "BUY", (enum: order type [BUY: buy, SELL: sell])
    "orderStatus": "10", (enum: order status [10: pending, 30: approved, 31: support documents pending, 40: pending payment, 50: paid, 60: released, 70: canceled, 80: rejected by self])
    "orderApprovedTime": "", (number: timestamp of the order approved)
    "orderTimeFrameMinute": "", (number: time frame of the payment (minute))
    "orderConfirmTimestamp": "", (number: timestamp of the order confirmed (second))
    "orderExpireTimestamp": "", (number: timestamp of the order expired (second))
    "mark": "",                (string: remark)
    "mcId": 1,(number: id of the merchant)
    "mcName": "pel",(string: name of the merchant)
    "traclingNumber": "987654321",(number: transaction number)
    "companyName": "System",(string: name of the company)
    "hasRefund": 1,(enum: whether the order is a refund order [0: no, 1: yes])
    "hasSelf": 1,(enum: whether the order is a self order [0: no, 1: yes])
    "paymentType": 1,(enum: type of the payment method [0: manual(default), 1: automatic])
    "deptPaymentInfo": { (object: merchant payment method information)
        "id": "1", (number: id of the payment method)
        "name": "Paypal",(string: name of the payment method)
        "logo": "http://localhost/123",(string: logo of the payment method)
        "color": "",(string: color of the payment method)
        "paymentFieldList": [  (array: list of custom fields)
            {
                "index": 0,(number: index of the field)
                "textType": 1,(enum: type of the text [1: number, 2: letter, 3: number+letter, 4: string, 5: image])
                "title": "Account",(string: title of the field)
                "promptText": "",(string: default text of the field)
                "isAccount": true,(boolean: whether the field is an account)
                "isOptional": false,(boolean: whether the field is required [true: required(default), false: optional])
                "maxLimit": 30,(number: maximum length of the field)
                "text": "1234567890",(string: text of the field)
                "picUrl":["http://localhost/1", "http://localhost/2"],(array: list of image links)
                "tempPicUrl":["http://localhost/1", "http://localhost/2"],              (array: list of temporary image links)
            }
        ]
     }, 
     "userPaymentInfo": { (object: user payment method information)
        "id": "1", (number: id of the payment method)
        "name": "Paypal",(string: name of the payment method)
        "logo": "http://localhost/123",(string: logo of the payment method)
        "color": "",(string: color of the payment method)
        "paymentFieldList": [  (array: list of custom fields)
            {
                "index": 0,(number: index of the field)
                "textType": 1,(enum: type of the text [1: number, 2: letter, 3: number+letter, 4: string, 5: image])
                "title": "Account",(string: title of the field)
                "promptText": "",(string: default text of the field)
                "isAccount": true,(boolean: whether the field is an account)
                "isOptional": false,(boolean: whether the field is required [true: required(default), false: optional])
                "maxLimit": 30,(number: maximum length of the field)
                "text": "1234567890",(string: text of the field)
                "picUrl":["http://localhost/1", "http://localhost/2"],(array: list of image links)
                "tempPicUrl":["http://localhost/1", "http://localhost/2"],(array: list of temporary image links)
            }
        ]
     }
}

Buy Order Example

{
    "orderId": "433576705563561984",
    "userId": "1489875904414977024",
    "accountId": "1489875904414977025",
    "cryptoCurrency": "USDT",
    "cryptoLogo": "https://xxxx.png",
    "fiatCurrency": "MXN",
    "orderPrice": "20.07",
    "quantity": "0.4982",
    "fiatAmount": "10",
    "orderType": "BUY",
    "paymentType": 1,
    "orderStatus": 40,
    "hasRefund": 0,
    "hasSelf": 2,
    "orderApprovedTime": "1725849618000",
    "orderTimeFrameMinute": 15,
    "orderConfirmTimestamp": "1725849542",
    "orderExpireTimestamp": "1725850518",
    "completedTime": "1725849542000",
    "mark": "",
    "deptPaymentInfo": {
        "id": 0,
        "name": "Automated SPEI - Arcus",
        "logo": "https://xxxx.png",
        "color": "",
        "realName": "HONGYI TANG API",
        "paymentFieldList": [
            {
                "index": 1,
                "textType": 1,
                "title": "Cuenta CLABE",
                "promptText": "Cuenta CLABE de 18 d\u00edgitos",
                "maxLimit": 100,
                "text": "706180101615753153",
                "picUrl": [],
                "tempPicUrl": [],
                "isOptional": false,
                "isAccount": true
            },
            {
                "index": 2,
                "textType": 4,
                "title": "Banco",
                "promptText": "",
                "maxLimit": 100,
                "text": "ARCUS",
                "picUrl": [],
                "tempPicUrl": [],
                "isOptional": false,
                "isAccount": false
            }
        ]
    },
    "mcId": 227,
    "mcName": "HONGYI TANG API",
    "traclingNumber": "",
    "companyName": "API TEST ACCOUNT",
    "createTime": "1725849542000",
    "updateTime": "1725849618000"
}

Sell Order Example

{
    "orderId": "433592805818896384",
    "userId": "1489875904414977024",
    "accountId": "1489875904414977025",
    "cryptoCurrency": "USDT",
    "cryptoLogo": "https://xxx.png",
    "fiatCurrency": "MXN",
    "orderPrice": "19.91",
    "quantity": "0.2",
    "fiatAmount": "3.98",
    "orderType": "SELL",
    "paymentType": 1,
    "orderStatus": 60,
    "hasRefund": 0,
    "hasSelf": 2,
    "orderApprovedTime": "1725853455000",
    "orderTimeFrameMinute": 240,
    "orderConfirmTimestamp": "1725853380",
    "orderExpireTimestamp": "1725867854",
    "completedTime": "1725853833000",
    "mark": "",
    "deptPaymentInfo": {
        "id": 58,
        "name": "Automated SPEI - Arcus",
        "logo": "https://xxx.png",
        "color": "",
        "realName": "",
        "paymentFieldList": []
    },
    "userPaymentInfo": {
        "id": 221,
        "name": "Automated SPEI - Arcus",
        "logo": "https://xxx.png",
        "color": "",
        "realName": "test-api-add",
        "paymentFieldList": [
            {
                "index": 1,
                "textType": 1,
                "title": "Cuenta CLABE",
                "promptText": "Cuenta CLABE de 18 d\u00edgitos",
                "maxLimit": 100,
                "text": "012180015049733082",
                "picUrl": [],
                "tempPicUrl": [],
                "isOptional": false,
                "isAccount": true
            },
            {
                "index": 2,
                "textType": 4,
                "title": "Banco",
                "promptText": "",
                "maxLimit": 100,
                "text": "BBVA",
                "picUrl": [],
                "tempPicUrl": [],
                "isOptional": false,
                "isAccount": false
            }
        ]
    },
    "mcId": 227,
    "mcName": "HONGYI TANG API",
    "traclingNumber": "2024090890706GA27Y4BFDRDHAD3X",
    "companyName": "API TEST ACCOUNT",
    "createTime": "1725853381000",
    "updateTime": "1725853833000"
}

Finish Order

  • Endpoint: /openapi/v1/otc/order/finish

  • Method: POST

  • Authorization: Requires signature and account verification

  • Headers: Requires signature

    • X-BH-APIKEY (string: API key)

  • Request Body:

{
    "orderId": 1123123123,  (number: id of the order)
}

  • Response: JSON containing the result of the order finish.

{
  "result": true,
  "msg": ""
}

Add Order

  • Endpoint: /openapi/v1/otc/order/add

  • Method: POST

  • Authorization: Requires signature and account verification

  • Headers: Requires signature

    • X-BH-APIKEY (string: API key)

  • Request Body:

{       
    "country":"Mexico", (string: name of the country)
    "clientId":"ebab8a9663704e7cbbeb",  (optional, string: id of the client (Unique))
    "mcId":3,  (number: id of the merchant)
    "cryptoCurrency":"USDT", (string: name of the crypto currency)
    "fiatCurrency":"MXN", (string: name of the fiat currency)
    "quantity":100.00, (decimal: order quantity)
    "orderAmount":1000.00, (decimal: order amount)
    "orderType":"SELL",(enum: order type [BUY: buy, SELL: sell])
    "paymentId":"91",  (number: id of the payment method)
}

  • Response: JSON containing the result of the add order operation.

{
    "orderId": 1123123123,  (number: id of the order)
}

Order Invoice Upload

  • Endpoint: /openapi/v1/otc/pic/upload

  • Method: POST

  • Authorization: Requires signature and account verification

  • Headers: Requires signature

    • X-BH-APIKEY (string: API key)

  • Request Parameters: order status is [31: support documents pending], Use this interface to upload invoices

    • orderId (number: id of the order)

    • files (file: Upload multiple file, This parameter does not participate in signature. numbwr max 5. Maxinum upload file size 5MB. format support [jpg,png,jpeg,pdf])

  • Response: JSON containing the result of the order invoice upload.

{
  "result": true,
  "msg": "SUCCESS"
}

6. Deposit Management

Get Deposit Address

  • Endpoint: /openapi/v1/otc/depositAddress

  • Method: GET

  • Authorization: Requires signature and account verification

  • Headers: Requires signature

    • X-BH-APIKEY (string: API key)

  • Request Query Parameters:

    • tokenId (String) - ID of the token

    • chainType (optional, String) - Type of the blockchain (default: "")

  • Response: JSON containing the deposit address.

{
    "allowDeposit": false, (boolean: whether the deposit is allowed)
    "address": "", (string: address of the deposit)
    "addressExt": "", (string: address tag)
    "minQuantity": "", (string: minimum amount of the deposit)
    "needAddressTag": false, (boolean: whether the address tag is required)
    "requiredConfirmNum": 0, (number: required confirmation number)
    "canWithdrawConfirmNum": 0, (number: maximum confirmation number)
    "tokenType": "" (string: type of the token)
}

Example tokenId = USDT ,chainType = ERC20

{
    "allowDeposit": true,
    "address": "0x895f6ab44fb0da1102ab1beb4995e42d74***41",
    "addressExt": "",
    "minQuantity": "5",
    "needAddressTag": false,
    "requiredConfirmNum": 64,
    "canWithdrawConfirmNum": 64,
    "tokenType": "ERC20_TOKEN"
}
Token Id
ChainType

USDT

ERC20

USDT

TRC20

7. Account Management

Get Account Info

  • Endpoint: /openapi/v1/otc/account

  • Method: GET

  • Authorization: Requires signature and account verification

  • Headers: Requires signature

    • X-BH-APIKEY (string: API key)

  • Response: JSON containing account information.

{
  "accountId": 0, (number: id of the account)
  "accountName": "", (string: name of the account)
  "accountType": 0, (number: type of the account)
  "accountIndex": 0, (number: index of the account)
  "canTrade": false, (boolean: whether the account can trade)
  "canDeposit": false, (boolean: whether the account can deposit)
  "canWithdraw": false, (boolean: whether the account can withdraw)
  "balances": [
    {
      "asset": "", (string: name of the asset)
      "assetId": "", (string: id of the asset)
      "assetName": "", (string: name of the asset)
      "total": "", (string: total amount of the asset)
      "free": "", (string: free amount of the asset)
      "locked": "" (string: locked amount of the asset)
    }
  ],
  "updateTime": 0 (number: update time of the account)
}

Example

{
    "balances": [
        {
            "asset": "USDT",
            "assetId": "USDT",
            "assetName": "USDT",
            "total": "0.2982",
            "free": "0.2982",
            "locked": "0"
        }
    ]
}

8. Webhooks

Order Notice Info

  • Method: POST

  • Authorization: Callback message authentication, The joint commission trubit platform obtains the public key.

  • Headers: Requires signature

    • signature (string: To verify that a webhook request is coming from trubit, you can use the signature header. The value of the header is a RSA-SHA256 signature of the request body, Use hexadecimal encoding.)

  • Request Body:

{
    "orderId": "473130522693193728", (number: id of the order)
    "clientId": "ebab8a9663704e7cbbeb",  (string: id of the client)
    "userId": "455472", (number: id of the user)
    "mcSettingsId": "10", (number: id of the merchant)
    "orderType": "SELL", (enum: order type [BUY: buy, SELL: sell])
    "fiatCurrency": "MXN", (string: name of the fiat currency)
    "orderAmount": "99", (decimal: order amount)
    "fiatFee": "0", (decimal: fiat fee)
    "cryptoCurrency": "USDT", (string: name of the crypto currency)
    "quantity": "5", (decimal: order quantity)
    "orderPrice": "19.8158", (decimal: order price)
    "orderStatus": "60", (enum: order status [10: pending, 30: approved, 40: pending payment, 50: paid, 60: released, 70: canceled])
    "createTime": "1735279907000", (string: timestamp of the create time(millisecond))
    "updateTime": "1735280582000", (string: timestamp of the update time(millisecond))
    "timestamp": "1735280582453" (string: timestamp of the update time(millisecond))
}

  • Response:

{
    "callbackStatus": "SUCCESS", (string: callback status, If SUCCESS is returned, the message is successfully notified)
}
PreviousUser GuideNextOther

Last updated