diff --git a/README.md b/README.md index 16b472c..7d05ef9 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,6 @@ Official Documentation for Bitkub APIs Name | Description ------------ | ------------ -[restful-api.md](./restful-api.md) | Details on the RESTful API (/api) -[websocket-api.md](./websocket-api.md) | Details on the Websocket API (/websocket-api) - +[restful-api.md](./restful-api.md) | Details on the RESTful API V3 (/api) +[restful-api-v4.md](./restful-api-v4.md) | Details on the RESTful API V4 (/api) +[websocket-api.md](./websocket-api.md) | Details on the Websocket API (/websocket-api) diff --git a/restful-api-v4.md b/restful-api-v4.md new file mode 100644 index 0000000..562448b --- /dev/null +++ b/restful-api-v4.md @@ -0,0 +1,500 @@ + +# RESTful API for Bitkub V4 (2025-02-03) + +# Announcement +* Introducing the New Public API v4 for Crypto Endpoints + +# Change log +* 2025-02-03 Introducing Crypto V4 Endpoints + +# Table of contents +* [Base URL](#base-url) +* [Endpoint types](#endpoint-types) +* [Constructing the request](#constructing-the-request) +* [API documentation](#api-documentation) +* [Error codes](#error-codes) +* [Rate limits](#rate-limits) + +# Base URL +* The base URL is: https://api.bitkub.com + +# Endpoint types + +### Secure endpoints V4 +All secure endpoints require [authentication](#constructing-the-request). + +| Crypto V4 Endpoints | Method | Deposit | Withdraw | Trade | +| ------------------------------------------------------------------------ | ------ | ------- | -------- | ----- | +| [/api/v4/crypto/addresses](#get-apiv4cryptoaddresses) | GET | | | | +| [/api/v4/crypto/addresses](#post-apiv4cryptoaddresses) | POST | ✅ | | | +| [/api/v4/crypto/deposits](#get-apiv4cryptodeposits) | GET | | | | +| [/api/v4/crypto/withdraws](#get-apiv4cryptowithdraws) | GET | | | | +| [/api/v4/crypto/withdraws](#post-apiv4cryptowithdraws) | POST | | ✅ | | +| [/api/v4/crypto/withdraws/internal](#post-apiv4cryptowithdraws-internal) | POST | | ✅ | | + + +# Constructing the request +### GET/POST request +* GET requests require parameters as **query string** in the URL (e.g. ?symbol=BTC&limit=10). +* POST requests require JSON payload (application/json). + +### Request headers (Secure Endpoints) +Authentication requires API KEY and API SECRET. Every request to the server must contain the following in the request header: +* Accept: application/json +* Content-type: application/json +* X-BTK-APIKEY: {YOUR API KEY} +* X-BTK-TIMESTAMP: {Timestamp i.e. 1699376552354 } +* X-BTK-SIGN: [Signature](#signature) + +### Payload (POST) +The payload is always JSON. + +### Signature +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 +You must get a new timestamp in millisecond from [/api/v3/servertime](restful-api.md#get-apiv3servertime). The old one is in second. + +#### Example string for signing a signature: +```javascript +//Example for Get Method +1699381086593GET/api/v4/crypto/addresses?symbol=ATOM + +// Example for Post Method +1699376552354POST/api/v4/crypto/addresses{"symbol":"ATOM","network": "ATOM"} +``` + +#### Example cURL: +```javascript +curl --location 'https://api.bitkub.com/api/v4/crypto/addresses?symbol=ATOM' \ +--header 'X-BTK-TIMESTAMP: 1699381086593' \ +--header 'X-BTK-APIKEY: e286825bda3497ae2d03aa3a30c420d603060cb4edbdd3ec711910c86966e9ba' \ +--header 'X-BTK-SIGN: f5884963865a6e868ddbd58c9fb9ea4bd013076e8a8fa51d38b86c38d707cb8a' +``` + +```javascript +curl --location 'https://api.bitkub.com/api/v4/crypto/addresses' \ +--header 'X-BTK-TIMESTAMP: 1699381086593' \ +--header 'X-BTK-APIKEY: e286825bda3497ae2d03aa3a30c420d603060cb4edbdd3ec711910c86966e9ba' \ +--header 'X-BTK-SIGN: f5884963865a6e868ddbd58c9fb9ea4bd013076e8a8fa51d38b86c38d707cb8a' \ +--header 'Content-Type: application/json' \ +--data '{ + "symbol": "ATOM", + "network": "ATOM", +}' +``` + +# API documentation +Refer to the following for description of each endpoint + +### GET /api/v4/crypto/addresses + +#### Description: +List all crypto addresses (paginated). + +#### Path Params: - + +#### Query Params: +| Key | Type | Required | Description | +| ----------- | --------- | ---------- | ------------------------------------------ | +| page | int | false | Page (default = 1) | +| limit | int | false | Limit (default = 100, max = 200) | +| symbol | String | false | e.g. ATOM | +| network | String | false | e.g. ATOM | +| memo | String | false | e.g. 107467228685 | + +#### Body Params: - + +#### Example cURL: +```javascript +curl --location 'https://api.bitkub.com/api/v4/crypto/addresses?symbol=ATOM' \ +--header 'X-BTK-TIMESTAMP: 1699381086593' \ +--header 'X-BTK-APIKEY: e286825bda3497ae2d03aa3a30c420d603060cb4edbdd3ec711910c86966e9ba' \ +--header 'X-BTK-SIGN: f5884963865a6e868ddbd58c9fb9ea4bd013076e8a8fa51d38b86c38d707cb8a' +``` + +#### Response: +```javascript +{ + "code": "0", + "message": "success", + "data": { + "page": 1, + "total_page": 1, + "total_item": 2, + "items": [ + { + "symbol": "ATOM", + "network": "ATOM", + "address": "cosmos1jcslcmz2lpsy7uq5u2ktn459qce2chqapey7gh", + "memo": "107467228685", + "created_at": "2022-03-18T05:41:40.199Z" + }, + { + "symbol": "ATOM", + "network": "ATOM", + "address": "cosmos1jcslcmz2lpsy7uq5u2ktn459qce2chqapey7gh", + "memo": "104010164476", + "created_at": "2022-03-18T05:46:34.113Z" + } + ] + } +} +``` + +### POST /api/v4/crypto/addresses + +#### Description: +Generate a new crypto address (if an address exists; will return the existing address). + +#### Required Permission: `is_deposit` + +#### Path Params: - + +#### Query Params: - + +#### Body Params: +| Key | Type | Required | Description | +| ----------- | --------- | ---------- | ------------------------------------------ | +| symbol | String | true | e.g. ATOM | +| network | String | true | e.g. ATOM | + +#### Example cURL: +```javascript +curl --location 'https://api.bitkub.com/api/v4/crypto/addresses' \ +--header 'X-BTK-TIMESTAMP: 1699381086593' \ +--header 'X-BTK-APIKEY: e286825bda3497ae2d03aa3a30c420d603060cb4edbdd3ec711910c86966e9ba' \ +--header 'X-BTK-SIGN: f5884963865a6e868ddbd58c9fb9ea4bd013076e8a8fa51d38b86c38d707cb8a' \ +--header 'Content-Type: application/json' \ +--data '{ + "symbol": "ETH", + "network": "ETH", +}' +``` + +#### Response: +```javascript +{ + "code": "0", + "message": "success", + "data": [ + { + "symbol": "ETH", + "network": "ETH", + "address": "0x520165471daa570ab632dd504c6af257bd36edfb", + "memo": "" + } + ] +} +``` + +### GET /api/v4/crypto/deposits + +#### Description: +List crypto deposit history. + +#### Path Params: - + +#### Query Params: +| Key | Type | Required | Description | +| ----------- | --------- | ---------- | ------------------------------------------ | +| page | int | false | Page (default = 1) | +| limit | int | false | Limit (default = 100, max = 200) | + +#### Body Params: - + +#### Example cURL: +```javascript +curl --location 'https://api.bitkub.com/api/v4/crypto/deposits?limit=10' \ +--header 'X-BTK-TIMESTAMP: 1699381086593' \ +--header 'X-BTK-APIKEY: e286825bda3497ae2d03aa3a30c420d603060cb4edbdd3ec711910c86966e9ba' \ +--header 'X-BTK-SIGN: f5884963865a6e868ddbd58c9fb9ea4bd013076e8a8fa51d38b86c38d707cb8a' +``` + +#### Response: +```javascript +{ + "code": "0", + "message": "success", + "data": { + "page": 1, + "total_page": 1, + "total_item": 1, + "items": [ + { + "hash": "XRPWD0000100276", + "symbol": "XRP", + "network": "XRP", + "amount": "5.75111474", + "from_address": "sender address", + "to_address": "recipient address", + "confirmations": 1, + "status": "complete", + "created_at": "2022-03-18T05:41:40.199Z" + } + ] + } +} +``` + +### GET /api/v4/crypto/withdraws + +#### Description: +List crypto withdrawal history. + +#### Path Params: - + +#### Query Params: +| Key | Type | Required | Description | +| ----------- | --------- | ---------- | ------------------------------------------ | +| page | int | false | Page (default = 1) | +| limit | int | false | Limit (default = 100, max = 200) | + +#### Body Params: - + +#### Example cURL: +```javascript +curl --location 'https://api.bitkub.com/api/v4/crypto/withdraws?limit=10' \ +--header 'X-BTK-TIMESTAMP: 1699381086593' \ +--header 'X-BTK-APIKEY: e286825bda3497ae2d03aa3a30c420d603060cb4edbdd3ec711910c86966e9ba' \ +--header 'X-BTK-SIGN: f5884963865a6e868ddbd58c9fb9ea4bd013076e8a8fa51d38b86c38d707cb8a' +``` + +#### Response: +```javascript +{ + "code": "0", + "message": "success", + "data": { + "page": 1, + "total_page": 1, + "total_item": 2, + "items": [ + { + "txn_id": "RDNTWD0000804050", + "external_ref": "XX_1111111111", + "hash": null, + "symbol": "RDNT", + "amount": "2.00000000", + "fee": "4.36", + "address": "0x8b5B4E70BFCB3784f1c1157A50bd5f103c4b0102", + "memo": "", + "status": "processing", + "created_at": "2024-09-01T10:02:43.211Z" + }, + { + "txn_id": "BTCWD1321312683", + "external_ref": "XX_1111111112", + "hash": "0x8891b79c79f0842c9a654db47745fe0291fba222b290d22cabc93f8ae4490303", + "symbol": "BTC", + "amount": "0.10000000", + "fee": "0.0025", + "address": "0x8b5B4E70BFCB3784f1c1157A50bd5f103c4b0102", + "memo": "", + "status": "complete", + "created_at": "2024-09-01T10:02:43.211Z" + } + ] + } +} +``` +### POST /api/v4/crypto/withdraws + +#### Description: +Make a withdrawal to a trusted address. + +#### Required Permission: `is_withdraw` + +#### Path Params: - + +#### Query Params: - + +#### Body Params: +| Key | Type | Required | Description | +| ----------- | --------- | ---------- | ------------------------------------------ | +| symbol | String | true | Symbol for withdrawal (e.g. BTC, ETH) | +| amount | String | true | Amount to withdraw | +| address | String | true | Address to withdraw | +| memo | String | false | Memo or destination tag to withdraw | +| network | String | true | Network to withdraw | + +#### Example cURL: +```javascript +curl --location 'https://api.bitkub.com/api/v4/crypto/withdraws' \ +--header 'X-BTK-TIMESTAMP: 1699381086593' \ +--header 'X-BTK-APIKEY: e286825bda3497ae2d03aa3a30c420d603060cb4edbdd3ec711910c86966e9ba' \ +--header 'X-BTK-SIGN: f5884963865a6e868ddbd58c9fb9ea4bd013076e8a8fa51d38b86c38d707cb8a' \ +--header 'Content-Type: application/json' \ +--data '{ + "symbol": "RDNT", + "amount": "2.00000000", + "address": "0x8b5B4E70BFCB3784f1c1157A50bd5f103c4b0102", + "network": "ARB" +}' +``` + +#### Response: +```javascript +{ + "code": "0", + "message": "success", + "data": { + "txn_id": "RDNTWD0000804050", + "symbol": "RDNT", + "network": "ARB", + "amount": "2.00000000", + "fee": "4.36", + "address": "0x8b5B4E70BFCB3784f1c1157A50bd5f103c4b0102", + "memo": "", + "created_at": "2024-09-01T10:02:43.211Z" + } +} +``` + +### POST /api/v4/crypto/withdraws/internal + +#### Description: +Make a withdraw to an internal address. The destination address is not required to be a trusted address. This API is not enabled by default. Only KYB users can request this feature by contacting us via support@bitkub.com + +#### Required Permission: `is_internal` + +#### Path Params: - + +#### Query Params: - + +#### Body Params: +| Key | Type | Required | Description | +| ------------ | --------- | ---------- | ------------------------------------------ | +| symbol | String | true | Symbol for withdrawal (e.g. BTC, ETH) | +| amount | String | true | Amount to withdraw | +| address | String | true | Address to withdraw | +| memo | String | false | Memo or destination tag to withdraw | +| network | String | true | Network to withdraw | +| external_ref | String | false | External reference | + +**Note**: When `external_ref` is presented in the request body, the system will validate against `external_ref` existing in the database. If `external_ref` already exists, the system will reject the request. + +#### Example cURL: +```javascript +curl --location 'https://api.bitkub.com/api/v4/crypto/withdraws' \ +--header 'X-BTK-TIMESTAMP: 1699381086593' \ +--header 'X-BTK-APIKEY: e286825bda3497ae2d03aa3a30c420d603060cb4edbdd3ec711910c86966e9ba' \ +--header 'X-BTK-SIGN: f5884963865a6e868ddbd58c9fb9ea4bd013076e8a8fa51d38b86c38d707cb8a' \ +--header 'Content-Type: application/json' \ +--data '{ + "symbol": "BTC", + "amount": "0.1", + "address": "4asyjKw6XScneNvhJTLVHS9XfNYM7VBf8x", + "network": "BTC" +}' +``` + +#### Response: +```javascript +{ + "code": "0", + "message": "success", + "data": { + "txn_id": "BTCWD0000012345", + "external_ref": "XXWD0000012345", + "address": "4asyjKw6XScneNvhJTLVHS9XfNYM7VBf8x", + "memo": "", + "symbol": "BTC", + "network": "BTC", + "amount": "0.1", + "fee": "0.0002", + "created_at": "2024-09-01T10:02:43.211Z" + } +} +``` + + +## Additional +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. + +| Coin Name | Symbol | +| ------------- | -------- | +| Terra Classic | `LUNA` | +| Terra 2.0 | `LUNA2` | + +# Error codes +The following is the JSON payload for the Response Error: +```javascript +{ + "code": "V1007-CW", + "message": "asset not found", + "data": {} + } +``` +## Status Codes + +#### 200 (OK) +The request was processed as expected. + +#### 400 (INVALID_REQUEST) +The request is not well-formed, violates schema, or has incorrect fields. + +#### 401 (NOT_AUTHORIZED) +The API key doesn't match the signature or have the necessary permissions to perform the request. + +#### 403 (FORBIDDEN) +The API key doesn't have the necessary permissions to complete the request. + +#### 404 (NOT_FOUND) +The requested resource doesn't exist. + +#### 5XX +Internal Server Error. + +| Code | Status | Message | +| ----------- | ------- |---------------------------------------------------------- | +| S1000-CW | 500 | Internal service error | + + +### Business Error +| Code | Status | Message | +| ----------- | ------- |---------------------------------------------------------- | +| B1000-CW | 400 | User account is suspended | +| B1001-CW | 400 | Network is disabled | +| B1002-CW | 400 | CWS Wallet not found | +| B1003-CW | 400 | Insufficient balance | +| B1004-CW | 400 | User mismatch condition | +| B1005-CW | 400 | Duplicate key | +| B1006-CW | 400 | Airdrop already transfer | +| B1007-CW | 400 | Symbol required | +| B1008-CW | 400 | Event Symbol mismatched | +| B1009-CW | 400 | Pending withdrawal exists | +| B1010-CW | 400 | User account is frozen | +| B1011-CW | 400 | Withdrawal exceeds daily limit | +| B1012-CW | 400 | Address is not trusted | +| B1013-CW | 400 | Withdrawal is frozen | +| B1014-CW | 400 | Address is not whitelisted | +| B1015-CW | 400 | Request is processing | + +### Validation Error +| Code | Status | Message | +| ----------- | ------- |---------------------------------------------------------- | +| V1000-CW | 404 | User not found | +| V1001-CW | 404 | Asset not found | +| V1002-CW | 404 | Event not found | +| V1003-CW | 400 | Invalid signature | +| V1004-CW | 401 | Signature has expired | +| V1005-CW | 404 | Transaction not found | +| V1006-CW | 400 | Invalid parameter*messages can vary | +| V1007-CW | 404 | Symbol not found | +| V1008-CW | 400 | Address not yet generated for this symbol | +| V1009-CW | 404 | Memo not found for this address | +| V1010-CW | 404 | Address not found | +| V1011-CW | 400 | Address already exists | +| V1012-CW | 400 | Destination address not active | + +### Authentication Error +| Code | Status | Message | +| ----------- | ------- |---------------------------------------------------------- | +| A1000-CW | 401 | Unauthorized Access | +| A1001-CW | 403 | Permission denied | + +# Rate limits +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.*** + +| Endpoint | Rate Limit | +| ---------------------------- | ---------------- | +| /api/crypto/* | 250 req/10secs | \ No newline at end of file diff --git a/restful-api.md b/restful-api.md index d35522a..c70071e 100644 --- a/restful-api.md +++ b/restful-api.md @@ -1,9 +1,8 @@ -# RESTful API for Bitkub (2024-12-23) +# RESTful API for Bitkub (2025-02-03) # Announcement -* We are excited to announce the release of our new [Get Market Data V3 endpoint](#non-secure-endpoints-v3) - +* Introducing the New Public API v4 for [Crypto Endpoints](restful-api-v4.md) # Change log * 2024-12-20 Introducing the Enhanced Market Data Endpoint [Ticker, Depth, Bids, Asks, Trades](#non-secure-endpoints-v3)