COSS public api for trading (1.2)

Download OpenAPI specification:Download

This is coss public api to facilitate secure trading for registered users. You can find out more about how to enable api and obtain api key for trading under Profile section in coss.io https://coss.io . For APIs which require signing user must provide following headers in request Authorisation - The public key. Signature - The HMAC256 hashed payload using private key.

Please refer to community trading wrappers for sample codes

API news

  • January, 16 2019 : Document update for rate limits and order cancellation limits information
    • The api https://trade.coss.io/c/api/v1/exchange-info rate_limits contains objects related to the exchange’s REQUESTS rate limits.

    • A 429 will be returned when rate limit is violated.

    • Your account may get blocked when you place and cancel orders too frequently as explained below:

      The frequency of your order placement and cancellation was too high. If you placed and cancelled an order within 10 seconds then it is counted as a violation. Five continuous violations would result your account being blocked.

      First occurrence: Your transactions will be blocked for 5 minutes.
      Second occurrence: You will be blocked for 1 hour.
      Third occurrence: Your account will be locked for 24 hours.
      Fourth occurrence: Your account will be locked for a longer duration. You may need to contact support to unlock your account.

    • December, 19th 2018 : Changes regarding COSS 1.2
      • A new api has been added to provide trade details for an order
        https://trade.coss.io/c/api/v1/order/trade-detail
      • For API server status please use following
        https://trade.coss.io/c/api/v1/ping
      • For API server time please use following
        https://trade.coss.io/c/api/v1/time
      • For retrieving market summaries please use https://exchange.coss.io/api/getmarketsummaries [1 unit]
        Please note that this api is used by external data providers and the symbol format is different from api for users.
      • Updated Document to reflect paths specific to hosts.
      • Your account may get blocked when you place and cancel orders too frequently as explained below:

        The frequency of your order placement and cancellation was too high.
        First occurrence: Your transactions will be blocked for 5 minutes.
        Second occurrence: You will be blocked for 1 hour.
        Third occurrence: Your account will be locked for 24 hours.
        Fourth occurrence: Your account will be locked for a longer duration. You may need to contact support to unlock your account.
      • December, 7th 2018 : Changes regarding COSS 1.2
        • Rate Limits have been an issue. To make it fairer and easier to deal with burst data, we’re decreasing the API throttling. We’re assigning a usage limit of 1000 units per “MINUTE”. Different API calls have different weights, heavier calls use more units. We’ve added the weight below in []’s
        • https://api.coss.io/v1/ will be depreciated and split into 2 two domains:
          1. https://engine.coss.io/api/v1/ - this will handle all our pricing streams
            • GET /dp - for depth [1 unit]
            • GET /ht - for trade history [1 unit]
          2. https://trade.coss.io/c/api/v1/ - this will handle all account and order requests
            • POST /order/add [1 unit]
            • DELETE /order/cancel [1 unit]
            • POST /order/details [1 unit]
            • POST /order/list/open [1 unit]
            • POST /order/list/completed [1 unit]
            • POST /order/list/all [5 units]
            • GET /account/balances [5 units]
            • GET /account/details [5 units]
            • GET /market-price [1 unit]
            • GET /exchange-info [1 unit]
        • We’ve added price precision on order price and size (similar to other exchanges) e.g. for ETH_BTC price precision 5 order size precision 3 (full list below) The precision per pair is available from the /exchange-info API call
        • We’ve added a new websocket price feed for order book depth and trades, it’s efficient as 0 units to use
          • GET wss://engine.coss.io/ws/v1/ht/{symbol}
            {
             "c" : 1544064724447, // Event time
             "e" : "history_trade", // Event type
             "k" : 461999, // ID
             "m" : false, // Buyer Made Order (buy order)
             "p" : "0.02771000", // Price
             "q" : "0.37800000", // Quantity (Size)
             "s" : "ETH_BTC", // Symbol
             "t" : 1544064724247 // Trade Time
            }
          • GET wss://engine.coss.io/ws/v1/dp/{symbol}
            {
             "a" : [ // asks
              [
                "0.02773000", // price
                "0.67800000" // size
              ]
             ],
             "b" : [ // bids
              [
               "0.02769000", // price
               "0.97800000" // size
              ]
             ]
             "e" : "depthUpdate" // event_type
             "s" : "ETH_BTC" // Symbol
             "t" : 1544064724247 // Time
            }
        • A list of the symbols and the precision (some samples)
          Pairs Token Base Pair Order Amount Limit Decimal Order Price Limit Decimal
          COSS_BTC COSS BTC 2 6
          COSS_ETH COSS ETH 2 6
          KIN_BTC KIN BTC 0 8
          KIN_ETH KIN ETH 1 7
          NEO_BTC NEO BTC 3 5
          NEO_ETH NEO ETH 3 5
      • November, 16th 2018 : Updated API Document
      • October, 31st 2018 : To match industry convention, changed response code for Order creation from 202 to 200
      • October, 30th 2018 : Reduced Throttling to 1 request per second

      Swagger Specs

      Sample Code

      Note: Known Issues

      SIGNED GET Method

      • Please provide the query string (Signed GET methods for account/balances and account/details) in alphabetical order. The cloud provider sends the query strings of parameter names (arranged alphabetically) so the signed pay load may not match at server end. As a work around, please provide parameters in the following format: recvWindow=5000×tamp=12345678

      Orders

      • After creation of a new order, a response code 200 is sent when order created successfully.
      • stop_price in order request and response is not used. The field is for future release.
      • Completed orders not returning orders which were created before public API release.
      • Market Orders are not currently supported. Please use Limit Orders.


      General

      • Timestamp and recvWindow are for future release and currently not used for request timeout, however for signed GET requests the signed payload must be provided: recvWindow=5000&timestamp=12345678
      • Throttling is now set to 1 request every second, this will change over the coming weeks


