├── README.md ├── auth.md ├── dns-settings-api.md ├── error-codes.md ├── marketplace-api.md ├── namebase-exchange-api-documentation.pdf ├── rest-api.md └── web-socket-api.md /README.md: -------------------------------------------------------------------------------- 1 | Namebase Public API Documentation 2 | == 3 | The documents below are the official authority on the Namebase Exchange API. Some notes: 4 | 5 | * Endpoints _not_ enumerated in this document may be discontinued or modified at any time with no notice. 6 | * Error codes will remain consistent within a major API version, but error messages may change at any time with no notice. 7 | * API key authentication may change within a major API version with 1 week of notice/legacy compatibility. 8 | * Rate limiting may change within a major API version with no notice. With all likelihood, we will provide notice, but that is not a guarantee this API provides. 9 | 10 | ## Documents 11 | 12 | 1. [API key authentication instructions](./auth.md) 13 | 2. [Comprehensive list of the Exchange REST API endpoints](./rest-api.md) 14 | 3. [Comprehensive list of the Marketplace REST API endpoints](./marketplace-api.md) 15 | 4. [Comprehensive list of the DNS Settings REST API endpoints](./dns-settings-api.md) 16 | 5. [Comprehensive list of error codes and messages](./error-codes.md) 17 | 6. [Web socket data feed information](./web-socket-api.md) 18 | 19 | ## Client libraries 20 | 21 | Language | Link | Author 22 | ------------ | ------------ | --- 23 | Node.js | [namebasehq/exchange-api](https://github.com/namebasehq/exchange-api) | Namebase 24 | Python | [wy/namebase-exchange-python](https://github.com/wy/namebase-exchange-python) | ~wy 25 | Go | [sniperem/namebase](https://github.com/sniperem/namebase) | sniperem 26 | Python | [pretended/namebase-marketplace](https://github.com/pretended/namebase-marketplace) | pretended -------------------------------------------------------------------------------- /auth.md: -------------------------------------------------------------------------------- 1 | # Auth for the Namebase API 2 | 3 | To obtain an API key, visit the keys page on [https://www.namebase.io/pro/keys](https://www.namebase.io/next/pro/keys) and follow the instructions in the user interface. 4 | 5 | **Be careful with your API keys: they grant unrestricted access to your exchange account.** 6 | 7 | ## Authenticating to the API 8 | 9 | The Namebase API expects HTTP Basic Auth with a valid pair of Namebase API keys. Use the `ACCESS_KEY` as the username and the `SECRET_KEY` as the password. To authorize your requests, send an HTTP request to one of the API endpoints with the following `Authorization` header: 10 | 11 | ```javascript 12 | Authorization: Basic /* base64-encoded string of ACCESS_KEY:SECRET_KEY */ 13 | ``` 14 | 15 | Here is a code sample of API key authentication using Node.js and the `node-fetch` package: 16 | 17 | ```javascript 18 | const credentials = Buffer.from(`${ACCESS_KEY}:${SECRET_KEY}`); 19 | const encodedCredentials = credentials.toString('base64'); 20 | const authorization = `Basic ${encodedCredentials}`; 21 | fetch(/*ENDPOINT*/, { 22 | method: 'GET', 23 | headers: { 24 | Authorization: authorization, 25 | Accept: 'application/json', 26 | 'Content-Type': 'application/json', 27 | }, 28 | }); 29 | ``` 30 | 31 | Note: for Node.js, you may want to use the officially supported Node.js client library linked to in the documentation homepage. 32 | -------------------------------------------------------------------------------- /dns-settings-api.md: -------------------------------------------------------------------------------- 1 | # Public Rest API for Namebase DNS Settings 2 | ## General API Information 3 | * The root API URL is https://www.namebase.io 4 | * Parameters for GET requests must be sent as a `query string`. 5 | * All other request methods require parameters in the request body as `Content-Type: application/json` 6 | * Parameter order does not matter. 7 | * All timestamps are in milliseconds. 8 | * API errors take the following form: 9 | ```javascript 10 | { 11 | "code": "NAMEBASE_API_ERROR_CODE", 12 | "message": "Error message appears here." 13 | } 14 | ``` 15 | 16 | # DNS Settings API 17 | 18 | ## Blockchain Settings 19 | Blockchain settings will not update on Handshake immediately. Until they are mined, the settings will exist in two states: the current Namebase records and the current Handshake records. In the responses, the `upToDate` field will indicate if Handshake is fully synced with the Namebase records. Otherwise, `records` will just return the Namebase records. 20 | 21 | ### Get Settings 22 | ``` 23 | GET /api/v0/dns/domains/:domain 24 | ``` 25 | Returns the current blockchain DNS settings for a `domain`. 26 | 27 | #### Response: 28 | ``` 29 | { 30 | "success": boolean, 31 | "currentHeight": integer, 32 | "upToDate": boolean, 33 | "canUseSimpleUi": boolean, // false if the records were set using the advanced settings 34 | "rawNameState": string, 35 | "fee": string, 36 | "records": Record[], 37 | } 38 | ``` 39 | 40 | ##### Record: 41 | ``` 42 | { 43 | "type": string, 44 | "host": string, 45 | "value": string, 46 | "ttl": integer, 47 | } 48 | ``` 49 | 50 | ### Change Settings 51 | ``` 52 | PUT /api/v0/dns/domains/:domain 53 | ``` 54 | Updates the Handshake DNS settings 55 | 56 | #### Parameters: 57 | | Name | Type | Mandatory | Description | 58 | |-----------------|----------|------------|--------------| 59 | | `records` | Record[] | YES | | 60 | 61 | #### Record: 62 | | Name | Type | Mandatory | Description | 63 | |-----------------|---------|-----------|-----------------------------------| 64 | | `type` | ENUM | YES | Valid inputs: [`DS`, `NS`, `TXT`] | 65 | | `host` | STRING | YES | | 66 | | `value` | STRING | YES | | 67 | | `ttl` | INTEGER | YES | | 68 | 69 | #### Response: 70 | ``` 71 | { 72 | "success": boolean, 73 | "txHash": string, 74 | "rawNameState": string, // hex of synced blockchain records 75 | "records": Record[], 76 | } 77 | ``` 78 | 79 | ##### Record: 80 | ``` 81 | { 82 | "type": string, 83 | "host": string, 84 | "value": string, 85 | "ttl": integer, 86 | } 87 | ``` 88 | 89 | ### Change Settings (advanced) 90 | ``` 91 | PUT /api/v0/dns/domains/:domain/advanced 92 | ``` 93 | Updates the Handshake DNS settings using advanced types. Not all Handshake types are supported using json input, to include other types, create a hex of the records and use this endpoint. 94 | 95 | #### Parameters: 96 | | Name | Type | Mandatory | Description | 97 | |-----------------|--------|------------|---------------------| 98 | | `rawNameState` | STRING | YES | Hex of DNS records | 99 | 100 | #### Response: 101 | ``` 102 | { 103 | "success": boolean, 104 | "txHash": string, 105 | "rawNameState": string, 106 | "canUseSimpleUi": boolean, // false if the records were set using the advanced settings 107 | "records": Record[], 108 | } 109 | ``` 110 | 111 | ##### Record: 112 | ``` 113 | { 114 | "type": string, 115 | "host": string, 116 | "value": string, 117 | "ttl": integer, 118 | } 119 | ``` 120 | 121 | ## Namebase Nameserver Settings 122 | Our nameservers will update immediately. 123 | 124 | ### Get Settings 125 | ``` 126 | GET /api/v0/dns/domains/:domain/nameserver 127 | ``` 128 | 129 | #### Response: 130 | ``` 131 | { 132 | "success": boolean, 133 | "records": Record[], 134 | } 135 | ``` 136 | 137 | ##### Record: 138 | ``` 139 | { 140 | "type": string, 141 | "host": string, 142 | "value": string, 143 | "ttl": integer, 144 | } 145 | ``` 146 | 147 | ### Change Settings 148 | ``` 149 | PUT /api/v0/dns/domains/:domain/nameserver 150 | ``` 151 | 152 | #### Parameters: 153 | | Name | Type | Mandatory | Description | 154 | |-----------------|----------------|------------|--------------| 155 | | `records` | Record[] | YES | The records you want set. Keep in mind that when a new record is set, every record with the same host and type will be removed and replaced with the new record | 156 | | `deleteRecords` | DeleteRecord[] | YES | The record sets that you want to delete. This will remove all records with the specified host and type | 157 | 158 | ##### Record: 159 | | Name | Type | Mandatory | Description | 160 | |-----------------|---------|-----------|-----------------------------------| 161 | | `type` | ENUM | YES | Valid inputs: [`A`, `NS`, `CNAME`, `TXT`, `DS`, `ALIAS`] | 162 | | `host` | STRING | YES | Use `@` to set the record at the root | 163 | | `value` | STRING | YES | | 164 | | `ttl` | INTEGER | YES | | 165 | 166 | ##### DeleteRecord: 167 | | Name | Type | Mandatory | Description | 168 | |-----------------|---------|-----------|-----------------------------------| 169 | | `type` | ENUM | YES | Valid inputs: [`A`, `NS`, `CNAME`, `TXT`, `DS`, `ALIAS`] | 170 | | `host` | STRING | YES | Use `@` to set the zone as the root | 171 | 172 | #### Response: 173 | ``` 174 | { 175 | "success": boolean, 176 | } 177 | ``` 178 | -------------------------------------------------------------------------------- /error-codes.md: -------------------------------------------------------------------------------- 1 | # Error codes for Namebase 2 | Errors consist of two parts: an error code and a message. Codes are universal, 3 | but messages can vary. Here is the error JSON payload: 4 | ```javascript 5 | { 6 | "code": "NAMEBASE_API_ERROR_CODE", 7 | "message": "Error message appears here." 8 | } 9 | ``` 10 | 11 | ## General server or network issues; unclear fix 12 | #### SERVER_UNKNOWN 13 | * An unknown server error occured. 14 | 15 | #### SERVER_FUTURE_TIMESTAMP 16 | * The provided timestamp is too far into the future. 17 | 18 | #### SERVER_LATE_TIMESTAMP 19 | * This request was received after the specified receive window. 20 | 21 | #### SERVER_MAINTENANCE 22 | * The server is currently undergoing scheduled maintenance. Try again. 23 | 24 | ## Request issues; fixed by changing a parameter 25 | 26 | #### REQUEST_UNAUTHENCIATED 27 | * This request is not properly authenticated. Log in or use an API key. 28 | 29 | #### REQUEST_PARSE_ERROR 30 | * An unknown error occured while parsing your request parameters. 31 | 32 | #### REQUEST_MISSING_PARAMETER 33 | * Parameter ${key} is required but did not appear in the request. 34 | 35 | #### REQUEST_BAD_PARAMETER 36 | * Parameter ${key} does not adhere to the spec. 37 | 38 | #### REQUEST_EXTRA_PARAMETER 39 | * Parameter ${key} should not have been included. 40 | 41 | #### REQUEST_UNSUPPORTED_SYMBOL 42 | * The Namebase exchange does not yet support symbol "${symbol}". 43 | 44 | #### REQUEST_UNSUPPORTED_ASSET 45 | * The Namebase exchange does not yet support asset "${asset}". 46 | 47 | #### REQUEST_UNSUPPORTED_LIMIT 48 | * The only supported limits are ${acceptedLimitsString}. 49 | 50 | #### REQUEST_MINIMUM_WITHDRAWAL 51 | * The minimum withdrawal for ${asset} is ${amount}. 52 | 53 | #### REQUEST_MINIMUM_DEPOSIT 54 | * The minimum deposit for ${asset} is ${amount}. 55 | 56 | #### REQUEST_MINIMUM_ORDER 57 | * The minimum order size for ${symbol} is ${amount} ${asset}. 58 | 59 | ## Stateful errors; hard or impossible for user to fix 60 | #### NOT_ALLOWED_TO_TRADE 61 | * Your account is not currently allowed to trade. Complete KYC verification or contact support. 62 | 63 | #### NOT_ALLOWED_TO_DEPOSIT 64 | * Unfortunately, based on your verification status, you cannot deposit ${asset}. 65 | 66 | #### NOT_ALLOWED_TO_WITHDRAW 67 | * Unfortunately, based on your verification status, you cannot withdraw ${asset}. 68 | 69 | #### WITHDRAWAL_ADDRESS_INVALID 70 | * The withdrawal address you've entered is not a valid ${asset} address. 71 | 72 | #### WITHDRAWAL_LIMIT_REACHED 73 | * You've reached your withdrawal limit for ${asset}. Try withdrawing less funds or try again later. 74 | 75 | #### WITHDRAWALS_DISABLED 76 | * ${asset} withdrawals are disabled until block height ${height}. 77 | 78 | #### INSUFFICIENT_BALANCE 79 | * You do not have sufficient balance to perform this action. 80 | 81 | #### CANCEL_INVALID 82 | You can only cancel active orders. 83 | 84 | #### CANCEL_UNAUTHORIZED 85 | You do not have permission to cancel this order. 86 | 87 | #### CANCEL_UNKNOWN 88 | Could not cancel this order due to an unknown error. 89 | 90 | #### GET_ORDER_FAILED 91 | Could not retrieve this order. 92 | 93 | #### GET_TRADES_UNAUTHORIZED 94 | You do not have permission to retrieve this order's trades. 95 | -------------------------------------------------------------------------------- /marketplace-api.md: -------------------------------------------------------------------------------- 1 | # Public Rest API for Namebase Marketplace 2 | ## General API Information 3 | * The root API URL is https://www.namebase.io 4 | * Parameters for GET requests must be sent as a `query string`. 5 | * All other request methods require parameters in the request body as `Content-Type: application/json` 6 | * Parameter order does not matter. 7 | * All timestamps are in milliseconds. 8 | * API errors take the following form: 9 | ```javascript 10 | { 11 | "code": "NAMEBASE_API_ERROR_CODE", 12 | "message": "Error message appears here." 13 | } 14 | ``` 15 | 16 | ## Rate limiting 17 | If your account repeatedly gets rate limited, then you are using the API improperly and must back off. Failure to do so will cause your account to lose API access. Namebase retains the right to ban your account with no notice if you are abusing the API. 18 | 19 | The rate limits are set generously and are not meant to prohibit any amount of normal usage. In the future, we will standardize our rate limits and provide more explicit feedback about how many remaining requests you can send each minute. 20 | 21 | # Marketplace API 22 | ## Terminology 23 | * All prices are in the units of quote asset per 1 unit of the base asset 24 | * All quantities are in the units of the base asset, and all quote quantities are in the units of the quote asset 25 | * Similarly, volumes are in the units of the base asset, and quote volumes are in the units of the quote asset 26 | 27 | ### Marketplace Listings 28 | ``` 29 | GET /api/domains/marketplace/:offset 30 | ``` 31 | Returns 100 sorted names, paginated by an `offset` parameter. For example, `offset=0` will get the first 100 listings and `offset=100` will return listings 101-200. 32 | 33 | #### Parameters: 34 | | Name | Type | Mandatory | Description | 35 | |-----------------|--------|-----------|--------------------------------------------------| 36 | | `sortKey` | ENUM | NO | Default: `bid`; Valid sortKeys: [`bid`, `price`, `name`, 'date'] | 37 | | `sortDirection` | ENUM | NO | Default: `asc`; Valid sortDirections: [`desc`, `asc`] | 38 | | `firstCharacter`| STRING | NO | Use `#` to select for all names starting with a number | 39 | | `maxPrice` | STRING | NO | Small HNS units | 40 | | `maxLength` | STRING | NO | | 41 | | `onlyPuny` | BOOLEAN | NO | Default: `false` | 42 | 43 | #### Response: 44 | ``` 45 | { 46 | "success": boolean, 47 | "domains": [ 48 | { 49 | "id": string, 50 | "amount": string, 51 | "name": string, 52 | "description": string, 53 | "watching": boolean | null 54 | }, 55 | ], 56 | } 57 | ``` 58 | 59 | ### All Sale History 60 | ``` 61 | GET /api/domains/sold/:offset 62 | ``` 63 | Returns 100 sorted names, paginated by an `offset` parameter. For example, `offset=0` will get the first 100 listings and `offset=100` will return listings 101-200. 64 | 65 | #### Parameters: 66 | | Name | Type | Mandatory | Description | 67 | |-----------------|--------|-----------|------------------------------------------------------------| 68 | | `sortKey` | ENUM | NO | Default: `date`, Valid inputs: [`date`, `price`, `name`] | 69 | | `sortDirection` | ENUM | NO | Default: `desc`, Valid inputs: [`desc, `asc`] | 70 | 71 | #### Response: 72 | ``` 73 | { 74 | "success": boolean, 75 | "domains": [ 76 | { 77 | "id": string, 78 | "name": string, 79 | "amount": string, 80 | "asset": string, 81 | "watching": boolean | null, 82 | "created_at": datetime 83 | }, 84 | ], 85 | } 86 | ``` 87 | 88 | ### Domain Sale History 89 | ``` 90 | GET /api/v0/marketplace/:domain/history 91 | ``` 92 | 93 | #### Response: 94 | ``` 95 | { 96 | "success": boolean, 97 | "history": [ 98 | { 99 | "domain": string, 100 | "amount": string, 101 | "asset": string, 102 | "created_at": datetime, 103 | }, 104 | ], 105 | } 106 | ``` 107 | 108 | ### List Name / Update Listing 109 | ``` 110 | POST /api/v0/marketplace/:domain/list 111 | ``` 112 | 113 | #### Parameters: 114 | | Name | Type | Mandatory | Description | 115 | |---------------|--------|-----------|---------------------------------------| 116 | | `amount` | STRING | YES | | 117 | | `asset` | STRING | YES | Valid inputs: [`HNS`] | 118 | | `description` | STRING | NO | Default: ''; 10,000 character max | 119 | 120 | #### Response: 121 | ``` 122 | { 123 | "success": boolean, 124 | } 125 | ``` 126 | 127 | ### Cancel Listing 128 | ``` 129 | POST /api/v0/marketplace/:domain/cancel 130 | ``` 131 | 132 | #### Response: 133 | ``` 134 | { 135 | "success": boolean, 136 | } 137 | ``` 138 | 139 | ### Purchase Name 140 | ``` 141 | POST /api/v0/marketplace/:domain/buynow 142 | ``` 143 | 144 | #### Response: 145 | ``` 146 | { 147 | "success": boolean, 148 | } 149 | -------------------------------------------------------------------------------- /namebase-exchange-api-documentation.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/namebasehq/api-documentation/a146459984f2bc013b971c5947e3cb604d9e800c/namebase-exchange-api-documentation.pdf -------------------------------------------------------------------------------- /rest-api.md: -------------------------------------------------------------------------------- 1 | # Public Rest API for Namebase 2 | ## General API Information 3 | * The root API URL is https://www.namebase.io 4 | * Parameters for GET requests must be sent as a `query string`. 5 | * All other request methods require parameters in the request body as `Content-Type: application/json` 6 | * Parameter order does not matter. 7 | * All timestamps are in milliseconds. 8 | * API errors take the following form: 9 | ```javascript 10 | { 11 | "code": "NAMEBASE_API_ERROR_CODE", 12 | "message": "Error message appears here." 13 | } 14 | ``` 15 | 16 | ## Rate limiting 17 | If your account repeatedly gets rate limited, then you are using the API improperly and must back off. Failure to do so will cause your account to lose API access. Namebase retains the right to ban your account with no notice if you are abusing the API. 18 | 19 | The rate limits are set generously and are not meant to prohibit any amount of normal usage. In the future, we will standardize our rate limits and provide more explicit feedback about how many remaining requests you can send each minute. 20 | 21 | ## Timing security 22 | * Some endpoints require you to send a `timestamp` of when you created the request. 23 | * You can optionally specify a `receiveWindow` which determines when your timestamped request expires. 24 | * The `receiveWindow` defaults to 5 seconds (so, `5000`) 25 | * If your timestamp is ahead of the server time by too much, you will receive an error complaining about sending a timestamp from the future. 26 | * You can query the exchange info endpoint to synchronize your computer's clock with the exchange's. 27 | 28 | # Public Namebase API 29 | ## Terminology 30 | * For a symbol like HNSBTC, HNS is the "base" asset and BTC is the "quote" asset 31 | * All prices are in the units of quote asset per 1 unit of the base asset 32 | * All quantities are in the units of the base asset, and all quote quantities are in the units of the quote asset 33 | * Similarly, volumes are in the units of the base asset, and quote volumes are in the units of the quote asset 34 | 35 | ## ENUM definitions 36 | ### Order types 37 | * `LMT` (limit) 38 | * `MKT` (market) 39 | 40 | ### Order status 41 | * `NEW` (on the book, no trades yet) 42 | * `PARTIALLY_FILLED` (on the book, some trades have occurred) 43 | * `FILLED` (automatically taken off the book, order fully satisfied) 44 | * `CLOSED` (automatically taken off the book, order partially satisfied) 45 | * `CANCELED` (the trader took the order off the book, order partially satisfied) 46 | 47 | When a limit buy order is placed, due to complexities with rounding numbers, it may be the case that your order lacks sufficient quote to be fully satisfied. In this scenario, your order will automatically be removed from the book (the `CLOSED` state) and you will be refunded the dusty quote amount that remained. In the case of BTC, this dust amount is often just a few satoshis. This is rare and requires no action on your part. 48 | 49 | When a market order is placed, there may be insufficient liquidity to fully satisfy the order. Alternatively, there may be price slippage and your account may lack sufficient funds to fully satisfy the order. In either case, the order is automtically removed from the book and placed in the `CLOSED` state. 50 | 51 | Lastly, if you place two orders on opposite sites and accidentally trade with yourself, then your more recent order, the taker order, will be automatically removed from the book and placed in the `CLOSED` state. Your older, original order will remain on the book. For your own protection (to save you trading fees), Namebase's matching engine will not match two orders from the same user. 52 | 53 | ### Order side 54 | * `BUY` 55 | * `SELL` 56 | 57 | **Valid kline intervals:** 58 | 59 | * `1m` (one minute) 60 | * `5m` (five minutes) 61 | * `15m` (fifteen minutes) 62 | * `1h` (one hour) 63 | * `4h` (four hours) 64 | * `12h` (twelve hours) 65 | * `1d` (one day) 66 | * `1w` (one week) 67 | 68 | ## Miscellaneous endpoints 69 | ### Exchange information 70 | ``` 71 | GET /api/v0/info 72 | ``` 73 | Current exchange trading rules and symbol information. Use to test connectivity to the Rest API. 74 | 75 | **Parameters:** 76 | NONE 77 | 78 | **Response:** 79 | ```javascript 80 | { 81 | "timezone": "UTC", 82 | "serverTime": 1555556529865, 83 | "symbols": [{ 84 | "symbol": "HNSBTC", 85 | "status": "TRADING", 86 | "baseAsset": "HNS", 87 | "basePrecision": 6, 88 | "quoteAsset": "BTC", 89 | "quotePrecision": 8, 90 | "orderTypes": ["LMT", "MKT"] 91 | }] 92 | } 93 | ``` 94 | 95 | ## Market Data endpoints 96 | ### Order book 97 | ``` 98 | GET /api/v0/depth 99 | ``` 100 | 101 | **Parameters:** 102 | 103 | Name | Type | Mandatory | Description 104 | -----|------|-----------|------------ 105 | symbol | STRING | YES | 106 | limit | INT| NO | Default 100; max 1000. Valid limits:[5, 50, 100, 500, 1000] 107 | 108 | **Response:** 109 | ```javascript 110 | { 111 | "lastEventId": 6828, // The last event id this includes 112 | "bids": [ 113 | ["0.00003000", "200.000000"] // [Price level, Quantity] 114 | ], 115 | "asks": [ 116 | ["0.00003100", "100.000000"] 117 | ] 118 | } 119 | ``` 120 | 121 | ### Trade lookup 122 | ``` 123 | GET /api/v0/trade 124 | ``` 125 | Get older trades. 126 | 127 | **Parameters:** 128 | 129 | Name | Type | Mandatory | Description 130 | -----|------|-----------|------------ 131 | symbol | STRING | YES | 132 | tradeId | LONG | NO | Trade id to fetch from. Default gets most recent trades. 133 | limit | INT | NO | Default 100; max 1000. 134 | receiveWindow | LONG | NO | 135 | timestamp | LONG | YES | 136 | 137 | **Response:** 138 | ```javascript 139 | [ 140 | { 141 | "tradeId": 28457, 142 | "price": "0.00003000", 143 | "quantity": "500.000000", 144 | "quoteQuantity": "0.01500000", 145 | "createdAt": 1555556529865, 146 | "isBuyerMaker": true 147 | } 148 | ] 149 | ``` 150 | 151 | ### Kline data 152 | ``` 153 | GET /api/v0/ticker/klines 154 | ``` 155 | Kline (candlestick) bars for a symbol. 156 | 157 | **Parameters:** 158 | 159 | Name | Type | Mandatory | Description 160 | -----|------|-----------|------------ 161 | symbol | STRING | YES | 162 | interval | ENUM | YES | 163 | startTime | LONG | NO | Inclusive 164 | endTime | LONG | NO | Inclusive 165 | limit | INT | NO | Default 100; max 1000. 166 | 167 | * If startTime and endTime are not sent, the most recent klines are returned. 168 | 169 | **Response:** 170 | ```javascript 171 | [ 172 | { 173 | 174 | "openTime": 1557190800000, 175 | "closeTime": 1557190859999, 176 | "openPrice": "0.00002247", 177 | "highPrice": "0.00002256", 178 | "lowPrice": "0.00002243", 179 | "closePrice": "0.00002253", 180 | "volume": "10.001301", 181 | "quoteVolume": "0.000224824", 182 | "numberOfTrades": 42 183 | } 184 | ] 185 | ``` 186 | 187 | 188 | ### 24hr ticker price change statistics 189 | ``` 190 | GET /api/v0/ticker/day 191 | ``` 192 | 24 hour rolling window price change statistics. 193 | 194 | **Parameters:** 195 | 196 | Name | Type | Mandatory | Description 197 | -----|------|-----------|------------ 198 | symbol | STRING | YES | 199 | 200 | **Response:** 201 | ```javascript 202 | { 203 | "volumeWeightedAveragePrice": "0.00001959", 204 | "priceChange": "0.00000019", 205 | "priceChangePercent": "0.8528", 206 | "openPrice": "0.00002228", 207 | "highPrice": "0.00002247", 208 | "lowPrice": "0.00001414", 209 | "closePrice": "0.00002247", 210 | "volume": "11413.935399", 211 | "quoteVolume": "0.22363732", 212 | "openTime": 1555467560001, 213 | "closeTime": 1555553960000, 214 | "firstTradeId": 19761, 215 | "lastTradeId": 20926, 216 | "numberOfTrades": 1166 217 | } 218 | ``` 219 | 220 | 221 | ### Symbol price ticker 222 | ``` 223 | GET /api/v0/ticker/price 224 | ``` 225 | Latest price for a symbol or symbols. 226 | 227 | **Parameters:** 228 | 229 | Name | Type | Mandatory | Description 230 | -----|------|-----------|------------ 231 | symbol | STRING | YES | 232 | 233 | **Response:** 234 | ```javascript 235 | { 236 | "price": "0.00002300" 237 | } 238 | ``` 239 | 240 | 241 | ### Symbol order book ticker 242 | ``` 243 | GET /api/v0/ticker/book 244 | ``` 245 | Best price/quantity on the order book for a symbol or symbols. 246 | 247 | **Parameters:** 248 | 249 | Name | Type | Mandatory | Description 250 | -----|------|-----------|------------ 251 | symbol | STRING | YES | 252 | 253 | **Response:** 254 | ```javascript 255 | { 256 | "bidPrice": "0.00002000", 257 | "bidQuantity": "100.000000", 258 | "askPrice": "0.00002300", 259 | "askQuantity": "9000.100000" 260 | } 261 | ``` 262 | 263 | ### Circulating supply ticker 264 | ``` 265 | GET /api/v0/ticker/supply 266 | ``` 267 | Returns the circulating supply for the provided asset. 268 | 269 | Currently, only HNS is supported, and it incorporates 1) mined coins, 2) claimed coins from the developer airdrop, 3) coins granted to project sponsors, and 4) burned coins removed from circulation due to name auctions. 270 | 271 | **Parameters:** 272 | 273 | Name | Type | Mandatory | Description 274 | -----|------|-----------|------------ 275 | asset | STRING | YES | 276 | supplyOnly | BOOLEAN | NO | If true, only the number will be returned (with no object labels) 277 | 278 | **Response:** 279 | ```javascript 280 | { 281 | "height": 22012, 282 | "circulatingSupply": "116082412.354562", 283 | 284 | } 285 | ``` 286 | 287 | ## Account endpoints 288 | ### New order 289 | ``` 290 | POST /api/v0/order 291 | ``` 292 | Send in a new order. 293 | 294 | **Parameters:** 295 | 296 | Name | Type | Mandatory | Description 297 | -----|------|-----------|------------ 298 | symbol | STRING | YES | 299 | side | ENUM | YES | Buy or sell etc 300 | type | ENUM | YES | Limit or market etc 301 | quantity | DECIMAL | YES | 302 | price | DECIMAL | NO | Required for limit orders 303 | receiveWindow | LONG | NO | 304 | timestamp | LONG | YES | 305 | 306 | **Response:** 307 | ```javascript 308 | { 309 | "orderId": 174, 310 | "createdAt": 1555556529865, 311 | "price": "0.00000000", 312 | "originalQuantity": "1000.00000000", 313 | "executedQuantity": "1000.00000000", 314 | "status": "FILLED", 315 | "type": "MKT", 316 | "side": "SELL", 317 | "fills": [ 318 | { 319 | "price": "0.00003000", 320 | "quantity": "500.000000", 321 | "quoteQuantity": "0.01500000", 322 | "commission": "0.00000750", 323 | "commissionAsset": "BTC" 324 | } 325 | { 326 | "price": "0.00002000", 327 | "quantity": "500.000000", 328 | "quoteQuantity": "0.01000000", 329 | "commission": "0.00000500", 330 | "commissionAsset": "BTC" 331 | } 332 | ] 333 | } 334 | ``` 335 | 336 | ### Query order 337 | ``` 338 | GET /api/v0/order 339 | ``` 340 | Check an order's status. 341 | 342 | **Parameters:** 343 | 344 | Name | Type | Mandatory | Description 345 | -----|------|-----------|------------ 346 | symbol | STRING | YES | 347 | orderId | LONG | YES | 348 | receiveWindow | LONG | NO | 349 | timestamp | LONG | YES | 350 | 351 | **Response:** 352 | ```javascript 353 | { 354 | "orderId": 1, 355 | "price": "0.1", 356 | "originalQuantity": "1.0", 357 | "executedQuantity": "0.0", 358 | "status": "NEW", 359 | "type": "LMT", 360 | "side": "BUY", 361 | "createdAt": 1555556529865, 362 | "updatedAt": 1555556529865 363 | } 364 | ``` 365 | 366 | ### Cancel order 367 | ``` 368 | DELETE /api/v0/order 369 | ``` 370 | Cancel an active order. 371 | 372 | **Parameters:** 373 | 374 | Name | Type | Mandatory | Description 375 | -----|------|-----------|------------ 376 | symbol | STRING | YES | 377 | orderId | LONG | YES | 378 | receiveWindow | LONG | NO | 379 | timestamp | LONG | YES | 380 | 381 | **Response:** 382 | ```javascript 383 | { 384 | "orderId": 28, 385 | "price": "1.00000000", 386 | "originalQuantity": "910.00000000", 387 | "executedQuantity": "19.00000000", 388 | "status": "CANCELED", 389 | "type": "LMT", 390 | "side": "SELL", 391 | "createdAt": 1555556529865, 392 | } 393 | ``` 394 | 395 | ### Current open orders 396 | ``` 397 | GET /api/v0/order/open 398 | ``` 399 | Get the most recent open orders on a symbol (limited to 500). 400 | 401 | **Parameters:** 402 | 403 | Name | Type | Mandatory | Description 404 | -----|------|-----------|------------ 405 | symbol | STRING | YES | 406 | receiveWindow | LONG | NO | 407 | timestamp | LONG | YES | 408 | 409 | **Response:** 410 | ```javascript 411 | [ 412 | { 413 | "orderId": 1, 414 | "price": "0.1", 415 | "originalQuantity": "1.0", 416 | "executedQuantity": "0.0", 417 | "status": "NEW", 418 | "type": "LMT", 419 | "side": "BUY", 420 | "createdAt": 1555556529865, 421 | "updatedAt": 1555556529865 422 | } 423 | ] 424 | ``` 425 | 426 | ### All orders 427 | ``` 428 | GET /api/v0/order/all 429 | ``` 430 | Get all account orders; active, canceled, or filled. 431 | 432 | **Parameters:** 433 | 434 | Name | Type | Mandatory | Description 435 | -----|------|-----------|------------ 436 | symbol | STRING | YES | 437 | orderId | LONG | NO | Greater than or equal to 0. 438 | limit | INT | NO | Default 100; max 1000. 439 | receiveWindow | LONG | NO | 440 | timestamp | LONG | YES | 441 | 442 | **Notes:** 443 | * If `orderId` is set, it will get orders >= that `orderId`. Otherwise you will receive the most recent orders. 444 | 445 | **Response:** 446 | ```javascript 447 | [ 448 | { 449 | "orderId": 1, 450 | "price": "0.1", 451 | "originalQuantity": "1.0", 452 | "executedQuantity": "0.0", 453 | "status": "NEW", 454 | "type": "LMT", 455 | "side": "BUY", 456 | "createdAt": 1555556529865, 457 | "updatedAt": 1555556529865 458 | } 459 | ] 460 | ``` 461 | 462 | ### Account information 463 | ``` 464 | GET /api/v0/account 465 | ``` 466 | Get basic account information. 467 | 468 | **Parameters:** 469 | 470 | Name | Type | Mandatory | Description 471 | -----|------|-----------|------------ 472 | receiveWindow | LONG | NO | 473 | timestamp | LONG | YES | 474 | 475 | **Response:** 476 | ```javascript 477 | { 478 | "makerFee": 15, // in basis points, 0.15% 479 | "takerFee": 15, // in basis points, 0.15% 480 | "canTrade": true, 481 | "balances": [ 482 | { 483 | "asset": "HNS", 484 | "unlocked": "779.900092", 485 | "lockedInOrders": "100.000000", 486 | "canDeposit": true, 487 | "canWithdraw": true 488 | }, 489 | { 490 | "asset": "BTC", 491 | "unlocked": "5.10000012", 492 | "lockedInOrders": "1.000000", 493 | "canDeposit": true, 494 | "canWithdraw": true 495 | } 496 | ] 497 | } 498 | ``` 499 | 500 | ### Account withdrawal limits 501 | ``` 502 | GET /api/v0/account/limits 503 | ``` 504 | Retrieve your account's withdrawal limits for all assets. Withdrawal limits are applied on a 24-hour rolling basis, and the start and end time of this period are specified by `startTime` and `endTime`. 505 | 506 | The `totalWithdrawn` key specifies how much of an asset you have withdrawn in the last 24 hours, and the `withdrawalLimit` key specifies the maximum amount you are permitted to withdraw in the specified period. 507 | 508 | **Parameters:** 509 | 510 | Name | Type | Mandatory | Description 511 | -----|------|-----------|------------ 512 | receiveWindow | LONG | NO | 513 | timestamp | LONG | YES | 514 | 515 | **Response:** 516 | ```javascript 517 | { 518 | "startTime": 1555467560001, 519 | "endTime": 1555553960000, 520 | "withdrawalLimits": [ 521 | { 522 | "asset": "HNS", 523 | "totalWithdrawn": "500.000000", 524 | "withdrawalLimit": "10000.000000", 525 | }, 526 | { 527 | "asset": "BTC", 528 | "totalWithdrawn": "0.50000000", 529 | "withdrawalLimit": "5.00000000", 530 | } 531 | ] 532 | } 533 | ``` 534 | 535 | ### Account trade list 536 | ``` 537 | GET /api/v0/trade/account 538 | ``` 539 | Get trades for a specific account and symbol. 540 | 541 | **Parameters:** 542 | 543 | Name | Type | Mandatory | Description 544 | -----|------|-----------|------------ 545 | symbol | STRING | YES | 546 | tradeId | LONG | NO | TradeId to fetch from. Default gets most recent trades. 547 | limit | INT | NO | Default 100; max 1000. 548 | receiveWindow | LONG | NO | 549 | timestamp | LONG | YES | 550 | 551 | **Notes:** 552 | * If `tradeId` is set, it will get trades >= that `tradeId`. Otherwise you will get your most recent trades. 553 | 554 | **Response:** 555 | ```javascript 556 | [ 557 | { 558 | "tradeId": 10921, 559 | "orderId": 61313, 560 | "price": "8.00000000", 561 | "quantity": "200.000000", 562 | "quoteQuantity": "1600.00000000", 563 | "commission": "4.500000", 564 | "commissionAsset": "HNS", 565 | "createdAt": 1555556529865, 566 | "isBuyer": true, 567 | "isMaker": false, 568 | } 569 | ] 570 | ``` 571 | 572 | ### Order trade list 573 | ``` 574 | GET /api/v0/trade/order 575 | ``` 576 | Get trades for a specific order and symbol. 577 | 578 | **Parameters:** 579 | 580 | Name | Type | Mandatory | Description 581 | -----|------|-----------|------------ 582 | symbol | STRING | YES | 583 | orderId | LONG | YES | OrderId to get the trades for. 584 | receiveWindow | LONG | NO | 585 | timestamp | LONG | YES | 586 | 587 | **Response:** 588 | ```javascript 589 | [ 590 | { 591 | "tradeId": 10921, 592 | "orderId": 61313, 593 | "price": "8.00000000", 594 | "quantity": "200.000000", 595 | "quoteQuantity": "1600.00000000", 596 | "commission": "4.500000", 597 | "commissionAsset": "HNS", 598 | "createdAt": 1555556529865, 599 | "isBuyer": true, 600 | "isMaker": false, 601 | } 602 | ] 603 | ``` 604 | 605 | ### Deposit Address 606 | ``` 607 | POST /api/v0/deposit/address 608 | ``` 609 | Generate a deposit address. 610 | 611 | **Parameters:** 612 | 613 | Name | Type | Mandatory | Description 614 | -----|------|-----------|------------ 615 | asset | STRING | YES | 616 | receiveWindow | LONG | NO | 617 | timestamp | LONG | YES | 618 | 619 | **Response:** 620 | ```javascript 621 | { 622 | "address": "ts1qjg8chhk2t4zff4ltdaug3g9f7sxgne98jyv6ar", 623 | "success": true, 624 | "asset": "HNS" 625 | } 626 | 627 | ``` 628 | 629 | ### Withdraw 630 | ``` 631 | POST /api/v0/withdraw 632 | ``` 633 | Submit a withdraw request. 634 | 635 | **Parameters:** 636 | 637 | Name | Type | Mandatory | Description 638 | -----|------|-----------|------------ 639 | asset | STRING | YES | 640 | address | STRING | YES | 641 | amount | DECIMAL | YES | 642 | receiveWindow | LONG | NO | 643 | timestamp | LONG | YES | 644 | 645 | **Response:** 646 | ```javascript 647 | { 648 | "message": "success", 649 | "success": true, 650 | "id": "df7282ad-df8c-44f7-b747-5b09079ee852" 651 | } 652 | ``` 653 | 654 | ### Deposit History 655 | ``` 656 | GET /api/v0/deposit/history 657 | ``` 658 | Fetch deposit history. 659 | 660 | **Parameters:** 661 | 662 | Name | Type | Mandatory | Description 663 | -----|------|-----------|------------ 664 | asset | STRING | YES | 665 | startTime | LONG | NO | 666 | endTime | LONG | NO | 667 | receiveWindow | LONG | NO | 668 | timestamp | LONG | YES | 669 | 670 | 671 | **Response:** 672 | ```javascript 673 | [ 674 | { 675 | "asset": "HNS", 676 | "amount": "31.853300", 677 | "address": "ts1qtq6ymgcep8mz2ag32ftrktwws0hr4uygprjurf", 678 | "txHash": "e7714680a4d93e3b29348eab38c22bb99949ed4d8aea7006091ff5f9712d1ec6", 679 | "createdAt": 1555556529865, 680 | }, 681 | { 682 | "asset": "HNS", 683 | "amount": "210.000333", 684 | "address": "n1M5Rw3r7WkujB2dG1L84M3a4pzr2NKvfp", 685 | "txHash": "1d0827c642bd67781f80fe15c0fbb349aa4e35117adba06a52add4b207d334dd", 686 | "createdAt": 1555556529865, 687 | } 688 | ], 689 | ``` 690 | 691 | ### Withdraw History 692 | ``` 693 | GET /api/v0/withdraw/history 694 | ``` 695 | Fetch withdraw history. 696 | 697 | **Parameters:** 698 | 699 | Name | Type | Mandatory | Description 700 | -----|------|-----------|------------ 701 | asset | STRING | YES | 702 | startTime | LONG | NO | 703 | endTime | LONG | NO | 704 | receiveWindow | LONG | NO | 705 | timestamp | LONG | YES | 706 | 707 | 708 | **Response:** 709 | 710 | ```javascript 711 | [ 712 | { 713 | "id": "3333edc6-e5c6-4d23-bf84-7b1072a90e37", 714 | "asset": "HNS", 715 | "amount": "1.000000", 716 | "minerFee": "0.100000", 717 | "address": "ts1qtq6ymgcep8mz2ag32ftrktwws0hr4uygprjurf", 718 | "txHash": "e7714680a4d93e3b29348eab38c22bb99949ed4d8aea7006091ff5f9712d1ec6", 719 | "createdAt": 1555556529865, 720 | }, 721 | { 722 | "id": "180ceb4d-d303-4fed-9af6-213b5137255a", 723 | "asset": "HNS", 724 | "amount": "1200.000000", 725 | "minerFee": "0.200000", 726 | "address": "ts1qygv5nh38e9sl8npm4pcx8mqqqfp9sjaq4jrsn5", 727 | "txHash": "c5c398802554b861bef2ec7c4805846ff400a90f71059619974685848bbc4fd3", 728 | "createdAt": 1555556529865, 729 | } 730 | ] 731 | ``` 732 | -------------------------------------------------------------------------------- /web-socket-api.md: -------------------------------------------------------------------------------- 1 | # Web Socket Data Feeds for Namebase 2 | 3 | The host for the streams is wss://app.namebase.io:443/ 4 | 5 | Note: this root URL is different than the root URL for the REST endpoints. 6 | 7 | The `/ticker` feeds send data every second. 8 | 9 | The `/stream` feeds send data on each event as soon as it happens, e.g. on each trade. 10 | 11 | ## Trade stream 12 | The Trades feed sends trade information with the buyer and seller ids scrubbed out. 13 | 14 | **Feed name:** '/ws/v0/stream/trades' 15 | 16 | **Payload:** 17 | ```javascript 18 | { 19 | "eventType": "trade", // Event type 20 | "eventTime": 1555553960000, // Event time 21 | "symbol": "HNSBTC", // Symbol 22 | "tradeId": 12345, // Trade id 23 | "price": "0.001", // Price 24 | "quantity": "100", // Quantity 25 | "quoteQuantity": "100", // Quote quantity 26 | "createdAt": 1555553960000, // The time the trade occurred 27 | "isBuyerMaker": true, // True iff the buy order is the maker 28 | } 29 | ``` 30 | 31 | ## Klines ticker 32 | Connect to the klines feed to receive klines (i.e. candlesticks) every second. 33 | 34 | **Valid kline intervals:** 35 | 36 | * `1m` (one minute) 37 | * `5m` (five minutes) 38 | * `15m` (fifteen minutes) 39 | * `1h` (one hour) 40 | * `4h` (four hours) 41 | * `12h` (twelve hours) 42 | * `1d` (one day) 43 | * `1w` (one week) 44 | 45 | **Feed name:** '/ws/v0/ticker/kline_' 46 | 47 | **Payload:** 48 | ```javascript 49 | { 50 | "eventType": "kline", // Event type 51 | "eventTime": 1555553960000, // Event time 52 | "symbol": "HNSBTC", // Symbol 53 | "kline": { 54 | "interval": "1m", // Interval duration 55 | "isClosed": false, // Is this kline still being updated? 56 | "openTime": 1557190800000, // Kline start time 57 | "closeTime": 1557190859999, // Kline close time 58 | "openPrice": "0.00002247", // Open price 59 | "highPrice": "0.00002256", // High price 60 | "lowPrice": "0.00002243", // Low price 61 | "closePrice": "0.00002253", // Close price 62 | "volume": "10.001301", // Total base asset traded in interval 63 | "quoteVolume": "0.000224824", // Total quote asset traded in interval 64 | "numberOfTrades": 42, // Number of trades 65 | "firstTradeId": 13001, // First trade id 66 | "lastTradeId": 13042, // Last trade id 67 | } 68 | } 69 | ``` 70 | 71 | ## Price ticker 72 | This feed provides statistics for the last 24 hours of trading activity for a HNSBTC, every second. Importantly, these statistics are taken over a _rolling_ window and not over a calendar day. Thus, a request sent on `2019/05/05 16:01:33` will return statistics for trades that occurred between `2019/05/04 16:01:34` and `2019/05/05 16:01:33`. The seconds are inclusive on both ends. 73 | 74 | **Feed name:** '/ws/v0/ticker/day' 75 | 76 | **Payload:** 77 | ```javascript 78 | { 79 | "eventType": "24hr", // Event type 80 | "eventTime": 1555553960000, // Event time 81 | "symbol": "HNSBTC", // Symbol 82 | "volumeWeightedAveragePrice": "0.00001959", // Volume weighted average price 83 | "priceChange": "0.00000019", // Price change 84 | "priceChangePercent": "0.8528", // Price change percent 85 | "openPrice": "0.00002228", // Open price 86 | "highPrice": "0.00002247", // High price 87 | "lowPrice": "0.00001414", // Low price 88 | "closePrice": "0.00002247", // Close price 89 | "volume": "11413.935399", // Total base asset traded in interval 90 | "quoteVolume": "0.22363732", // Total quote asset traded in interval 91 | "openTime": 1555467560001, // Time these statistics began (inclusive) 92 | "closeTime": 1555553960000, // Time these statistics end (inclusive) 93 | "firstTradeId": 19761, // First trade id 94 | "lastTradeId": 20926, // Last trade Id 95 | "numberOfTrades": 1166 // Total number of trades 96 | "bestBidPrice": "0.00002079", // (TODO) Best bid price 97 | "bestBidQty": "10.130000", // (TODO) Best bid quantity 98 | "bestAskPrice": "0.00002091", // (TODO) Best ask price 99 | "bestAskQty": "32.901102", // (TODO) Best ask quantity 100 | } 101 | ``` 102 | 103 | ## Depth ticker 104 | This feed allows you to mirror the Namebase order book on your computer. It sends price and quantity updates every second. Note: this API provides no guarantees on the order the price levels appear in. Do not assume that bids and asks are sorted in decreasing order by price. 105 | 106 | **Feed name:** '/ws/v0/ticker/depth' 107 | 108 | **Payload:** 109 | ```javascript 110 | { 111 | "eventType": "depthUpdate", // Event type 112 | "eventTime": 1555553960000, // Event time 113 | "symbol": "HNSBTC", // Symbol 114 | "firstEventId": 256, // First event id 115 | "lastEventId": 258, // Last event id 116 | "asks": [ 117 | ["0.00002091", "32.901102"] // [Price level to change, New quantity] 118 | ], 119 | "bids": [ 120 | ["0.00002079", "10.130000"] // [Price level to change, New quantity] 121 | ] 122 | } 123 | ``` 124 | 125 | ### Buffering depth updates 126 | Since this feed only provides updates (it's a differential feed), you need to obtain the current orderbook state by querying the `GET /api/v0/depth` REST endpoint. However, it's important that you don't do this _first_. 127 | 128 | To properly maintain a local copy of the Namebase orderbook, begin by connecting to the depth feed and storing all of the depth update events in a buffer. Only once you've successfully connected should you query the REST endpoint to get the current orderbook. 129 | 130 | With this in hand, you can review your buffer and apply all of the updates that happend _after_ the REST response's `lastEventId`. This procedure ensures that you do not miss any events. 131 | --------------------------------------------------------------------------------