├── README.md ├── restful-api-v4.md ├── restful-api.md ├── samples └── python │ └── v3 │ ├── sample_get_my_open_order.py │ ├── sample_get_order_info.py │ └── sample_place_bid.py └── websocket-api.md /README.md: -------------------------------------------------------------------------------- 1 | # bitkub-official-api-docs 2 | Official Documentation for Bitkub APIs 3 | 4 | * The documentation described here is official. This means the documentation is officially supported and maintained by Bitkub's own development team. 5 | * The use of any other projects is **not supported**; please make sure you are visiting **bitkub/bitkub-official-api-docs**. 6 | 7 | 8 | Name | Description 9 | ------------ | ------------ 10 | [restful-api.md](./restful-api.md) | Details on the RESTful API V3 (/api) 11 | [restful-api-v4.md](./restful-api-v4.md) | Details on the RESTful API V4 (/api) 12 | [websocket-api.md](./websocket-api.md) | Details on the Websocket API (/websocket-api) 13 | -------------------------------------------------------------------------------- /restful-api-v4.md: -------------------------------------------------------------------------------- 1 | # RESTful API for Bitkub V4 (2025-02-03) 2 | 3 | # Announcement 4 | 5 | - Introducing the New Public API v4 for Crypto Endpoints 6 | 7 | # Change log 8 | 9 | - 2025-05-27 Added new Crypto endpoint [GET /api/v4/crypto/compensations](#get-apiv4cryptocompensations) and update api specification for [GET /api/v4/crypto/withdraws](#get-apiv4cryptowithdraws) and [GET /api/v4/crypto/deposits](#get-apiv4cryptodeposits) 10 | - 2025-04-08 Added new error codes: [B1016-CW] Deposit is frozen, [V1015-CW] Coin not found 11 | - 2025-04-03 Added new Crypto endpoint [GET /api/v4/crypto/coins](#get-apiv4cryptocoins) 12 | - 2025-02-03 Introducing Crypto V4 Endpoints 13 | 14 | # Table of contents 15 | 16 | - [Base URL](#base-url) 17 | - [Endpoint types](#endpoint-types) 18 | - [Constructing the request](#constructing-the-request) 19 | - [API documentation](#api-documentation) 20 | - [Error codes](#error-codes) 21 | - [Rate limits](#rate-limits) 22 | 23 | # Base URL 24 | 25 | - The base URL is: https://api.bitkub.com 26 | 27 | # Endpoint types 28 | 29 | ### Secure endpoints V4 30 | 31 | All secure endpoints require [authentication](#constructing-the-request). 32 | 33 | | Crypto V4 Endpoints | Method | Deposit | Withdraw | Trade | 34 | | ------------------------------------------------------------- | ------ | ------- | -------- | ----- | 35 | | [/api/v4/crypto/addresses](#get-apiv4cryptoaddresses) | GET | | | | 36 | | [/api/v4/crypto/addresses](#post-apiv4cryptoaddresses) | POST | ✅ | | | 37 | | [/api/v4/crypto/deposits](#get-apiv4cryptodeposits) | GET | | | | 38 | | [/api/v4/crypto/withdraws](#get-apiv4cryptowithdraws) | GET | | | | 39 | | [/api/v4/crypto/withdraws](#post-apiv4cryptowithdraws) | POST | | ✅ | | 40 | | [/api/v4/crypto/coins](#get-apiv4cryptocoins) | GET | | | | 41 | | [/api/v4/crypto/compensations](#get-apiv4cryptocompensations) | GET | | | | 42 | 43 | # Constructing the request 44 | 45 | ### GET/POST request 46 | 47 | - GET requests require parameters as **query string** in the URL (e.g. ?symbol=BTC&limit=10). 48 | - POST requests require JSON payload (application/json). 49 | 50 | ### Request headers (Secure Endpoints) 51 | 52 | Authentication requires API KEY and API SECRET. Every request to the server must contain the following in the request header: 53 | 54 | - Accept: application/json 55 | - Content-type: application/json 56 | - X-BTK-APIKEY: {YOUR API KEY} 57 | - X-BTK-TIMESTAMP: {Timestamp i.e. 1699376552354 } 58 | - X-BTK-SIGN: [Signature](#signature) 59 | 60 | ### Signature 61 | 62 | Generate the signature from the timestamp, the request method, API path, query parameter, and JSON payload using HMAC SHA-256. Use the API Secret as the secret key for generating the HMAC variant of JSON payload. The signature is in **hex** format. The user has to attach the signature via the Request Header 63 | You must get a new timestamp in millisecond from [/api/v3/servertime](restful-api.md#get-apiv3servertime). The old one is in second. 64 | 65 | #### Example string for signing a signature: 66 | 67 | ```javascript 68 | //Example for Get Method 69 | 1699381086593GET/api/v4/crypto/addresses?symbol=ATOM 70 | 71 | // Example for Post Method 72 | 1699376552354POST/api/v4/crypto/addresses{"symbol":"ATOM","network": "ATOM"} 73 | ``` 74 | 75 | #### Example cURL: 76 | 77 | ```javascript 78 | curl --location 'https://api.bitkub.com/api/v4/crypto/addresses?symbol=ATOM' \ 79 | --header 'X-BTK-TIMESTAMP: 1699381086593' \ 80 | --header 'X-BTK-APIKEY: e286825bda3497ae2d03aa3a30c420d603060cb4edbdd3ec711910c86966e9ba' \ 81 | --header 'X-BTK-SIGN: f5884963865a6e868ddbd58c9fb9ea4bd013076e8a8fa51d38b86c38d707cb8a' 82 | ``` 83 | 84 | ```javascript 85 | curl --location 'https://api.bitkub.com/api/v4/crypto/addresses' \ 86 | --header 'X-BTK-TIMESTAMP: 1699381086593' \ 87 | --header 'X-BTK-APIKEY: e286825bda3497ae2d03aa3a30c420d603060cb4edbdd3ec711910c86966e9ba' \ 88 | --header 'X-BTK-SIGN: f5884963865a6e868ddbd58c9fb9ea4bd013076e8a8fa51d38b86c38d707cb8a' \ 89 | --header 'Content-Type: application/json' \ 90 | --data '{ 91 | "symbol": "ATOM", 92 | "network": "ATOM", 93 | }' 94 | ``` 95 | 96 | # API documentation 97 | 98 | Refer to the following for description of each endpoint 99 | 100 | ### GET /api/v4/crypto/addresses 101 | 102 | #### Description: 103 | 104 | List all crypto addresses (paginated). 105 | 106 | #### Path Params: - 107 | 108 | #### Query Params: 109 | 110 | | Key | Type | Required | Description | 111 | | ------- | ------ | -------- | -------------------------------- | 112 | | page | int | false | Page (default = 1) | 113 | | limit | int | false | Limit (default = 100, max = 200) | 114 | | symbol | String | false | e.g. ATOM | 115 | | network | String | false | e.g. ATOM | 116 | | memo | String | false | e.g. 107467228685 | 117 | 118 | #### Body Params: - 119 | 120 | #### Example cURL: 121 | 122 | ```javascript 123 | curl --location 'https://api.bitkub.com/api/v4/crypto/addresses?symbol=ATOM' \ 124 | --header 'X-BTK-TIMESTAMP: 1699381086593' \ 125 | --header 'X-BTK-APIKEY: e286825bda3497ae2d03aa3a30c420d603060cb4edbdd3ec711910c86966e9ba' \ 126 | --header 'X-BTK-SIGN: f5884963865a6e868ddbd58c9fb9ea4bd013076e8a8fa51d38b86c38d707cb8a' 127 | ``` 128 | 129 | #### Response: 130 | 131 | ```javascript 132 | { 133 | "code": "0", 134 | "message": "success", 135 | "data": { 136 | "page": 1, 137 | "total_page": 1, 138 | "total_item": 2, 139 | "items": [ 140 | { 141 | "symbol": "ATOM", 142 | "network": "ATOM", 143 | "address": "cosmos1jcslcmz2lpsy7uq5u2ktn459qce2chqapey7gh", 144 | "memo": "107467228685", 145 | "created_at": "2022-03-18T05:41:40.199Z" 146 | }, 147 | { 148 | "symbol": "ATOM", 149 | "network": "ATOM", 150 | "address": "cosmos1jcslcmz2lpsy7uq5u2ktn459qce2chqapey7gh", 151 | "memo": "104010164476", 152 | "created_at": "2022-03-18T05:46:34.113Z" 153 | } 154 | ] 155 | } 156 | } 157 | ``` 158 | 159 | ### POST /api/v4/crypto/addresses 160 | 161 | #### Description: 162 | 163 | Generate a new crypto address (if an address exists; will return the existing address). 164 | 165 | #### Required Permission: `is_deposit` 166 | 167 | #### Path Params: - 168 | 169 | #### Query Params: - 170 | 171 | #### Body Params: 172 | 173 | | Key | Type | Required | Description | 174 | | ------- | ------ | -------- | ----------- | 175 | | symbol | String | true | e.g. ATOM | 176 | | network | String | true | e.g. ATOM | 177 | 178 | #### Example cURL: 179 | 180 | ```javascript 181 | curl --location 'https://api.bitkub.com/api/v4/crypto/addresses' \ 182 | --header 'X-BTK-TIMESTAMP: 1699381086593' \ 183 | --header 'X-BTK-APIKEY: e286825bda3497ae2d03aa3a30c420d603060cb4edbdd3ec711910c86966e9ba' \ 184 | --header 'X-BTK-SIGN: f5884963865a6e868ddbd58c9fb9ea4bd013076e8a8fa51d38b86c38d707cb8a' \ 185 | --header 'Content-Type: application/json' \ 186 | --data '{ 187 | "symbol": "ETH", 188 | "network": "ETH", 189 | }' 190 | ``` 191 | 192 | #### Response: 193 | 194 | ```javascript 195 | { 196 | "code": "0", 197 | "message": "success", 198 | "data": [ 199 | { 200 | "symbol": "ETH", 201 | "network": "ETH", 202 | "address": "0x520165471daa570ab632dd504c6af257bd36edfb", 203 | "memo": "" 204 | } 205 | ] 206 | } 207 | ``` 208 | 209 | ### GET /api/v4/crypto/deposits 210 | 211 | #### Description: 212 | 213 | List crypto deposit history. 214 | 215 | #### Path Params: - 216 | 217 | #### Query Params: 218 | 219 | | Key | Type | Required | Description | 220 | | ------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 221 | | page | int | false | Page (default = 1) | 222 | | limit | int | false | Limit (default = 100, max = 200) | 223 | | symbol | String | false | Coin Symbol (e.g. BTC, ETH) | 224 | | status | String | false | Transaction Deposit Status (pending, rejected, complete) | 225 | | created_start | String | false | The start of the time range for the transaction creation timestamp. Only transactions created on or after this timestamp will be included. (e.g. 2025-01-11T10:00:00.000Z) | 226 | | created_end | String | false | The end of the time range for the transaction creation timestamp. Only transactions created on or before this timestamp will be included. (e.g. 2025-01-11T10:00:00.000Z) | 227 | 228 | #### Body Params: - 229 | 230 | #### Example cURL: 231 | 232 | ```javascript 233 | curl --location 'https://api.bitkub.com/api/v4/crypto/deposits?limit=10' \ 234 | --header 'X-BTK-TIMESTAMP: 1699381086593' \ 235 | --header 'X-BTK-APIKEY: e286825bda3497ae2d03aa3a30c420d603060cb4edbdd3ec711910c86966e9ba' \ 236 | --header 'X-BTK-SIGN: f5884963865a6e868ddbd58c9fb9ea4bd013076e8a8fa51d38b86c38d707cb8a' 237 | ``` 238 | 239 | #### Response: 240 | 241 | ```javascript 242 | { 243 | "code": "0", 244 | "message": "success", 245 | "data": { 246 | "page": 1, 247 | "total_page": 1, 248 | "total_item": 1, 249 | "items": [ 250 | { 251 | "hash": "XRPWD0000100276", 252 | "symbol": "XRP", 253 | "network": "XRP", 254 | "amount": "5.75111474", 255 | "from_address": "0xDaCd17d1E77604aaFB6e47F5Ffa1F7E35F83fDa7", 256 | "to_address": "0x2b0849d47a90e3c4784a5b1130a14305a099d828", 257 | "confirmations": 1, 258 | "status": "complete", 259 | "created_at": "2022-03-18T05:41:40.199Z", 260 | "completed_at": "2022-03-18T05:45:50.199Z" 261 | } 262 | ] 263 | } 264 | } 265 | ``` 266 | 267 | ### GET /api/v4/crypto/withdraws 268 | 269 | #### Description: 270 | 271 | List crypto withdrawal history. 272 | 273 | #### Path Params: - 274 | 275 | #### Query Params: 276 | 277 | | Key | Type | Required | Description | 278 | | ------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 279 | | page | int | false | Page (default = 1) | 280 | | limit | int | false | Limit (default = 100, max = 200) | 281 | | symbol | String | false | Coin Symbol (e.g. BTC, ETH) | 282 | | status | String | false | Transaction Withdraw Status (pending, processing, reported, rejected, complete) | 283 | | created_start | String | false | The start of the time range for the transaction creation timestamp. Only transactions created on or after this timestamp will be included. (e.g. 2025-01-11T10:00:00.000Z) | 284 | | created_end | String | false | The end of the time range for the transaction creation timestamp. Only transactions created on or before this timestamp will be included. (e.g. 2025-01-11T10:00:00.000Z) | 285 | 286 | #### Body Params: - 287 | 288 | #### Example cURL: 289 | 290 | ```javascript 291 | curl --location 'https://api.bitkub.com/api/v4/crypto/withdraws?limit=10' \ 292 | --header 'X-BTK-TIMESTAMP: 1699381086593' \ 293 | --header 'X-BTK-APIKEY: e286825bda3497ae2d03aa3a30c420d603060cb4edbdd3ec711910c86966e9ba' \ 294 | --header 'X-BTK-SIGN: f5884963865a6e868ddbd58c9fb9ea4bd013076e8a8fa51d38b86c38d707cb8a' 295 | ``` 296 | 297 | #### Response: 298 | 299 | ```javascript 300 | { 301 | "code": "0", 302 | "message": "success", 303 | "data": { 304 | "page": 1, 305 | "total_page": 1, 306 | "total_item": 2, 307 | "items": [ 308 | { 309 | "txn_id": "RDNTWD0000804050", 310 | "external_ref": "XX_1111111111", 311 | "hash": null, 312 | "symbol": "RDNT", 313 | "network": "ARB", 314 | "amount": "2.00000000", 315 | "fee": "4.36", 316 | "address": "0xDaCd17d1E77604aaFB6e47F5Ffa1F7E35F83fDa7", 317 | "memo": "", 318 | "status": "processing", 319 | "created_at": "2024-09-01T10:02:43.211Z", 320 | "completed_at": "2024-09-01T10:02:45.031Z" 321 | }, 322 | { 323 | "txn_id": "BTCWD1321312683", 324 | "external_ref": "XX_1111111112", 325 | "hash": "0x8891b79c79f0842c9a654db47745fe0291fba222b290d22cabc93f8ae4490303", 326 | "symbol": "BTC", 327 | "network": "BTC", 328 | "amount": "0.10000000", 329 | "fee": "0.0025", 330 | "address": "0xDaCd17d1E77604aaFB6e47F5Ffa1F7E35F83fDa7", 331 | "memo": "", 332 | "status": "complete", 333 | "created_at": "2024-09-01T10:02:43.211Z", 334 | "completed_at": "2024-09-01T10:02:45.031Z" 335 | } 336 | ] 337 | } 338 | } 339 | ``` 340 | 341 | ### POST /api/v4/crypto/withdraws 342 | 343 | #### Description: 344 | 345 | Make a withdrawal to a trusted address. 346 | 347 | #### Required Permission: `is_withdraw` 348 | 349 | #### Path Params: - 350 | 351 | #### Query Params: - 352 | 353 | #### Body Params: 354 | 355 | | Key | Type | Required | Description | 356 | | ------- | ------ | -------- | ------------------------------------- | 357 | | symbol | String | true | Symbol for withdrawal (e.g. BTC, ETH) | 358 | | amount | String | true | Amount to withdraw | 359 | | address | String | true | Address to withdraw | 360 | | memo | String | false | Memo or destination tag to withdraw | 361 | | network | String | true | Network to withdraw | 362 | 363 | #### Example cURL: 364 | 365 | ```javascript 366 | curl --location 'https://api.bitkub.com/api/v4/crypto/withdraws' \ 367 | --header 'X-BTK-TIMESTAMP: 1699381086593' \ 368 | --header 'X-BTK-APIKEY: e286825bda3497ae2d03aa3a30c420d603060cb4edbdd3ec711910c86966e9ba' \ 369 | --header 'X-BTK-SIGN: f5884963865a6e868ddbd58c9fb9ea4bd013076e8a8fa51d38b86c38d707cb8a' \ 370 | --header 'Content-Type: application/json' \ 371 | --data '{ 372 | "symbol": "RDNT", 373 | "amount": "2.00000000", 374 | "address": "0xDaCd17d1E77604aaFB6e47F5Ffa1F7E35F83fDa7", 375 | "network": "ARB" 376 | }' 377 | ``` 378 | 379 | #### Response: 380 | 381 | ```javascript 382 | { 383 | "code": "0", 384 | "message": "success", 385 | "data": { 386 | "txn_id": "RDNTWD0000804050", 387 | "symbol": "RDNT", 388 | "network": "ARB", 389 | "amount": "2.00000000", 390 | "fee": "4.36", 391 | "address": "0xDaCd17d1E77604aaFB6e47F5Ffa1F7E35F83fDa7", 392 | "memo": "", 393 | "created_at": "2024-09-01T10:02:43.211Z" 394 | } 395 | } 396 | ``` 397 | 398 | ### GET /api/v4/crypto/coins 399 | 400 | #### Description: 401 | 402 | Get all coins (available for deposit and withdraw). 403 | 404 | #### Path Params: - 405 | 406 | #### Query Params: 407 | 408 | | Key | Type | Required | Description | 409 | | ------- | ------ | -------- | --------------------------- | 410 | | symbol | String | false | Coin Symbol (e.g. BTC, ETH) | 411 | | network | String | false | Network | 412 | 413 | #### Body Params: - 414 | 415 | #### Example cURL: 416 | 417 | ```javascript 418 | curl --location 'https://api.bitkub.com/api/v4/crypto/coin?symbol=ATOM' \ 419 | --header 'X-BTK-TIMESTAMP: 1699381086593' \ 420 | --header 'X-BTK-APIKEY: e286825bda3497ae2d03aa3a30c420d603060cb4edbdd3ec711910c86966e9ba' \ 421 | --header 'X-BTK-SIGN: f5884963865a6e868ddbd58c9fb9ea4bd013076e8a8fa51d38b86c38d707cb8a' 422 | ``` 423 | 424 | #### Response: 425 | 426 | ```javascript 427 | { 428 | "code": "0", 429 | "message": "success", 430 | "data": { 431 | "items":[ 432 | { 433 | "name": "Bitcoin", 434 | "symbol": "BTC", 435 | "networks": [ 436 | { 437 | "name": "Bitcoin", 438 | "network": "BTC", 439 | "address_regex": "^[13][a-km-zA-HJ-NP-Z1-9]{26,35}$|^(tb1)[0-9A-Za-z]{39,59}$", 440 | "memo_regex": "", 441 | "explorer": "https://www.blockchain.com/btc/tx/", 442 | "contract_address": "", 443 | "withdraw_min": "0.0002", 444 | "withdraw_fee": "0.0001", 445 | "withdraw_internal_min": "", 446 | "withdraw_internal_fee": "", 447 | "withdraw_decimal_places": 8, 448 | "min_confirm": 3, 449 | "decimal": 8, 450 | "deposit_enable": true, 451 | "withdraw_enable": true, 452 | "is_memo": false 453 | } 454 | ], 455 | "deposit_enable": true, 456 | "withdraw_enable": true 457 | } 458 | ] 459 | } 460 | } 461 | ``` 462 | 463 | ### GET /api/v4/crypto/compensations 464 | 465 | #### Description: 466 | 467 | List crypto compensations history. 468 | 469 | #### Path Params: - 470 | 471 | #### Query Params: 472 | 473 | | Key | Type | Required | Description | 474 | | ------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 475 | | page | int | false | Page (default = 1) | 476 | | limit | int | false | Limit (default = 100, max = 200) | 477 | | symbol | String | false | Coin Symbol (e.g. BTC, ETH) | 478 | | type | String | false | Compensation Type (COMPENSATE,DECOMPENSATE) | 479 | | status | String | false | Transaction Compensation Status (PENDING, COMPLETED) | 480 | | created_start | String | false | The start of the time range for the transaction creation timestamp. Only transactions created on or after this timestamp will be included. (e.g. 2025-01-11T10:00:00.000Z) | 481 | | created_end | String | false | The end of the time range for the transaction creation timestamp. Only transactions created on or before this timestamp will be included. (e.g. 2025-01-11T10:00:00.000Z) | 482 | 483 | #### Body Params: - 484 | 485 | #### Example cURL: 486 | 487 | ```javascript 488 | curl --location 'https://api.bitkub.com/api/v4/crypto/compensations?symbol=ATOM' \ 489 | --header 'X-BTK-TIMESTAMP: 1699381086593' \ 490 | --header 'X-BTK-APIKEY: e286825bda3497ae2d03aa3a30c420d603060cb4edbdd3ec711910c86966e9ba' \ 491 | --header 'X-BTK-SIGN: f5884963865a6e868ddbd58c9fb9ea4bd013076e8a8fa51d38b86c38d707cb8a' 492 | ``` 493 | 494 | #### Response: 495 | 496 | ```javascript 497 | { 498 | "code": "0", 499 | "message": "success", 500 | "data": { 501 | "page": 1, 502 | "total_page": 1, 503 | "total_item": 21, 504 | "items": [ 505 | { 506 | "txn_id": "XRPCP1234", 507 | "symbol": "XRP", 508 | "type": "DECOMPENSATE", 509 | "amount": "-1", 510 | "status": "COMPLETED", 511 | "created_at": "2024-02-09T12:00:00.000+00:00", 512 | "completed_at": "2024-02-09T13:00:00.000+00:00" 513 | }, 514 | { 515 | "txn_id": "BLUECP1234", 516 | "symbol": "BLUE", 517 | "type": "COMPENSATE", 518 | "amount": "20", 519 | "status": "COMPLETED", 520 | "created_at": "2025-04-09T18:30:04.000+07:00", 521 | "completed_at": "2025-04-09T18:30:04.000+07:00" 522 | } 523 | ] 524 | } 525 | } 526 | ``` 527 | 528 | ## Additional 529 | 530 | For the use of coins and networks, please use coin or network symbol for any APIs request. Please be cautious of these cryptocurrency when you specified on the request.\ 531 | \ 532 | Please refer to the link below for the available coins and networks.\ 533 | https://www.bitkub.com/fee/cryptocurrency \ 534 | \ 535 | Note the following exceptions for the coin and network: 536 | 537 | | Currency / Network | Symbol | 538 | | ------------------- | ------- | 539 | | Terra Classic(LUNC) | `LUNA` | 540 | | Terra 2.0 (LUNA) | `LUNA2` | 541 | 542 | # Error codes 543 | 544 | The following is the JSON payload for the Response Error: 545 | 546 | ```javascript 547 | { 548 | "code": "V1007-CW", 549 | "message": "Symbol not found", 550 | "data": {} 551 | } 552 | ``` 553 | 554 | ## Status Codes 555 | 556 | #### 200 (OK) 557 | 558 | The request was processed as expected. 559 | 560 | #### 400 (INVALID_REQUEST) 561 | 562 | The request is not well-formed, violates schema, or has incorrect fields. 563 | 564 | #### 401 (NOT_AUTHORIZED) 565 | 566 | The API key doesn't match the signature or have the necessary permissions to perform the request. 567 | 568 | #### 403 (FORBIDDEN) 569 | 570 | The API key doesn't have the necessary permissions to complete the request. 571 | 572 | #### 404 (NOT_FOUND) 573 | 574 | The requested resource doesn't exist. 575 | 576 | #### 5XX 577 | 578 | Internal Server Error. 579 | 580 | | Code | Status | Message | 581 | | -------- | ------ | ---------------------- | 582 | | S1000-CW | 500 | Internal service error | 583 | 584 | ### Business Error 585 | 586 | | Code | Status | Message | 587 | | -------- | ------ | ------------------------------ | 588 | | B1000-CW | 400 | User account is suspended | 589 | | B1001-CW | 400 | Network is disabled | 590 | | B1002-CW | 400 | CWS Wallet not found | 591 | | B1003-CW | 400 | Insufficient balance | 592 | | B1004-CW | 400 | User mismatch condition | 593 | | B1005-CW | 400 | Duplicate key | 594 | | B1006-CW | 400 | Airdrop already transfer | 595 | | B1007-CW | 400 | Symbol required | 596 | | B1008-CW | 400 | Event Symbol mismatched | 597 | | B1009-CW | 400 | Pending withdrawal exists | 598 | | B1010-CW | 400 | User account is frozen | 599 | | B1011-CW | 400 | Withdrawal exceeds daily limit | 600 | | B1012-CW | 400 | Address is not trusted | 601 | | B1013-CW | 400 | Withdrawal is frozen | 602 | | B1014-CW | 400 | Address is not whitelisted | 603 | | B1015-CW | 400 | Request is processing | 604 | | B1016-CW | 400 | Deposit is frozen | 605 | 606 | ### Validation Error 607 | 608 | | Code | Status | Message | 609 | | -------- | ------ | ----------------------------------------- | 610 | | V1000-CW | 404 | User not found | 611 | | V1001-CW | 404 | Asset not found | 612 | | V1002-CW | 404 | Event not found | 613 | | V1003-CW | 400 | Invalid signature | 614 | | V1004-CW | 401 | Signature has expired | 615 | | V1005-CW | 404 | Transaction not found | 616 | | V1006-CW | 400 | Invalid parameter | 617 | | V1007-CW | 404 | Symbol not found | 618 | | V1008-CW | 400 | Address not yet generated for this symbol | 619 | | V1009-CW | 404 | Memo not found for this address | 620 | | V1010-CW | 404 | Address not found | 621 | | V1011-CW | 400 | Address already exists | 622 | | V1012-CW | 400 | Destination address not active | 623 | | V1015-CW | 404 | Coin not found | 624 | 625 | ### Authentication Error 626 | 627 | | Code | Status | Message | 628 | | -------- | ------ | ------------------- | 629 | | A1000-CW | 401 | Unauthorized Access | 630 | | A1001-CW | 403 | Permission denied | 631 | 632 | # Rate limits 633 | 634 | If the request rate exceeds the limit in any endpoints, the request will be blocked for 30 seconds. When blocked, HTTP response is 429 Too Many Requests. The limits apply to individual user accessing the API. **_The rate limit is applied to each endpoint regardless the API version._** 635 | 636 | | Endpoint | Rate Limit | 637 | | ----------------- | ----------------- | 638 | | /api/v4/crypto/\* | 250 req / 10 secs | 639 | -------------------------------------------------------------------------------- /restful-api.md: -------------------------------------------------------------------------------- 1 | 2 | # RESTful API for Bitkub (2025-04-18) 3 | 4 | # Announcement 5 | * API Specifications for Crypto Endpoints, please refer to the documentation here: [Crypto Endpoints](restful-api-v4.md) 6 | * Deprecation of Order Hash for [my-open-orders](#get-apiv3marketmy-open-orders), [my-order-history](#get-apiv3marketmy-order-history), [my-order-info](#get-apiv3marketorder-info), [place-bid](#post-apiv3marketplace-bid), [place-ask](#post-apiv3marketplace-ask), [cancel-order](#post-apiv3marketcancel-order) on 28/02/2025 onwards, More details [here](https://support.bitkub.com/en/support/solutions/articles/151000205895-notice-deprecation-of-order-hash-from-public-api-on-28-02-2025-onwards) 7 | 8 | # Change log 9 | * 2025-01-07 Update FIAT Withdraw error code 10 | * 2025-04-03 Deprecated Crypto Endpoint v3 and Remove from the Document. 11 | * 2024-12-20 Introducing the Enhanced Market Data Endpoint [Ticker, Depth, Bids, Asks, Trades](#non-secure-endpoints-v3) 12 | * 2024-07-25 Deprecated Secure Endpoint V1/V2 and Remove from the Document. 13 | * 2024-07-05 Update rate-limits of place-bid, place-ask, cancel-order, my-open-orders [Rate-Limits](#rate-limits) 14 | * 2024-07-05 Update rate-limits which will be apply on 17 July 2024 [Rate-Limits](#rate-limits) 15 | * 2024-06-11 Updated API request of [POST /api/v3/crypto/internal-withdraw](#post-apiv3cryptointernal-withdraw) and edited API response of [POST /api/v3/crypto/withdraw-history](#post-apiv3cryptowithdraw-history) 16 | * 2024-06-11 Added new error code 58 - Transaction Not Found 17 | * 2024-05-16 Release: Post-Only Functionality Added to [POST /api/v3/market/place-bid](#post-apiv3marketplace-bid) and [POST /api/v3/market/place-ask](#post-apiv3marketplace-ask) 18 | * 2024-03-06 Edited Request field for [POST /api/v3/crypto/withdraw](#post-apiv3cryptowithdraw) 19 | * 2024-02-15 Edited Endpoint permission [Permission Table](#secure-endpoints-v3) 20 | 21 | 22 | # Table of contents 23 | * [Base URL](#base-url) 24 | * [Endpoint types](#endpoint-types) 25 | * [Constructing the request](#constructing-the-request) 26 | * [API documentation](#api-documentation) 27 | * [Error codes](#error-codes) 28 | * [Rate limits](#rate-limits) 29 | 30 | 31 | # Base URL 32 | * The base URL is: https://api.bitkub.com 33 | 34 | # Endpoint types 35 | ### Non-secure endpoints 36 | Our existing endpoints remain available for use. However, for enhanced security and performance, we strongly recommend utilizing the new [Non-Secure Endpoint V3](#non-secure-endpoints-v3). 37 | * [GET /api/status](#get-apistatus) 38 | * [GET /api/servertime](#get-apiservertime) 39 | * [GET /api/market/symbols](#get-apimarketsymbols) 40 | * [GET /api/market/ticker](#get-apimarketticker) 41 | * [GET /api/market/trades](#get-apimarkettrades) 42 | * [GET /api/market/bids](#get-apimarketbids) 43 | * [GET /api/market/asks](#get-apimarketasks) 44 | * [GET /api/market/books](#get-apimarketbooks) 45 | * [GET /api/market/depth](#get-apimarketdepth) 46 | * [GET /tradingview/history](#get-tradingviewhistory) 47 | * [GET /api/v3/servertime](#get-apiv3servertime) 48 | 49 | ### Non-secure endpoints V3 50 | | Market Data Endpoint | Method | 51 | | --------------------------------------------------------------| ------ | 52 | | [GET /api/v3/market/ticker](#get-apiv3marketticker) | GET | 53 | | [GET /api/v3/market/bids](#get-apiv3marketbids) | GET | 54 | | [GET /api/v3/market/asks](#get-apiv3marketasks) | GET | 55 | | [GET /api/v3/market/depth](#get-apiv3marketdepth) | GET | 56 | | [GET /api/v3/market/trades](#get-apiv3markettrades) | GET | 57 | 58 | | Exchange Information Endpoint | Method | 59 | | --------------------------------------------------------------| ------ | 60 | | [GET /api/v3/servertime](#get-apiv3servertime) | GET | 61 | 62 | 63 | ### Secure endpoints V3 64 | All secure endpoints require [authentication](#constructing-the-request). 65 | 66 | | User Endpoint | Method | Trade | Deposit | Withdraw | 67 | | ------------------------------------------------------------------------- | ------ | ----- | ------- | -------- | 68 | | [/api/v3/user/trading-credits](#post-apiv3usertrading-credits) | POST | | | | 69 | | [/api/v3/user/limits](#post-apiv3userlimits) | POST | | | | 70 | | [/api/v3/user/coin-convert-history](#get-apiv3usercoin-convert-history) | GET | | | | 71 | 72 | | Trading Endpoint | Method | Trade | Deposit | Withdraw | 73 | | ------------------------------------------------------------------- | ------ | ----- | ------- | -------- | 74 | | [/api/v3/market/wallet](#post-apiv3marketwallet) | POST | | | | 75 | | [/api/v3/market/balances](#post-apiv3marketbalances) | POST | | | | 76 | | [/api/v3/market/place-bid](#post-apiv3marketplace-bid) | POST | ✅ | | | 77 | | [/api/v3/market/place-ask](#post-apiv3marketplace-ask) | POST | ✅ | | | 78 | | [/api/v3/market/cancel-order](#post-apiv3marketcancel-order) | POST | ✅ | | | 79 | | [/api/v3/market/wstoken](#post-apiv3marketwstoken) | POST | ✅ | | | 80 | | [/api/v3/market/my-open-orders](#get-apiv3marketmy-open-orders) | GET | | | | 81 | | [/api/v3/market/my-order-history](#get-apiv3marketmy-order-history) | GET | | | | 82 | | [/api/v3/market/order-info](#get-apiv3marketorder-info) | GET | | | | 83 | 84 | | Fiat Endpoint | Method | Trade | Deposit | Withdraw | 85 | | ---------------------------------------------------------------- | ------ | ----- | ------- | -------- | 86 | | [/api/v3/fiat/accounts](#post-apiv3fiataccounts) | POST | | | ✅ | 87 | | [/api/v3/fiat/withdraw](#post-apiv3fiatwithdraw) | POST | | | | 88 | | [/api/v3/fiat/deposit-history](#post-apiv3fiatdeposit-history) | POST | | | | 89 | | [/api/v3/fiat/withdraw-history](#post-apiv3fiatwithdraw-history) | POST | | | | 90 | 91 | # Constructing the request 92 | ### GET/POST request 93 | * GET requests require parameters as **query string** in the URL (e.g. ?sym=THB_BTC&lmt=10). 94 | * POST requests require JSON payload (application/json). 95 | 96 | ### Request headers (Secure Endpoints) 97 | Authentication requires API KEY and API SECRET. Every request to the server must contain the following in the request header: 98 | * Accept: application/json 99 | * Content-type: application/json 100 | * X-BTK-APIKEY: {YOUR API KEY} 101 | * X-BTK-TIMESTAMP: {Timestamp i.e. 1699376552354 } 102 | * X-BTK-SIGN: [Signature](#signature) 103 | 104 | ### Payload (POST) 105 | The payload is always JSON. 106 | 107 | ### Signature 108 | Generate the signature from the timestamp, the request method, API path, query parameter, and JSON payload using HMAC SHA-256. Use the API Secret as the secret key for generating the HMAC variant of JSON payload. The signature is in **hex** format. The user has to attach the signature via the Request Header 109 | You must get a new timestamp in millisecond from [/api/v3/servertime](#get-apiv3servertime). The old one is in second. 110 | 111 | #### Example string for signing a signature: 112 | ```javascript 113 | //Example for Get Method 114 | 1699381086593GET/api/v3/market/my-order-history?sym=BTC_THB 115 | 116 | // Example for Post Method 117 | 1699376552354POST/api/v3/market/place-bid{"sym":"thb_btc","amt": 1000,"rat": 10,"typ": "limit"} 118 | ``` 119 | 120 | #### Example cURL: 121 | ```javascript 122 | curl --location 'https://api.bitkub.com/api/v3/market/place-bid' \ 123 | --header 'X-BTK-TIMESTAMP: 1699381086593' \ 124 | --header 'X-BTK-APIKEY: e286825bda3497ae2d03aa3a30c420d603060cb4edbdd3ec711910c86966e9ba' \ 125 | --header 'X-BTK-SIGN: f5884963865a6e868ddbd58c9fb9ea4bd013076e8a8fa51d38b86c38d707cb8a' \ 126 | --header 'Content-Type: application/json' \ 127 | --data '{ 128 | "sym": "thb_btc", 129 | "amt": 1000, 130 | "rat": 10, 131 | "typ": "limit", 132 | }' 133 | ``` 134 | ```javascript 135 | curl --location 'https://api.bitkub.com/api/v3/market/my-open-orders?sym=BTC_THB' \ 136 | --header 'X-BTK-TIMESTAMP: 1699381086593' \ 137 | --header 'X-BTK-APIKEY: e286825bda3497ae2d03aa3a30c420d603060cb4edbdd3ec711910c86966e9ba' \ 138 | --header 'X-BTK-SIGN: f5884963865a6e868ddbd58c9fb9ea4bd013076e8a8fa51d38b86c38d707cb8a' 139 | 140 | ``` 141 | 142 | # API documentation 143 | Refer to the following for description of each endpoint 144 | 145 | ### GET /api/status 146 | 147 | #### Description: 148 | Get endpoint status. When status is not `ok`, it is highly recommended to wait until the status changes back to `ok`. 149 | 150 | #### Query: 151 | - n/a 152 | 153 | #### Response: 154 | ```javascript 155 | [ 156 | { 157 | "name": "Non-secure endpoints", 158 | "status": "ok", 159 | "message": "" 160 | }, 161 | { 162 | "name": "Secure endpoints", 163 | "status": "ok", 164 | "message": "" 165 | } 166 | ] 167 | ``` 168 | 169 | ### GET /api/servertime 170 | 171 | #### Description: 172 | Get server timestamp. This can't use with secure endpoint V3. Please use [/api/v3/servertime](#get-apiv3servertime). 173 | 174 | #### Query: 175 | - n/a 176 | 177 | #### Response: 178 | ```javascript 179 | 1707220534359 180 | ``` 181 | 182 | ### GET /api/v3/servertime 183 | 184 | #### Description: 185 | Get server timestamp. 186 | 187 | #### Query: 188 | - n/a 189 | 190 | #### Response: 191 | ```javascript 192 | 1701251212273 193 | ``` 194 | 195 | ### GET /api/market/symbols 196 | 197 | #### Description: 198 | List all available symbols. 199 | 200 | #### Query: 201 | - n/a 202 | 203 | #### Response: 204 | ```javascript 205 | { 206 | "error": 0, 207 | "result": [ 208 | { 209 | "id": 1, 210 | "symbol": "THB_BTC", 211 | "info": "Thai Baht to Bitcoin" 212 | }, 213 | { 214 | "id": 2, 215 | "symbol": "THB_ETH", 216 | "info": "Thai Baht to Ethereum" 217 | } 218 | ] 219 | } 220 | ``` 221 | 222 | ### GET /api/market/ticker 223 | 224 | #### Description: 225 | Get ticker information. 226 | 227 | #### Query: 228 | * `sym` **string** The symbol (optional) 229 | * e.g. thb_btc 230 | 231 | #### Response: 232 | ```javascript 233 | { 234 | "THB_BTC": { 235 | "id": 1, 236 | "last": 216415.00, 237 | "lowestAsk": 216678.00, 238 | "highestBid": 215000.00, 239 | "percentChange": 1.91, 240 | "baseVolume": 71.02603946, 241 | "quoteVolume": 15302897.99, 242 | "isFrozen": 0, 243 | "high24hr": 221396.00, 244 | "low24hr": 206414.00 245 | }, 246 | "THB_ETH": { 247 | "id": 2, 248 | "last": 11878.00, 249 | "lowestAsk": 12077.00, 250 | "highestBid": 11893.00, 251 | "percentChange": -0.49, 252 | "baseVolume": 455.17839270, 253 | "quoteVolume": 5505664.42, 254 | "isFrozen": 0, 255 | "high24hr": 12396.00, 256 | "low24hr": 11645.00 257 | } 258 | } 259 | ``` 260 | 261 | ### GET /api/market/trades 262 | 263 | #### Description: 264 | List recent trades. 265 | 266 | #### Query: 267 | * `sym` **string** The symbol (e.g. thb_btc) 268 | * `lmt` **int** No. of limit to query recent trades 269 | 270 | #### Response: 271 | ```javascript 272 | { 273 | "error": 0, 274 | "result": [ 275 | [ 276 | 1529516287, // timestamp 277 | 10000.00, // rate 278 | 0.09975000, // amount 279 | "BUY" // side 280 | ] 281 | ] 282 | } 283 | ``` 284 | 285 | ### GET /api/market/bids 286 | #### Description: 287 | List open buy orders. 288 | 289 | #### Query: 290 | * `sym` **string** The symbol (e.g. thb_btc) 291 | * `lmt` **int** No. of limit to query open buy orders 292 | 293 | #### Response: 294 | ```javascript 295 | { 296 | "error": 0, 297 | "result": [ 298 | [ 299 | "1", // order id 300 | 1529453033, // timestamp 301 | 997.50, // volume 302 | 10000.00, // rate 303 | 0.09975000 // amount 304 | ] 305 | ] 306 | } 307 | 308 | ``` 309 | 310 | ### GET /api/market/asks 311 | 312 | 313 | #### Description: 314 | List open sell orders. 315 | 316 | #### Query: 317 | * `sym` **string** The symbol (e.g. thb_btc) 318 | * `lmt` **int** No. of limit to query open sell orders 319 | 320 | #### Response: 321 | ```javascript 322 | { 323 | "error": 0, 324 | "result": [ 325 | [ 326 | "680", // order id 327 | 1529491094, // timestamp 328 | 997.50, // volume 329 | 10000.00, // rate 330 | 0.09975000 // amount 331 | ] 332 | ] 333 | } 334 | ``` 335 | 336 | ### GET /api/market/books 337 | #### Description: 338 | List all open orders. 339 | 340 | #### Query: 341 | * `sym` **string** The symbol (e.g. thb_btc) 342 | * `lmt` **int** No. of limit to query open orders 343 | 344 | #### Response: 345 | ```javascript 346 | { 347 | "error": 0, 348 | "result": { 349 | "bids": [ 350 | [ 351 | "1", // order id 352 | 1529453033, // timestamp 353 | 997.50, // volume 354 | 10000.00, // rate 355 | 0.09975000 // amount 356 | ] 357 | ], 358 | "asks": [ 359 | [ 360 | "680", // order id 361 | 1529491094, // timestamp 362 | 997.50, // volume 363 | 10000.00, // rate 364 | 0.09975000 // amount 365 | ] 366 | ] 367 | } 368 | } 369 | ``` 370 | 371 | ### GET /tradingview/history 372 | #### Description: 373 | Get historical data for TradingView chart. 374 | 375 | #### Query: 376 | * `symbol` **string** The symbol (e.g. BTC_THB) 377 | * `resolution` **string** Chart resolution (1, 5, 15, 60, 240, 1D) 378 | * `from` **int** Timestamp of the starting time (e.g. 1633424427) 379 | * `to` **int** Timestamp of the ending time (e.g. 1633427427) 380 | 381 | #### Response: 382 | ```javascript 383 | { 384 | "c": [ 385 | 1685000, 386 | 1680699.95, 387 | 1688998.99, 388 | 1692222.22 389 | ], 390 | "h": [ 391 | 1685000, 392 | 1685000, 393 | 1689000, 394 | 1692222.22 395 | ], 396 | "l": [ 397 | 1680053.22, 398 | 1671000, 399 | 1680000, 400 | 1684995.07 401 | ], 402 | "o": [ 403 | 1682500, 404 | 1685000, 405 | 1680100, 406 | 1684995.07 407 | ], 408 | "s": "ok", 409 | "t": [ 410 | 1633424400, 411 | 1633425300, 412 | 1633426200, 413 | 1633427100 414 | ], 415 | "v": [ 416 | 4.604352630000001, 417 | 8.530631670000005, 418 | 4.836581560000002, 419 | 2.8510189200000022 420 | ] 421 | } 422 | ``` 423 | 424 | ### GET /api/market/depth 425 | 426 | #### Description: 427 | Get depth information. 428 | 429 | #### Query: 430 | * `sym` **string** The symbol (e.g. thb_btc) 431 | * `lmt` **int** Depth size 432 | 433 | #### Response: 434 | ```javascript 435 | { 436 | "asks": [ 437 | [ 438 | 262600, 439 | 0.61905798 440 | ], 441 | [ 442 | 263000, 443 | 0.00210796 444 | ], 445 | [ 446 | 263200, 447 | 0.89555545 448 | ], 449 | [ 450 | 263422.5, 451 | 0.03796183 452 | ], 453 | [ 454 | 263499, 455 | 0.4123439 456 | ] 457 | ], 458 | "bids": [ 459 | [ 460 | 262510, 461 | 0.38038703 462 | ], 463 | [ 464 | 262100.01, 465 | 1.22519999 466 | ], 467 | [ 468 | 262100, 469 | 0.00381533 470 | ], 471 | [ 472 | 262024.88, 473 | 0.00352718 474 | ], 475 | [ 476 | 262001, 477 | 0.09999961 478 | ] 479 | ] 480 | } 481 | ``` 482 | 483 | 484 | ## Market Data Endpoint 485 | 486 | ### GET /api/v3/market/ticker 487 | 488 | ### Description: 489 | Get ticker information. 490 | 491 | ### Query (URL): 492 | * `sym` **string** The symbol (e.g. btc_thb) 493 | 494 | ### Response: 495 | ```javascript 496 | [ 497 | { 498 | "symbol": "ADA_THB", 499 | "base_volume": "1875227.0489781", 500 | "high_24_hr": "38", 501 | "highest_bid": "37.33", 502 | "last": "37.36", 503 | "low_24_hr": "35.76", 504 | "lowest_ask": "37.39", 505 | "percent_change": "2.69", 506 | "quote_volume": "69080877.73" 507 | }, 508 | { 509 | "symbol": "CRV_THB", 510 | "base_volume": "1811348.93318162", 511 | "high_24_hr": "39", 512 | "highest_bid": "38.4", 513 | "last": "38.42", 514 | "low_24_hr": "35.51", 515 | "lowest_ask": "38.42", 516 | "percent_change": "4.52", 517 | "quote_volume": "67340316.65" 518 | } 519 | ] 520 | ``` 521 | 522 | 523 | ### GET /api/v3/market/bids 524 | #### Description: 525 | List open buy orders. 526 | 527 | #### Query: 528 | * `sym` **string** The symbol (e.g. btc_thb) 529 | * `lmt` **int** No. of limit to query open buy orders 530 | 531 | #### Response: 532 | ```javascript 533 | { 534 | "error": 0, 535 | "result": [ 536 | { 537 | "order_id": "365357265", 538 | "price": "3330100.43", 539 | "side": "buy", 540 | "size": "0.87901418", 541 | "timestamp": 1734714699000, 542 | "volume": "2927205.5" 543 | }, 544 | { 545 | "order_id": "365357190", 546 | "price": "3330100.13", 547 | "side": "buy", 548 | "size": "0.00314952", 549 | "timestamp": 1734689476000, 550 | "volume": "10488.24" 551 | } 552 | ] 553 | } 554 | 555 | ``` 556 | 557 | ### GET /api/v3/market/asks 558 | 559 | 560 | #### Description: 561 | List open sell orders. 562 | 563 | #### Query: 564 | * `sym` **string** The symbol (e.g. btc_thb) 565 | * `lmt` **int** No. of limit to query open sell orders 566 | 567 | #### Response: 568 | ```javascript 569 | { 570 | "error": 0, 571 | "result": [ 572 | { 573 | "order_id": "303536416", 574 | "price": "3334889", 575 | "side": "sell", 576 | "size": "0.01289714", 577 | "timestamp": 1734689550000, 578 | "volume": "42903" 579 | }, 580 | { 581 | "order_id": "303536239", 582 | "price": "3334889.31", 583 | "side": "sell", 584 | "size": "0.129", 585 | "timestamp": 1734714713000, 586 | "volume": "430200.72" 587 | } 588 | ] 589 | } 590 | ``` 591 | 592 | ### GET /api/v3/market/depth 593 | 594 | #### Description: 595 | Get depth information. 596 | 597 | #### Query: 598 | * `sym` **string** The symbol (e.g. btc_thb) 599 | * `lmt` **int** Depth size 600 | 601 | #### Response: 602 | ```javascript 603 | { 604 | "error": 0, 605 | "result": { 606 | "asks": [ 607 | [ 608 | 3338932.98, // price 609 | 0.00619979, //size 610 | ], 611 | [ 612 | 3341006.36, // price 613 | 0.00134854 //size 614 | ] 615 | ], 616 | "bids": [ 617 | [ 618 | 3334907.27, // price 619 | 0.00471255 //size 620 | ], 621 | [ 622 | 3334907.26, // price 623 | 0.36895805 //size 624 | ] 625 | ] 626 | } 627 | } 628 | ``` 629 | 630 | ### GET /api/v3/market/trades 631 | 632 | #### Description: 633 | List recent trades. 634 | 635 | #### Query: 636 | * `sym` **string** The symbol (e.g. btc_thb) 637 | * `lmt` **int** No. of limit to query recent trades 638 | 639 | #### Response: 640 | ```javascript 641 | { 642 | "error": 0, 643 | "result": [ 644 | [ 645 | 1734661894000, 646 | 3367353.98, 647 | 0.00148484, 648 | "BUY" 649 | ], 650 | [ 651 | 1734661893000, 652 | 3367353.98, 653 | 0.00029622, 654 | "BUY" 655 | ] 656 | ] 657 | } 658 | ``` 659 | ## Trading Endpoint V3 660 | 661 | 662 | ### POST /api/v3/market/wallet 663 | 664 | #### Description: 665 | Get user available balances (for both available and reserved balances please use [POST /api/v3/market/balances](#post-apiv3marketbalances)). 666 | 667 | #### Query: 668 | - n/a 669 | 670 | #### Response: 671 | ```javascript 672 | { 673 | "error": 0, 674 | "result": { 675 | "THB": 188379.27, 676 | "BTC": 8.90397323, 677 | "ETH": 10.1 678 | } 679 | } 680 | ``` 681 | ### POST /api/v3/user/trading-credits 682 | 683 | ### Description: 684 | Check trading credit balance. 685 | 686 | ### Query (URL): 687 | - 688 | 689 | ### Response: 690 | ```javascript 691 | { 692 | "error": 0, 693 | "result": 1000 694 | } 695 | ``` 696 | 697 | ### POST /api/v3/market/place-bid 698 | 699 | #### Description: 700 | Create a buy order. 701 | 702 | #### Body: 703 | * `sym` **string** The symbol you want to trade (e.g. btc_thb). 704 | * `amt` **float** Amount you want to spend with no trailing zero (e.g. 1000.00 is invalid, 1000 is ok) 705 | * `rat` **float** Rate you want for the order with no trailing zero (e.g. 1000.00 is invalid, 1000 is ok) 706 | * `typ` **string** Order type: limit or market (for market order, please specify rat as 0) 707 | * `client_id` **string** your id for reference ( not required ) 708 | * `post_only` **bool** Postonly flag: true or false ( not required ) 709 | 710 | #### Response: 711 | ```javascript 712 | { 713 | "error": 0, 714 | "result": { 715 | "id": "1", // order id 716 | "typ": "limit", // order type 717 | "amt": 1000, // spending amount 718 | "rat": 15000, // rate 719 | "fee": 2.5, // fee 720 | "cre": 2.5, // fee credit used 721 | "rec": 0.06666666, // amount to receive 722 | "ts": "1707220636" // timestamp 723 | "ci": "input_client_id" // input id for reference 724 | } 725 | } 726 | ``` 727 | 728 | ### POST /api/v3/market/place-ask 729 | 730 | #### Description: 731 | Create a sell order. 732 | 733 | #### Body: 734 | * `sym` **string** The symbol. The symbol you want to trade (e.g. btc_thb). 735 | * `amt` **float** Amount you want to sell with no trailing zero (e.g. 0.10000000 is invalid, 0.1 is ok) 736 | * `rat` **float** Rate you want for the order with no trailing zero (e.g. 1000.00 is invalid, 1000 is ok) 737 | * `typ` **string** Order type: limit or market (for market order, please specify rat as 0) 738 | * `client_id` **string** your id for reference ( not required ) 739 | * `post_only` **bool** Postonly flag: true or false ( not required ) 740 | 741 | 742 | #### Response: 743 | ```javascript 744 | { 745 | "error": 0, 746 | "result": { 747 | "id": "1", // order id 748 | "typ": "limit", // order type 749 | "amt": 1.00000000, // selling amount 750 | "rat": 15000, // rate 751 | "fee": 37.5, // fee 752 | "cre": 37.5, // fee credit used 753 | "rec": 15000, // amount to receive 754 | "ts": "1533834844" // timestamp 755 | "ci": "input_client_id" // input id for reference 756 | } 757 | } 758 | ``` 759 | 760 | ### POST /api/v3/market/cancel-order 761 | 762 | ### Description: 763 | Cancel an open order. 764 | 765 | ### Body: 766 | * `sym` **string** The symbol. ***Please note that the current endpoint requires the symbol thb_btc. However, it will be changed to btc_thb soon and you will need to update the configurations accordingly for uninterrupted API functionality.*** 767 | * `id` **string** Order id you wish to cancel 768 | * `sd` **string** Order side: buy or sell 769 | 770 | ### Response: 771 | ```javascript 772 | { 773 | "error": 0 774 | } 775 | ``` 776 | ### POST /api/v3/market/balances 777 | 778 | #### Description: 779 | Get balances info: this includes both available and reserved balances. 780 | 781 | #### Query: 782 | - n/a 783 | 784 | #### Response: 785 | ```javascript 786 | { 787 | "error": 0, 788 | "result": { 789 | "THB": { 790 | "available": 188379.27, 791 | "reserved": 0 792 | }, 793 | "BTC": { 794 | "available": 8.90397323, 795 | "reserved": 0 796 | }, 797 | "ETH": { 798 | "available": 10.1, 799 | "reserved": 0 800 | } 801 | } 802 | } 803 | ``` 804 | ### GET /api/v3/market/my-open-orders 805 | 806 | ### Description: 807 | List all open orders of the given symbol. 808 | 809 | ### Query: 810 | * `sym` **string** The symbol (e.g. btc_thb) 811 | 812 | ### Response: 813 | ```javascript 814 | { 815 | "error": 0, 816 | "result": [ 817 | { // Example of sell order 818 | "id": "2", // order id 819 | "side": "sell", // order side 820 | "type": "limit", // order type 821 | "rate": "15000", // rate 822 | "fee": "35.01", // fee 823 | "credit": "35.01", // credit used 824 | "amount": "0.93333334", // amount of crypto quantity 825 | "receive": "14000", // amount of THB 826 | "parent_id": "1", // parent order id 827 | "super_id": "1", // super parent order id 828 | "client_id": "client_id" // client id 829 | "ts": 1702543272000 // timestamp 830 | }, 831 | { // Example of buy order 832 | "id": "278465822", 833 | "side": "buy", 834 | "type": "limit", 835 | "rate": "10", 836 | "fee": "0.25", 837 | "credit": "0", 838 | "amount": "100", // amount of THB 839 | "receive": "9.975", // amount of crypto quantity 840 | "parent_id": "0", 841 | "super_id": "0", 842 | "client_id": "client_id", 843 | "ts": 1707220636000 844 | }, 845 | ] 846 | } 847 | ``` 848 | Note : The ```client_id``` of this API response is the input body field name ```client_id``` , was inputted by the user of APIs 849 | * [api/v3/market/place-bid](#post-apiv3marketplace-bid) 850 | * [api/v3/market/place-ask](#post-apiv3marketplace-ask) 851 | 852 | 853 | 854 | ### GET /api/v3/market/my-order-history 855 | 856 | ### Description: 857 | List all orders that have already matched. 858 | 859 | ### Query: 860 | * `sym` **string** The symbol (e.g. btc_thb) 861 | * `p` **int** Page (optional) 862 | * `lmt` **int** Limit (optional) 863 | * `start` **int** Start timestamp (optional) 864 | * `end` **int** End timestamp (optional) 865 | 866 | ### Response: 867 | ```javascript 868 | { 869 | "error": 0, 870 | "result": [ 871 | { 872 | "txn_id": "BTCSELL0021206932", 873 | "order_id": "241407793", 874 | "parent_order_id": "0", 875 | "super_order_id": "0", 876 | "client_id": "", 877 | "taken_by_me": false, 878 | "is_maker": false, 879 | "side": "sell", 880 | "type": "market", 881 | "rate": "1525096.27", 882 | "fee": "0.04", 883 | "credit": "0", 884 | "amount": "0.00001", // crypto amount 885 | "ts": 1707221396584 886 | }, 887 | { 888 | "txn_id": "BTCBUY0021182426", 889 | "order_id": "277231907", 890 | "parent_order_id": "0", 891 | "super_order_id": "0", 892 | "client_id": "client_id", 893 | "taken_by_me": false, 894 | "is_maker": false, 895 | "side": "buy", 896 | "type": "market", 897 | "rate": "1497974.74", 898 | "fee": "0.03", 899 | "credit": "0", 900 | "amount": "11", // THB amount 901 | "ts": 1706775718739 902 | } 903 | ], 904 | "pagination": { 905 | "page": 2, 906 | "last": 3, 907 | "next": 3, 908 | "prev": 1 909 | } 910 | } 911 | ``` 912 | 913 | ### GET /api/v3/market/order-info 914 | ### Description: 915 | Get information regarding the specified order. 916 | 917 | ### Query: 918 | * `sym` **string** The symbol (e.g. btc_thb) 919 | * `id` **string** Order id 920 | * `sd` **string** Order side: buy or sell 921 | 922 | ### Response: 923 | ```javascript 924 | { 925 | "error": 0, 926 | "result": { 927 | "id": "289", // order id 928 | "first": "289", // first order id 929 | "parent": "0", // parent order id 930 | "last": "316", // last order id 931 | "client_id": "", // your id for reference 932 | "post_only": false, // post_only: true, false 933 | "amount": "4000", // order amount THB amount if it Buy side. And Crypto Amount if it sell side 934 | "rate": 291000, // order rate 935 | "fee": 10, // order fee 936 | "credit": 10, // order fee credit used 937 | "filled": 3999.97, // filled amount 938 | "total": 4000, // total amount 939 | "status": "filled", // order status: filled, unfilled, cancelled 940 | "partial_filled": false, // true when order has been partially filled, false when not filled or fully filled 941 | "remaining": 0, // remaining amount to be executed 942 | "history": [ 943 | { 944 | "amount": 98.14848, 945 | "credit": 0.25, 946 | "fee": 0.25, 947 | "id": "289", 948 | "rate": 291000, 949 | "timestamp": 1702466375000, 950 | "txn_id": "BTCBUY0003372258" 951 | } 952 | ] 953 | } 954 | } 955 | ``` 956 | 957 | ## Fiat Endpoint 958 | 959 | ### POST /api/v3/fiat/accounts 960 | 961 | ### Description: 962 | List all approved bank accounts. 963 | 964 | ### Query (URL): 965 | * `p` **int** Page (optional) 966 | * `lmt` **int** Limit (optional) 967 | 968 | ### Response: 969 | ```javascript 970 | { 971 | "error": 0, 972 | "result": [ 973 | { 974 | "id": "7262109099", 975 | "bank": "Kasikorn Bank", 976 | "name": "Somsak", 977 | "time": 1570893867 978 | } 979 | ], 980 | "pagination": { 981 | "page": 1, 982 | "last": 1 983 | } 984 | } 985 | ``` 986 | 987 | ### POST /api/v3/fiat/withdraw 988 | 989 | ### Description: 990 | Make a withdrawal to an **approved** bank account. 991 | 992 | ### Query: 993 | * `id` **string** Bank account id 994 | * `amt` **float** Amount you want to withdraw 995 | 996 | ### Response: 997 | ```javascript 998 | { 999 | "error": 0, 1000 | "result": { 1001 | "txn": "THBWD0000012345", // local transaction id 1002 | "acc": "7262109099", // bank account id 1003 | "cur": "THB", // currency 1004 | "amt": 21, // withdraw amount 1005 | "fee": 20, // withdraw fee 1006 | "rec": 1, // amount to receive 1007 | "ts": 1569999999 // timestamp 1008 | } 1009 | } 1010 | ``` 1011 | 1012 | ### POST /api/v3/fiat/deposit-history 1013 | 1014 | ### Description: 1015 | List fiat deposit history. 1016 | 1017 | ### Query (URL): 1018 | * `p` **int** Page (optional) 1019 | * `lmt` **int** Limit (optional) 1020 | 1021 | ### Response: 1022 | ```javascript 1023 | { 1024 | "error": 0, 1025 | "result": [ 1026 | { 1027 | "txn_id": "THBDP0000012345", 1028 | "currency": "THB", 1029 | "amount": 5000.55, 1030 | "status": "complete", 1031 | "time": 1570893867 1032 | } 1033 | ], 1034 | "pagination": { 1035 | "page": 1, 1036 | "last": 1 1037 | } 1038 | } 1039 | ``` 1040 | 1041 | ### POST /api/v3/fiat/withdraw-history 1042 | 1043 | ### Description: 1044 | List fiat withdrawal history. 1045 | 1046 | ### Query (URL): 1047 | * `p` **int** Page (optional) 1048 | * `lmt` **int** Limit (optional) 1049 | 1050 | ### Response: 1051 | ```javascript 1052 | { 1053 | "error":0, 1054 | "result": [ 1055 | { 1056 | "txn_id": "THBWD0000012345", 1057 | "currency": "THB", 1058 | "amount": "21", 1059 | "fee": 20, 1060 | "status": "complete", 1061 | "time": 1570893493 1062 | } 1063 | ], 1064 | "pagination": { 1065 | "page": 1, 1066 | "last": 1 1067 | } 1068 | } 1069 | ``` 1070 | 1071 | ## User information Endpoint 1072 | 1073 | ### POST /api/v3/user/limits 1074 | 1075 | ### Description: 1076 | Check deposit/withdraw limitations and usage. 1077 | 1078 | ### Query (URL): 1079 | - 1080 | 1081 | ### Response: 1082 | ```javascript 1083 | { 1084 | "error": 0, 1085 | "result": { 1086 | "limits": { // limitations by kyc level 1087 | "crypto": { 1088 | "deposit": 0.88971929, // BTC value equivalent 1089 | "withdraw": 0.88971929 // BTC value equivalent 1090 | }, 1091 | "fiat": { 1092 | "deposit": 200000, // THB value equivalent 1093 | "withdraw": 200000 // THB value equivalent 1094 | } 1095 | }, 1096 | "usage": { // today's usage 1097 | "crypto": { 1098 | "deposit": 0, // BTC value equivalent 1099 | "withdraw": 0, // BTC value equivalent 1100 | "deposit_percentage": 0, 1101 | "withdraw_percentage": 0, 1102 | "deposit_thb_equivalent": 0, // THB value equivalent 1103 | "withdraw_thb_equivalent": 0 // THB value equivalent 1104 | }, 1105 | "fiat": { 1106 | "deposit": 0, // THB value equivalent 1107 | "withdraw": 0, // THB value equivalent 1108 | "deposit_percentage": 0, 1109 | "withdraw_percentage": 0 1110 | } 1111 | }, 1112 | "rate": 224790 // current THB rate used to calculate 1113 | } 1114 | } 1115 | ``` 1116 | ### GET /api/v3/user/coin-convert-history 1117 | ### Description: 1118 | List all coin convert histories (paginated). 1119 | 1120 | ### Query (URL): 1121 | * `p` **int** Page default = 1 (optional) 1122 | * `lmt` **int** Limit default = 100 (optional) 1123 | * `sort` **int** Sort [1, -1] default = 1 (optional) 1124 | * `status` **string** Status [success, fail, all] (default = all) (optional) 1125 | * `sym` **string** The symbol (optional) 1126 | * e.g. KUB 1127 | * `start` **int** Start timestamp (optional) 1128 | * `end` **int** End timestamp (optional) 1129 | 1130 | 1131 | ### Response: 1132 | ```javascript 1133 | { 1134 | "error": 0, 1135 | "result": [ 1136 | { 1137 | "transaction_id": "67ef4ca7ddb88f34ce16a126", 1138 | "status": "success", 1139 | "amount": "0.0134066", 1140 | "from_currency": "KUB", 1141 | "trading_fee_received": "1.34", 1142 | "timestamp": 1743761171000 1143 | }, 1144 | { 1145 | "transaction_id": "6707a7426fb3370035725c03", 1146 | "status": "fail", 1147 | "amount": "0.000006", 1148 | "from_currency": "KUB", 1149 | "trading_fee_received": "0", 1150 | "timestamp": 1728580016000 1151 | } 1152 | ], 1153 | "pagination": { 1154 | "page": 1, 1155 | "last": 12, 1156 | "next": 2 1157 | } 1158 | } 1159 | ``` 1160 | 1161 | 1162 | # Error codes 1163 | Refer to the following descriptions: 1164 | 1165 | | Code | Message | Description | 1166 | | ---- | ---------------------- | ---------------------------------------------------------- | 1167 | | 0 | | No error | 1168 | | 1 | | Invalid JSON payload | 1169 | | 2 | | Missing X-BTK-APIKEY | 1170 | | 3 | | Invalid API key | 1171 | | 4 | | API pending for activation | 1172 | | 5 | | IP not allowed | 1173 | | 6 | | Missing / invalid signature | 1174 | | 7 | | Missing timestamp | 1175 | | 8 | | Invalid timestamp | 1176 | | 9 | | • Invalid user
• User not found
• Freeze withdrawal
• User is not allowed to perform this action within the last 24 hours
• User has suspicious withdraw crypto txn | 1177 | | 10 | | • Invalid parameter
• Invalid response: Code not found in response
• Validate params
• Default | 1178 | | 11 | | Invalid symbol | 1179 | | 12 | | • Invalid amount
• Withdrawal amount is below the minimum threshold | 1180 | | 13 | | Invalid rate | 1181 | | 14 | | Improper rate | 1182 | | 15 | | Amount too low | 1183 | | 16 | | Failed to get balance | 1184 | | 17 | | Wallet is empty | 1185 | | 18 | | Insufficient balance | 1186 | | 19 | | Failed to insert order into db | 1187 | | 20 | | Failed to deduct balance | 1188 | | 21 | | Invalid order for cancellation (Unable to find OrderID or Symbol.) | 1189 | | 22 | | Invalid side | 1190 | | 23 | | Failed to update order status | 1191 | | 24 | | • Invalid order for lookup
• Invalid kyc level | 1192 | | 25 | | KYC level 1 is required to proceed | 1193 | | 30 | | Limit exceeds | 1194 | | 40 | | Pending withdrawal exists | 1195 | | 41 | | Invalid currency for withdrawal | 1196 | | 42 | | Address is not in whitelist | 1197 | | 43 | | • Failed to deduct crypto
• Insufficient balance
• Deduct balance failed | 1198 | | 44 | | Failed to create withdrawal record | 1199 | | 47 | | Withdrawal amount exceeds the maximum limit | 1200 | | 48 | | • Invalid bank account
• User bank id is not found
• User bank is unavailable | 1201 | | 49 | | Bank limit exceeds | 1202 | | 50 | | • Pending withdrawal exists
• Cannot perform the action due to pending transactions | 1203 | | 51 | | Withdrawal is under maintenance | 1204 | | 52 | | Invalid permission | 1205 | | 53 | | Invalid internal address | 1206 | | 54 | | Address has been deprecated | 1207 | | 55 | | Cancel only mode | 1208 | | 56 | | User has been suspended from purchasing | 1209 | | 57 | | User has been suspended from selling | 1210 | | 58 | | ~~Transaction not found~~
User bank is not verified | 1211 | | 90 | | Server error (please contact support) | 1212 | 1213 | # Rate limits 1214 | If the request rate exceeds the limit in any endpoints, the request will be blocked for 30 seconds. When blocked, HTTP response is 429 Too Many Requests. The limits apply to individual user accessing the API. ***The rate limit is applied to each endpoint regardless the API version.*** 1215 | 1216 | | Endpoint | Rate Limit | 1217 | | ---------------------------- | ---------------- | 1218 | | /api/market/ticker | 100 req/sec | 1219 | | /api/market/depth | 10 req/sec | 1220 | | /api/market/symbols | 100 req/sec | 1221 | | /api/market/trades | 100 req/sec | 1222 | | /api/market/bids | 100 req/sec | 1223 | | /api/market/asks | 100 req/sec | 1224 | | /api/market/books | 100 req/sec | 1225 | | /api/market/order-info | 100 req/sec | 1226 | | /api/market/my-open-orders | 150 req/sec | 1227 | | /api/market/my-order-history | 100 req/sec | 1228 | | /api/market/place-bid | 150 req/sec | 1229 | | /api/market/place-ask | 150 req/sec | 1230 | | /api/market/cancel-order | 200 req/sec | 1231 | | /api/market/balances | 150 req/sec | 1232 | | /api/market/wallet | 150 req/sec | 1233 | | /api/servertime | 2,000 req/10secs | 1234 | | /api/status | 100 req/sec | 1235 | | /api/fiat/* | 20 req/sec | 1236 | | /api/user/* | 20 req/sec | 1237 | | /tradingview/* | 100 req/sec | 1238 | -------------------------------------------------------------------------------- /samples/python/v3/sample_get_my_open_order.py: -------------------------------------------------------------------------------- 1 | import hashlib 2 | import hmac 3 | import json 4 | import time 5 | import requests 6 | 7 | def gen_sign(api_secret, payload_string=None): 8 | return hmac.new(api_secret.encode('utf-8'), payload_string.encode('utf-8'), hashlib.sha256).hexdigest() 9 | 10 | def gen_query_param(url, query_param): 11 | req = requests.PreparedRequest() 12 | req.prepare_url(url, query_param) 13 | return req.url.replace(url,"") 14 | 15 | if __name__ == '__main__': 16 | 17 | host = 'https://api.bitkub.com' 18 | path = '/api/v3/market/my-open-orders' 19 | api_key = 'your API key' 20 | api_secret = 'your API SECRET' 21 | 22 | ts = str(round(time.time() * 1000)) 23 | param = { 24 | 'sym':"btc_thb" 25 | } 26 | query_param = gen_query_param(host+path, param) 27 | 28 | payload = [] 29 | payload.append(ts) 30 | payload.append('GET') 31 | payload.append(path) 32 | payload.append(query_param) 33 | 34 | sig = gen_sign(api_secret, ''.join(payload)) 35 | headers = { 36 | 'Accept': 'application/json', 37 | 'Content-Type': 'application/json', 38 | 'X-BTK-TIMESTAMP': ts, 39 | 'X-BTK-SIGN': sig, 40 | 'X-BTK-APIKEY': api_key 41 | } 42 | 43 | response = requests.request('GET', f'{host}{path}{query_param}', headers=headers, data={}, verify=False) 44 | print(response.text) 45 | -------------------------------------------------------------------------------- /samples/python/v3/sample_get_order_info.py: -------------------------------------------------------------------------------- 1 | import hashlib 2 | import hmac 3 | import json 4 | import time 5 | import requests 6 | 7 | def gen_sign(api_secret, payload_string=None): 8 | return hmac.new(api_secret.encode('utf-8'), payload_string.encode('utf-8'), hashlib.sha256).hexdigest() 9 | 10 | def gen_query_param(url, query_param): 11 | req = requests.PreparedRequest() 12 | req.prepare_url(url, query_param) 13 | return req.url.replace(url,"") 14 | 15 | if __name__ == '__main__': 16 | 17 | host = 'https://api.bitkub.com' 18 | path = '/api/v3/market/order-info' 19 | api_key = 'your API key' 20 | api_secret = 'your API SECRET' 21 | 22 | ts = str(round(time.time() * 1000)) 23 | param = { 24 | 'sym':"", # symbol in quote_base format: e.g. btc_thb 25 | 'id': "", # order id 26 | "sd": "", # side buy or sell 27 | # "hash":"", # order hash (optional) 28 | } 29 | query_param = gen_query_param(host+path, param) 30 | 31 | payload = [] 32 | payload.append(ts) 33 | payload.append('GET') 34 | payload.append(path) 35 | payload.append(query_param) 36 | 37 | sig = gen_sign(api_secret, ''.join(payload)) 38 | headers = { 39 | 'Accept': 'application/json', 40 | 'Content-Type': 'application/json', 41 | 'X-BTK-TIMESTAMP': ts, 42 | 'X-BTK-SIGN': sig, 43 | 'X-BTK-APIKEY': api_key 44 | } 45 | 46 | response = requests.request('GET', f'{host}{path}{query_param}', headers=headers, data={}, verify=False) 47 | print(response.text) 48 | -------------------------------------------------------------------------------- /samples/python/v3/sample_place_bid.py: -------------------------------------------------------------------------------- 1 | import hashlib 2 | import hmac 3 | import json 4 | import time 5 | import requests 6 | 7 | def gen_sign(api_secret, payload_string=None): 8 | return hmac.new(api_secret.encode('utf-8'), payload_string.encode('utf-8'), hashlib.sha256).hexdigest() 9 | 10 | if __name__ == '__main__': 11 | host = 'https://api.bitkub.com' 12 | path = '/api/v3/market/place-bid' 13 | api_key = 'your API key' 14 | api_secret = 'your API SECRET' 15 | 16 | ts = str(round(time.time() * 1000)) 17 | reqBody = { 18 | 'sym': 'btc_thb', # {quote}_{base} 19 | 'amt': 10, 20 | 'rat': 10, 21 | 'typ': 'limit' # limit, market 22 | } 23 | payload = [] 24 | payload.append(ts) 25 | payload.append('POST') 26 | payload.append(path) 27 | payload.append(json.dumps(reqBody)) 28 | 29 | sig = gen_sign(api_secret, ''.join(payload)) 30 | headers = { 31 | 'Accept': 'application/json', 32 | 'Content-Type': 'application/json', 33 | 'X-BTK-TIMESTAMP': ts, 34 | 'X-BTK-SIGN': sig, 35 | 'X-BTK-APIKEY': api_key 36 | } 37 | 38 | response = requests.request('POST', host + path, headers=headers, data=json.dumps(reqBody), verify=False) 39 | print(response.text) -------------------------------------------------------------------------------- /websocket-api.md: -------------------------------------------------------------------------------- 1 | # Websocket API for Bitkub (2023-04-19) 2 | 3 | # Changelog 4 | * 2023-04-19 Changed the webSocket 5 | market.trade.symbol. Field ```bid, sid``` changed type from ```Integer to String```. 6 | * 2023-01-16 Update `Live Order Book`, added a new event info. 7 | * 2022-08-31 Deprecated the authentication to `Live Order Book` websocket. 8 | # Table of contents 9 | * [Websocket endpoint](#websocket-endpoint) 10 | * [Stream name](#stream-name) 11 | * [Symbols](#symbols) 12 | * [Websocket API documentation](#web-socket-api-documentation) 13 | * [Stream Demo](#stream-demo) 14 | * [Live Order Book](#live-order-book) 15 | 16 | # Websocket endpoint 17 | * The websocket endpoint is: **wss://api.bitkub.com/websocket-api/[\](#stream-name)** 18 | 19 | # Stream name 20 | Stream name requires 3 parts: **service name**, **service type**, and **symbol**, delimited by **dot (.)**, and is **case-insensitive**. 21 | 22 | #### Stream name format: 23 | ```javascript 24 | .. 25 | ``` 26 | 27 | #### Stream name example: 28 | ```javascript 29 | market.trade.thb_btc 30 | ``` 31 | Above example stream name provides real-time data from the **market** service, type **trade**, of symbol **THB_BTC**. 32 | 33 | 34 | 35 | ### Multiple streams subscription: 36 | You can combine multiple streams by using **comma (,)** as the delimeter. 37 | 38 | #### Multiple stream names format: 39 | ```javascript 40 | ,, 41 | ``` 42 | 43 | #### Multiple stream names example: 44 | ```javascript 45 | market.trade.thb_btc,market.ticker.thb_btc,market.trade.thb_eth,market.ticker.thb_eth 46 | ``` 47 | Above subscription provides real-time data from trade and ticker streams of symbols THB_BTC and THB_ETH. 48 | 49 | 50 | 51 | # Symbols 52 | Refer to [RESTful API](https://github.com/bitkub/bitkub-official-api-docs/blob/master/restful-api.md#get-apimarketsymbols) for all available symbols and symbol ids). 53 | 54 | 55 | 56 | # Websocket API documentation 57 | Refer to the following for description of each stream 58 | 59 | ### Trade stream 60 | ⚠️ After April 18th, 2023 at 18:00PM(GMT+7) 61 | 62 | * Response field ```bid, sid``` change type from ```Integer to String```. 63 | * Ref: [Announcement](#announcement) 64 | 65 | #### Name: 66 | market.trade.\ 67 | 68 | #### Description: 69 | The trade stream provides real-time data on matched orders. Each trade contains buy order id and sell order id. Order id is unique by the order side (buy/sell) and symbol. 70 | 71 | #### Response: 72 | ```javascript 73 | { 74 | "stream": "market.trade.thb_eth", // stream name 75 | "sym":"THB_ETH", // symbol 76 | "txn": "ETHSELL0000074282", // transaction id 77 | "rat": "5977.00", // rate matched 78 | "amt": 1.556539, // amount matched 79 | "bid": 2048451, // buy order id 80 | "sid": 2924729, // sell order id 81 | "ts": 1542268567 // trade timestamp 82 | } 83 | ``` 84 | 85 | ### Ticker stream 86 | #### Name: 87 | market.ticker.\ 88 | 89 | #### Description: 90 | The ticker stream provides real-time data on ticker of the specified symbol. Ticker for each symbol is re-calculated on trade order creation, cancellation, and fulfillment. 91 | 92 | #### Response: 93 | ```javascript 94 | { 95 | "stream": "market.ticker.thb_btc", 96 | "id": 1, 97 | "last": 2883194.85, 98 | "lowestAsk": 2883194.9, 99 | "lowestAskSize": 0.0070947, 100 | "highestBid": 2881000.31, 101 | "highestBidSize": 0.00470253, 102 | "change": 60622.33, 103 | "percentChange": 2.15, 104 | "baseVolume": 89.25334259, 105 | "quoteVolume": 256768588.16, 106 | "isFrozen": 0, 107 | "high24hr": 2916959.99, 108 | "low24hr": 2819009.05, 109 | "open": 2822572.52, 110 | "close": 2883194.85 111 | } 112 | ``` 113 | 114 | # Stream Demo 115 | The demo page is available [here](https://api.bitkub.com/websocket-api?streams=) for testing streams subscription. 116 | 117 | # Live Order Book 118 | #### Description: 119 | Use symbol id (numeric id) to get real-time data of order book: **wss://api.bitkub.com/websocket-api/orderbook/[\](#symbols)**. 120 | 121 | #### Message data: 122 | ```javascript 123 | { 124 | "data": (data), 125 | "event": (event type) 126 | } 127 | ``` 128 | There are 4 event types: **bidschanged**, **askschanged**, **tradeschanged**, and **global.ticker** 129 | * **bidschanged** occurs when any buy order has changed on the selected symbol (opened/closed/cancelled). Data is array of buy orders after the change (max. 30 orders). 130 | * **askschanged** occurs when any sell order has changed on the selected symbol (opened/closed/cancelled). Data is array of sell orders after the change (max. 30 orders). 131 | * **tradeschanged** occurs when buy and sell orders have been matched on the selected symbol. Data is array containing 3 arrays: array of latest trades, array of buy orders, and array of sell orders (each max. 30 orders). You get this event as the initial data upon successful subscription. 132 | * **ticker** occurs every time when either bidschanged, askschanged, or tradeschanged is fired on the selected symbol. 133 | * **global.ticker** occurs every time when either bidschanged, askschanged, or tradeschanged is fired on any symbol in the exchange. 134 | 135 | #### Example response (bidschanged or askschanged): 136 | ```javascript 137 | { 138 | "data":[ 139 | [ 140 | 121.82, // vol 141 | 112510.1, // rate 142 | 0.00108283, // amount 143 | 0, // reserved, always 0 144 | false, // is new order 145 | false // user is owner (deprecated) 146 | ] 147 | ], 148 | "event":"bidschanged", 149 | "pairing_id":1 150 | } 151 | ``` 152 | 153 | #### Example response (tradeschanged): 154 | ```javascript 155 | { 156 | "data":[ 157 | [ 158 | [ 159 | 1550320593, // timestamp 160 | 113587, // rate 161 | 0.12817027, // amount 162 | "BUY", // side 163 | 0, // reserved, always 0 164 | 0, // reserved, always 0 165 | true, // is new order 166 | false, // user is buyer (available when authenticated) 167 | false // user is seller (available when authenticated) 168 | ] 169 | ], 170 | [ 171 | [ 172 | 121.82, // vol 173 | 112510.1, // bid rate 174 | 0.00108283, // bid amount 175 | 0, // reserved, always 0 176 | false, // is new order 177 | false // user is owner (available when authenticated) 178 | ] 179 | ], 180 | [ 181 | [ 182 | 51247.13, // vol 183 | 113699, // ask rate 184 | 0.45072632, // ask amount 185 | 0, // reserved, always 0 186 | false, // is new order 187 | false // user is owner (available when authenticated) 188 | ] 189 | ] 190 | ], 191 | "event":"tradeschanged", 192 | "pairing_id":1 193 | } 194 | ``` 195 | 196 | #### Example response (ticker): 197 | ```javascript 198 | { 199 | "data":{ 200 | "baseVolume":106302.39237032, // amount of crypto 201 | "change":0.16, // difference of price compare to the latest 202 | "close":15.9, // close price 203 | "high24hr":16.72, // the highest bidding price taken in the last 24 hours 204 | "highestBid":15.81, // the highest bidding price 205 | "highestBidSize":5640.39911448, // the amount of the highest bidding order 206 | "id":139, // symbol id 207 | "isFrozen":0, // symbol trade status 208 | "last":15.9, // the latest price 209 | "low24hr":15.7, // the lowest price taken in the last 24 hours 210 | "lowestAsk":16.22, // the lowest asking price 211 | "lowestAskSize":1582, // the amount of the lowest asking order 212 | "open":15.74, // open price 213 | "percentChange":1.02, // difference of price compare to the latest in percent 214 | "quoteVolume":1715566.77, // amount of fiat 215 | "stream":"market.ticker.thb_1inch" // stream name 216 | }, 217 | "event":"global.ticker", // event name 218 | "pairing_id":1 219 | } 220 | ``` 221 | 222 | #### Example response (global.ticker): 223 | ```javascript 224 | { 225 | "data":{ 226 | "baseVolume":106302.39237032, // amount of crypto 227 | "change":0.16, // difference of price compare to the latest 228 | "close":15.9, // close price 229 | "high24hr":16.72, // the highest bidding price taken in the last 24 hours 230 | "highestBid":15.81, // the highest bidding price 231 | "highestBidSize":5640.39911448, // the amount of the highest bidding order 232 | "id":139, // symbol id 233 | "isFrozen":0, // symbol trade status 234 | "last":15.9, // the latest price 235 | "low24hr":15.7, // the lowest price taken in the last 24 hours 236 | "lowestAsk":16.22, // the lowest asking price 237 | "lowestAskSize":1582, // the amount of the lowest asking order 238 | "open":15.74, // open price 239 | "percentChange":1.02, // difference of price compare to the latest in percent 240 | "quoteVolume":1715566.77, // amount of fiat 241 | "stream":"market.ticker.thb_1inch" // stream name 242 | }, 243 | "event":"global.ticker" // event name 244 | } 245 | ``` 246 | --------------------------------------------------------------------------------