Authentication

APIKeyHeader

The public key to be provided by user in Authorisation Header.

Security scheme type: API Key
header parameter name: Authorisation

APISignatureHeader

The hmac256 signed payload provided by user in Signature header using their private key.

Security scheme type: API Key
header parameter name: Signature

Account

Everything about your account and wallets. Currently user can retrieve the account balances and account details. Account details to be enriched with more information in future release which will provide information like daily trading limits, kyc status etc.

Retrieves account balances information.

This is a signed function. User must provide the public api key in Authorization header and signed payload in Signature header. On a Linux machine following command will generate the signed pay load echo -n 'recvWindow=5000×tamp=1540203005798’ | openssl dgst -sha256 -hmac ‘replace this by your private key value’ Example URL: https://trade.coss.io/c/api/v1/account/balances

query Parameters
timestamp
required
integer <int64>

Mandatory field for retrieving account balances in query string ?recvWindow=5000×tamp=1540203005798. The future release of API generate use timestamp provided by user in conjunction with recvWindow parameter provided by the user to check if request has reached in time. If the server timestamp is later than sun of value of timestamp and recvWindow by the user then request will be rejected.

recvWindow
integer <int32>

Optional field for retrieving account balances in query string ?recvWindow=5000×tamp=1540203005798.

Responses

200

Account Balances Response

400

Error Response

get /account/balances (HMAC SHA256)
https://trade.coss.io/c/api/v1/account/balances (HMAC SHA256)

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Retrieves account details information.

This is a signed function. User must provide the public api key in Authorisation header and signed payload in Signature header. On a Linux machine following command will generate the signed pay load echo -n ''recvWindow=5000×tamp=1540203005798’’ | openssl dgst -sha256 -hmac ‘replace this by your private key value’ Example URL: https://trade.coss.io/c/api/v1/account/details

query Parameters
timestamp
required
integer <int64>

Mandatory field for retrieving account details in query string ?recvWindow=5000×tamp=1540203005798.If the server timestamp is later than sum of value of timestamp and recvWindow provided by the user then request will be rejected.

recvWindow
integer <int32>

