Coins Pro API AGREEMENT FOR USERS, Transcriptions of Business Systems

Download Coins Pro API AGREEMENT FOR USERS and more Transcriptions Business Systems in PDF only on Docsity!

API Specification

Version 0.3.

13 September, 2018

Changelog

Version 0.3.0 (13 September) - added GetDepositTickets, GetWithdrawTickets methods. Added API keys management methods.

• Changelog
• URLs
• Message Frame Format
  • How to use the frame.
• Standard API Responses - Common error codes
• Unauthenticated Calls
  • GetProducts
  • GetInstruments
• Authentication
  • WebAuthenticateUser
  • GetUserAPIKeys
  • AddUserAPIKey
  • RemoveUserAPIKey
  • AuthenticateUser
• User Account Calls
  • GetUserAccounts
  • GetAccountTransactions
  • GetAccountPositions
  • GetAccountTrades
• Order Handling Calls
  • Description of Order Types used in various calls
  • SendOrder
  • CancelOrder
  • GetOrderStatus
  • GetOrderFee
  • GetOrderHistory
  • GetOpenOrders
• Deposits
  • GetDepositTickets
• Withdrawals
  • CreateWithdrawTicket
  • GetWithdrawTickets
• Market Data
  • Overview of Level 1 and Level 2 Market Information
  • Level 1 Data
    • SubscribeLevel1
    • Level1UpdateEvent
    • UnsubscribeLevel1
  • Level 2 data
    • SubscribeLevel2
    • Level2UpdateEventB
    • UnsubscribeLevel2
  • Trades feed
    • SubscribeTrades
    • TradeDataUpdateEvent
    • UnsubscribeTrades
• Account events feed
  • SubscribeAccountEvents
  • PendingDepositUpdate
  • AccountPositionEvent
  • OrderStateEvent
  • OrderTradeEvent
  • NewOrderRejectEvent
  • CancelOrderRejectEvent
  • MarketStateUpdate

URLs

You can access the Coins PRO API using the following websocket addresses:

Production wss://api-cx.coins.asia/ws-api/

Staging wss://api-cx.staging.coins.technology/ws-api/

Message Frame Format

All WebSocket Calls and Replies are embedded into a JSON-Formatted Frame object

containing the relevant information about the call or reply, as well as the payload. Take

attention, that all sections about functions, contains format only of response payload

("o" in the frame).

Example

"m":0, "i":0, "n":"GetProducts", "o":"{"OMSId":1"}" }

Frame Payload Parameters

Attribute Name Example Description

m: Message Type "m":0, Describes the type of call the message relates to.

Supported types:

0 = Request 1 = Reply 2 = Subscribe To Event 3 = Event 4 = Unsubscribe from Event 5 = Error

Client should only use 0 (Request) and 2 - to subscribe to data feed.

i: Sequence Number "i":0, This is the sequence number of the message. The Client-Side sequence number should always be an Even Number, such that your sequence number variable should

frame.o = json.Stringify(requestPayload); WS.Send(json.Stringify(frame));

When receiving a frame from our API, use the frame to determine the context, and then unwrap the content:

var frame = json.Parse(wsMessage);

if (frame.i == 1) { //This is a Reply if (frame.n == "GetProducts") { var LoginReply = json.Parse(frame.o); if (LoginReply.Authenticated) { var user = LoginReply.User; } } }

Standard API Responses

Response payloads not returning object data and common error responses will follow

pattern below. Please note, that function can have extra error codes, which are described

below under the function section.

Common error codes

Error Code Description

20 Not Authorized

100 Invalid Request

101 Operation Failed

102 Server Error

104 Resource Not Found

Successful call with no return object

"result":true, "errormsg":null, "errorcode":0, "detail":null }

Unsuccessful call due to an issue with authorization

"result":false, "errormsg":"Not Authorized", "errorcode":20, "detail":null }

Unsuccessful call due to invalid request params

"result":false, "errormsg":"Invalid Request", "errorcode":100, "detail":"OMSId must be an Integer" }

Unauthenticated Calls

For all calls requiring OMSId, set OMSId = 1, also, all sections here represent separate

function names. Please read more about OMS and function names in the Message Frame

Format section.

GetProducts

Requests a list of available Products from the API.

Example

Request -> { "m":0, "i":0, "n":"GetProducts", "o":"{"OMSId": 1}" }

Response <- (full frame omitted, please read Message Frame Format)

[ { "ProductId": 1, "Product": "BTC", "ProductFullName": "Bitcoin", "ProductType": "CryptoCurrency", "DecimalPlaces": 9 }, ... ]

Request Parameters

Attribute Name Example Description

OMSId 1 Order Management System ID. Always 1.

Response Parameters

Attribute Name Example Description

ProductId 1 Product's ID Number [Integer]

Product "BTC" Product's Symbol [String]

ProductFullName "Bitcoin" Product's Full Name [String]

ProductType "CryptoCurrency" Product's Type [String]

Supported values:

• "NationalCurrency"
• "CryptoCurrency"

DecimalPlaces 9 Product's Precision [Integer]

GetInstruments

Requests a list of available instruments from the API.

Example

Request -> { "m":0, "i":0, "n":"GetInstruments", "o":"{"OMSId": 1}" }

Response <- (full frame omitted, please read Message Frame Format)

[ { "InstrumentId":1, "Symbol":"BTCUSD", "Product1":1, "Product1Symbol":"BTC", "Product2":2, "Product2Symbol":"USD", "InstrumentType": "Standard", }, ... ]

Request Parameters

Attribute Name Example Description

OMSId 1 Order Management System ID. Always 1.

Response Parameters

Attribute Name Example Description

Authentication

WebAuthenticateUser

You must call this in order to use any of the authenticated calls below.

