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.
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)
}
]
}
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"
}
]
}
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": "test@gmail.com", (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": "test@gmail.com",(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": "test@gmail.com",(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)
}
]
}
}
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)
}
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)
}
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)
}