Optional field for retrieving account balances in query string ?timestamp=1540203005798&recvWindow=5000.

Responses

200

Account Details Response

400

Error Response

get /account/details (HMAC SHA256)
https://trade.coss.io/c/api/v1/account/details (HMAC SHA256)

Response samples

application/json
Copy
Expand all Collapse all
{
  • "account_id": "3c05d5f4-41da-4c84-a167-XXXXXXXXX",
  • "email": "xyz@email.com",
  • "phone": 12345678,
  • "enable_google_2fa": true,
  • "status": "offline",
  • "create_at": 1533546246091,
  • "nick_name": "Nick name",
  • "chat_id": "XXX@coss.io",
  • "chat_password": "XXXXXx",
  • "country": "US",
  • "language": "EN",
  • "kyc_status": "string",
  • "kyc_level": "level1",
  • "last_login_history":
    {
    },
  • "commission_status": false,
  • "allow_order": 1,
  • "disable_withdraw": 0,
  • "referral_id": "XXXXX",
  • "chat_server": "string",
  • "exchange_fee":
    {
    }
}

Exchange information

Buy ,Sell, and trading rules information for active (non frozen) symbols.

Provides information about trading rules, symbols etc.

This is a public function and does not require signing. It provides information about trading rules, symbols etc Example URL: https://trade.coss.io/c/api/v1/exchange-info

Responses

200

Exchange Information Response

500

Error Response

get /exchange-info
https://trade.coss.io/c/api/v1/exchange-info

Response samples

application/json
Copy
Expand all Collapse all
{
  • "timezone": "UTC",
  • "server_time": 1530683054384,
  • "rate_limits":
    [
    ],
  • "base_currencies":
    [
    ],
  • "coins":
    [
    ],
  • "symbols":
    [
    ]
}

Market

Information related to market depth, market price, and market summaries.

Provides information about market summaries for symbols.

This is a public function and does not require signing. Retrieves market summaries for all symbols.
URL Example : https://exchange.coss.io/api/getmarketsummaries

Responses

200

Market Summaries Response

400

Error Response

get /getmarketsummaries
https://exchange.coss.io/api/getmarketsummaries

Response samples

application/json
Copy
Expand all Collapse all
{
  • "success": true,
  • "message": null,
  • "result":
    [
    ],
  • "volumes":
    [
    ],
  • "t": 1531208813959
}

Retrieves market price information

This is a public function and does not require signing. Retrieves market price for all symbols if no symbol is provided as query string parameter. If a symbol is provided then retrieves market-price for the symbol URL Example : https://trade.coss.io/c/api/v1//market-price?symbol=ETH_BTC

query Parameters
symbol
string

Retrieves market-price for all symbols if symbol is not provide in parameter otherwise retrieves information for symbol provided in

Responses

200

Market Price Response

400

Error Response

get /market-price/
https://trade.coss.io/c/api/v1/market-price/

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Retrieve market depth information (Order book) for given symbol

Specific pair id for retrieving depth in query string e.g. ?symbol=ETH_BTC. This API does not require signing.
Example URL: https://engine.coss.io/api/v1/dp?symbol=ETH_BTC

query Parameters
symbol
required
string

pair id to retrieve market depth

Responses

200

Market Depth Response

400

Error Response

get /dp/
https://engine.coss.io/api/v1/dp/

Response samples

application/json
Copy
Expand all Collapse all
{
  • "symbol": "COSS_ETH",
  • "limit": 10,
  • "asks":
    [
    ],
  • "bids":
    [
    ],
  • "time": 1538114348750
}

Retrieve market information for given symbol

Specific pair id for retrieving market information stream in path e.g. ETH_BTC. This API does not require signing.
Example URL: https://engine.coss.io/api/v1/ht?symbol=ETH_BTC

query Parameters
symbol
required
string

pair id to retrieve market information.

Responses

200

Trade History Response

400

Error Response

get /ht/
https://engine.coss.io/api/v1/ht/

Response samples