Example

Request -> { "m":0, "i":0, "n":"WebAuthenticateUser", "o":"{"UserName":"User1","Password":"Password"}" }

Response <- (full frame omitted, please read Message Frame Format)

{ "Authenticated": true, "SessionToken":"7d0ccf3a-ae63-44f5-a409-2301d80228bc", "UserId": 1 }

Request Parameters

Attribute Name Example Description

UserName "User1" Username [String]

Password "Password" Password [String]

Response Parameters

Attribute Name Example Description

Authenticated true Is session authenticated now [Bool]

Note: this will be false if auth failed.

SessionToken "7d0ccf3a-ae63- f5-a409-2301d 28bc"

Session token [String]

UserId 1 Authenticated user ID [Integer]

GetUserAPIKeys

The endpoint will return existing APIKeys with assigned permissions. APISecret field will be blank.

Request Parameters

Attribute Name Example Description

UserId 4 User ID [Integer]

Response Parameters

Attribute Name Example Description

UserId 4 User ID [Integer]

ApiKey “ab1eb50a1b0cb a9130cdccba995a 47da77a22e”

Key that you will need to authenticate with [String]

ApiSecret “” Secret that you will use for signature generation [String]

Permissions [‘Deposit’, ‘Withdraw’]

Permissions enabled for API Keys [Array of Strings]

AddUserAPIKey

In order to authenticate using an API key, you will need to create an ApiKey and ApiSecret using this endpoint. Your UserId will need to be provided along with the permissions you wish to enable in payload.

The endpoint will return a UserAPIKey classtype json string containing the APIKey and APISecret.

Note: Please save the APIKey and APISecret values returned in a secure location. Both of these values are needed for authentication and signature generation.

Request Parameters

Attribute Name Example Description

UserId 4 User ID [Integer]

Permissions [‘Deposit’, ‘Withdraw’]

Permissions you wish to enable for this API Key [Array of Strings]

47da77a22e”

Nonce “1534750973” Current timestamp as a string [String]

Signature “6a8de403af40e 27ce00fd1d5c03e eeca0d5ced5227d 273122c398143be 499”

This is a HMAC-SHA256 signature with ApiSecret as a key and nonce + UserId + ApiKey as a message.

Response Parameters

Attribute Name Example Description

User {"UserId":1,"UserNa me":"[email protected] om","Email":"email @email.com","Email Verified":true,"Acco untId":3,"OMSId":1," Use2FA":false}

User info [Object]

Authenticated true If authentication was successful [Bool]

User Account Calls

GetUserAccounts

Retrieves a list of account IDs for the current user. The Request should have an empty

string as the payload. Typically, each user is assigned one account.

Example

Request -> { "m":0, "i":0, "n":"GetUserAccounts", "o":"" }

Response <- (full frame omitted, please read Message Frame Format)

[4]

Response Parameters

Attribute Name Example Description

An array of account IDs

[4] Array of Account IDs [Integer]

GetAccountTransactions

Retrieves a list of recent transactions from your account.

Example

Request -> { "m":0, "i":0, "n":"GetAccountTransactions", "o":"{"OMSId":1,"AccountId": 1,"Depth": 200}" }

Response <- (full frame omitted, please read Message Frame Format) [ { "TransactionId": 945, "AccountId": 4, "CR": 76, "DR": 0, "TransactionType": "Trade", "ReferenceId": 232, "ReferenceType": "Trade", "ProductId": 2, "Balance": 101111.1, "TimeStamp": 1501354796418 }, ... ]

Request Parameters

Attribute Name Example Description

OMSId 1 Order Management System ID. Always 1.

AccountId 1 Account ID of user. Should be populated using GetUserAccounts.

Values:

• Trade
• Deposit
• Withdraw
• Transfer
• OrderHold
• WithdrawHold
• DepositHold
• MarginHold

TimeStamp 1501354796418 [Long Integer] Time at which the transaction took place, in POSIX format and UTC time zone.

GetAccountPositions

Retrieves a list of Positions(Balances) on a specific account.

Example

Request -> { "m":0, "i":0, "n":"GetAccountPositions", "o":"{"OMSId":1,"AccountId":4}" }

Response <- (full frame omitted, please read Message Frame Format)

[{ "AccountId": 4, "ProductSymbol": "BTC", "ProductId": 1, "Amount": 10497.3, "Hold": 3.19, "PendingDeposits": 0, "PendingWithdraws": 0, "TotalDayDeposits": 10500, "TotalDayWithdraws": 0, "TotalMonthWithdraws": 0, }]

Request Parameters

Attribute Name Example Description

OMSId 1 Order Management System ID. Always 1.

AccountId 4 Account ID [Integer]

Response Parameters

Attribute Name Example Description

AccountId 4 Your account id. [Integer]

ProductId 5 Product's ID Number [Integer]

ProductSymbol "BTC" The product symbol for this record. [String]

Amount 10497.3 The Total Balance for the specified product. [Decimal]

Hold 3.19 The total amount of your balance that is on hold. Your Available balance for trading and withdraw is (Amount - Hold). [Decimal]

PendingDeposits 0 Total Deposits Pending for the specified product. [Decimal]

PendingWithdraws 0 Total Withdraws Pending for the specified product. [Decimal]

TotalDayDeposits 10500 The total 24 hour deposits for the specified product. [Decimal]

TotalDayWithdraws 0 The total 24 hour withdraws for the specified product. [Decimal]

TotalMonthWithdraws 0 The total month withdraws for the specified product. [Decimal]

GetAccountTrades

Retrieves Trade History for a specific account.

Example

Request -> { "m":0, "i":0, "n":"GetAccountTrades", "o":"{"OMSId":1,"AccountId":4,"Count":50,"StartIndex":0}" }