application/json
Copy
Expand all Collapse all
{
  • "symbol": "ETH_BTC",
  • "limit": 100,
  • "history":
    [
    ],
  • "time": 1529298130192
}

Order management

Everything about your order management and statuses.

Place a new order

Place a new order for order side(BUY/SELL) and order type (market/limit). This API requires signing of the payload. URL Example: https://trade.coss.io/c/api/v1/order/add

Request Body schema: application/json
order_symbol
required
string <string>
order_price
required
string <string>
stop_price
string <string>
order_side
required
string
Enum:"BUY" "SELL"

Order side (BUY or SELL)

order_size
required
string <string>
type
required
string
Enum:"market" "limit"

order type (e.g. limit)

timestamp
required
integer <int64>
recvWindow
integer <int32>

Responses

200

Create Order Response

400

Error Response

post /order/add/ (HMAC SHA256)
https://trade.coss.io/c/api/v1/order/add/ (HMAC SHA256)

Request samples

application/json
Copy
Expand all Collapse all
{
  • "order_symbol": "ETH_BTC",
  • "order_price": "1.00234567",
  • "stop_price": "1.00234555",
  • "order_side": "BUY",
  • "order_size": "1000",
  • "type": "limit",
  • "timestamp": 1538114348750,
  • "recvWindow": 5000
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "order_id": "9e5ae4dd-3369-401d-81f5-dff985e1c4ty",
  • "account_id": "9e5ae4dd-3369-401d-81f5-dff985e1c4a6",
  • "order_symbol": "ETH_BTC",
  • "order_side": "BUY",
  • "status": "OPEN",
  • "createTime": 1538114348750,
  • "type": "limit",
  • "order_price": "0.12345678",
  • "order_size": "10.12345678",
  • "executed": "0",
  • "stop_price": "02.12345678",
  • "avg": "1.12345678",
  • "total": "2.12345678"
}

Cancel the open order

Cancel an open order. This API requires signing of the payload. URL Example: https://trade.coss.io/c/api/v1/order/cancel

Request Body schema: application/json
order_id
required
string <string>
order_symbol
required
string <string>
timestamp
required
integer <int64>
recvWindow
integer <int64>

Responses

200

Order Cancellation Successful.

400

Error Response

delete /order/cancel/ (HMAC SHA256)
https://trade.coss.io/c/api/v1/order/cancel/ (HMAC SHA256)

Request samples

application/json
Copy
Expand all Collapse all
{
  • "order_id": "9e5ae4dd-3369-401d-81f5-dff985e1c4e7",
  • "order_symbol": "ETH_BTC",
  • "timestamp": 1538114348750,
  • "recvWindow": 5000
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "order_id": "9e5ae4dd-3369-401d-81f5-dff985e1c4x7",
  • "order_symbol": "ETH_BTC"
}

Get order detail for specific order.

Get order details for specific order. This API requires signing of the payload. URL Example: https://trade.coss.io/c/api/v1/order/details

Request Body schema: application/json
order_id
required
string <string>
timestamp
required
integer <int64>
recvWindow
integer <int64>

Responses

200

Order Detail Response

400

Error Response

post /order/details/ (HMAC SHA256)
https://trade.coss.io/c/api/v1/order/details/ (HMAC SHA256)

Request samples

application/json
Copy
Expand all Collapse all
{
  • "order_id": "9e5ae4dd-3369-401d-81f5-dff985e1cxyz",
  • "timestamp": 1538114348750,
  • "recvWindow": 5000
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "order_id": "9e5ae4dd-3369-401d-81f5-dff985e1c4ty",
  • "account_id": "9e5ae4dd-3369-401d-81f5-dff985e1c4a6",
  • "order_symbol": "ETH_BTC",
  • "order_side": "BUY",
  • "status": "OPEN",
  • "createTime": 1538114348750,
  • "type": "limit",
  • "order_price": "0.12345678",
  • "order_size": "10.12345678",
  • "executed": "0",
  • "stop_price": "02.12345678",
  • "avg": "1.12345678",
  • "total": "2.12345678"
}

Get order's trade details.

Get trade details for an order. API requires signing of the payload. URL Example: https://trade.coss.io/c/api/v1/order/trade-detail

Request Body schema: application/json
order_id
string <string>
timestamp
integer <int64>
recvWindow
integer <int>

Responses

200

Trade Detail Response

400

Error Response

post /order/trade-detail (HMAC SHA256)
https://trade.coss.io/c/api/v1/order/trade-detail (HMAC SHA256)

Request samples

application/json
Copy
Expand all Collapse all
{
  • "order_id": "08098534-ae65-452e-9a84-5b79a5160b5g",
  • "timestamp": 1545196121361,
  • "recvWindow": 5000
}

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get the list of open orders for user.

Get current open orders for specific symbol OPEN and CANCELING. This API requires signing of the payload. URL Example: https://trade.coss.io/c/api/v1/order/list/open

Request Body schema: application/json
limit
integer <int32>
page
integer <int32>
symbol
required
string <string>
timestamp
required
integer <int64>
recvWindow
integer <int32>

Responses

200

Order Detail Response

400

Error Response

post /order/list/open (HMAC SHA256)
https://trade.coss.io/c/api/v1/order/list/open (HMAC SHA256)

Request samples

application/json
Copy
Expand all Collapse all
{
  • "limit": 10,
  • "page": 0,
  • "symbol": "ETH_BTC",
  • "timestamp": 1429514463299,
  • "recvWindow": 5000
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "total": 2,
  • "list":
    [
    ]
}

Get the list of completed orders for user.

Get completed orders for specific symbol where order status is FILLED, PARTIAL_FILL, or CANCELED URL Example: https://trade.coss.io/c/api/v1/order/list/completed

Request Body schema: application/json
limit
integer <int32>
page
integer <int32>
symbol
required
string <string>
timestamp
required
integer <int64>
recvWindow
integer <int32>

Responses

200

Order Detail Response

400

Error Response

post /order/list/completed (HMAC SHA256)
https://trade.coss.io/c/api/v1/order/list/completed (HMAC SHA256)

Request samples

application/json
Copy
Expand all Collapse all
{
  • "limit": 10,
  • "page": 0,
  • "symbol": "ETH_BTC",
  • "timestamp": 1429514463299,
  • "recvWindow": 5000
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "total": 2,
  • "list":
    [
    ]
}

Get the list of all orders for user.

Get the list of all orders for user. URL Example: https://trade.coss.io/c/api/v1/order/list/all

Request Body schema: application/json
symbol
required
string <string>
from_id
string <string>
limit
integer <int32>
timestamp
required
integer <int64>
recvWindow
integer <int32>

Responses

200

Order Detail Response

400

Error Response

post /order/list/all (HMAC SHA256)
https://trade.coss.io/c/api/v1/order/list/all (HMAC SHA256)

Request samples

application/json
Copy
Expand all Collapse all
{
  • "symbol": "ETH_BTC",
  • "from_id": "order id to fetch from",
  • "limit": "default and maximum is 50",
  • "timestamp": 1530682938651,
  • "recvWindow": 5000
}

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Server information

Check server status and server time

Test connectivity to API

Test connectivity to API. Example URL: https://trade.coss.io/c/api/v1/ping

Responses

200

API Connectivity Response

500

Error Response

get /ping
https://trade.coss.io/c/api/v1/ping

Response samples

application/json
Copy
Expand all Collapse all
{
  • "result": true
}

Test connectivity to API and get Server time

Test connectivity to API and get server time. Example URL: https://trade.coss.io/c/api/v1/time

Responses

200

API Connectivity and Time Response

500

Error Response

get /time
https://trade.coss.io/c/api/v1/time

Response samples

application/json
Copy
Expand all Collapse all
{
  • "server_time": 1545196121361
}

COSS public api

COSS public api

Responses

200

COSS public api for registered traders.

500

COSS public api not available.

get /
https://engine.coss.io/api/v1/
https://trade.coss.io/c/api/v1/
wss://engine.coss.io/ws/v1/