NAV Navbar

General

Overview

We are providing our API as a Restfull web service. We use JSON as a primary data format for our service.

Server responses with 200 OK HTTP Status for every request proceed well and with 400 Bad Request otherwise. The body of failed response contains data required for explanation and debugging.

Smart contracts

TODO: Write a section

Fees

Operation Fee
Withdrawing 0.1%
Putting an order to orderbook 0.1%
Fulfiling order from orderbook 0.2%

Architectural conventions

For each token we name pennie the minimal fraction of this token. For ETH it is WEI.

So, 1 ETH is equal to 10^18 WEI. The exponent of 10 for number of pennies for the token we name decimalPlaces of that token.

Each Token has code attribute containing our internal identificator for this token.

Authentication

Example of how to sign the hello message to produce authorization token

web3.eth.getAccounts(function getAccountsCallback(error, accounts) {
  var from = accounts[0];
  var data = [
    { type: 'string', name: 'hello', value: 'counter' }
  ];
  web3.currentProvider.sendAsync({
    from: from,
    method: 'eth_signTypedData',
    params: [data, from],
  }, function sendAsyncCallback(error, result) {
    alert(result.result);
  });
});

Use ethereum signature of { hello: 'counter' } as an authorization key

Models

Token

Token trading on our exchange

{
  code: 0
  symbol: "ETH"
  name: "Ethereum"
  decimalPlaces: 18
  contractAddress: null
}
Attribute Type Description
code number Token code
symbol string Token ticker symbol
name string Token name
decimalPlaces number number of pennies in 1 token coin. (i.e 1 ETH = 1018 of WEI so for ETH decimalPlaces = 18)
contractAddress string / null for ERC-20 tokens: token's smart contract address, for ETH: null

Trade

Market's trade

{
  id: "123abcdef",
  timestamp: "2019-02-10 15:45:00",
  type: "buy",
  stockTokenCode: 2,
  cashTokenCode: 1,
  cashPriceE8: "0xde0b6b3a7640000",
  stockAmount: "0xde0b6b3a7640000",
  maker: "0x1234567890123456789012345678901234567890",
  taker: "0x1234567890123456789012345678901234567890"
}
Attribute Type Description
id string Unique identificator
timestamp string Creation timestamp: YYYY-MM-DD HH:mm:ss
type string Order type: buy / sell
stockTokenCode string stock Token's code
cashTokenCode string cash Token's code
cashPrice string HEX of cash price * 108
stockAmount string HEX of stock amount in pennies: coins count * 10token decimal count
maker string maker's eth address
taker string taker's eth address

Order book

Market's orderbook entity. Stock amount is equal to sum of all order's volumes of given type in given cash price range.

{
  cashPriceE8: "0xde0b6b3a7640000",
  stockAmount: "0xde0b6b3a7640000",
  cashAmount: "0xde0b6b3a7640000",
  type: "buy"
}
Attribute Type Description
cashPriceE8 string HEX of threshold value of cash price range * 108
stockAmount string HEX of stock amount in pennies: coins count * 10token decimal count
cashAmount string HEX of cash sum in current price range in pennies: coins count * 10token decimal count
type string Order type: `(buy / sell)

Order

{
  uniqueId: "123abcdef",
  stockTokenCode: 2,
  cashTokenCode: 1,
  type: "buy",
  stockAmount: "0xde0b6b3a7640000",
  cashPrice: "0xde0b6b3a7640000",
  maker: "0x1234567890123456789012345678901234567890",
  fulfilledStockAmount: "0xde0b6b3a7640000",
  expiryDate: "2019-02-10 15:45:00",
  createdAt: "2019-02-10 15:45:00"
}
Attribute Type Description
uniqueId string Identificator
stockTokenCode number stock Token's code
cashTokenCode number cash Token's code
type string Order type: buy / sell
stockAmount string HEX of stock amount in pennies: coins count * 10token decimal count
cashPriceE8 string HEX of cash price in pennies: price * 108
fulfilledStockAmount string HEX of order's amount which has been partly fullfiled already
expiryDate string Expiry date: YYYY-MM-DD HH:mm:ss
createdAt string Creation timestamp: YYYY-MM-DD HH:mm:ss

Token Account

Each wallet has few fundings in several of the tokens trading on the platform. We name such a relation as a Token Account

{
  id: "123abcdef",
  tokenCode: 1,
  totalAmount: "0xde0b6b3a7640000",
  onOrders: "0xde0b6b3a7640000"
}
Attribute Type Description
id string Identificator
tokenCode string Token's code
totalAmount string HEX of stock amount in pennies: coins count * 10token decimal count
onOrders string HEX of on orders fund amount in pennies: coins count * 10token decimal count

Funding

{
  id: "123abcdef",
  type: "buy",
  amount: "0xde0b6b3a7640000",
  tokenCode: 1,
}
Attribute Type Description
id string Identificator
tokenCode number Token's code
type string Order type: buy / sell
amount string HEX of stock amount in pennies: coins count * 10token decimal count
status object Transaction Status model

Transaction status

{
  state: "final",
  txHash: "0xd22b381c1dec5fdbc14dfd5a0072832728e2e36bacb1443178d62463a3ef4705",
  confirmations: 10,
  timestamp: "2019-02-10 15:45:00"
}
Attribute Type Description
state string Transaction status: (signed / pending / mined / final)
txHash string / null Hash of transaction or null
confirmations number Number of confirmations
timestamp string Timestamp transaction was mined at: YYYY-MM-DD HH:mm:ss

OHLCV

{
  time: 1543219658000,
  open: "2.16",
  high: "2.16",
  low: "2.13",
  close: "2.13",
  volume: "2600"
}
Attribute Type Description
time number Time frame timestamp as unix in ms
open string Open price
high string High price
low string Low price
close string Close price
volume string Trade volume

Exchange rate

{
  id: "1/0",
  fromTokenCode: "1",
  toTokenCode: "0",
  value: "0xcebc200",
  timestamp: "2018-11-25 16:31:20"
}
Attribute Type Description
id string Identificator
fromTokenCode string Code of converted Token
toTokenCode string Code of conversion Token
value string HEX of conversion rate multiplied by 108
timestamp string Timestamp

Exchange

Get tokens

CURL

curl "http://staging.counter.market/arbiter/tokens"
  -X GET
  -H "Authorization: YOUR-AUTHORIZATION-KEY"
  -H "Content-Type: application/json"

This endpoint returns all tokens which can be traded on our platform.

HTTP Request

GET http://staging.counter.market/arbiter/tokens

HTTP JSON Response

List of Tokens:

[ Token, ... ]

Get exchange rates

CURL

curl "http://staging.counter.market/ts/exchange-rates"
  -X GET
  -H "Authorization: YOUR-AUTHORIZATION-KEY"
  -H "Content-Type: application/json"

This endpoint returns all exchange rates for every trading token pair.

HTTP Request

GET http://staging.counter.market/ts/exchange-rates

HTTP JSON Response

List of Exchange rates:

[ items: [ Exchange rate, ... ] ]

Market

Put an order

CURL

curl "http://staging.counter.market/arbiter/orders"
  -X PUT
  -H "Authorization: YOUR-AUTHORIZATION-KEY"
  -H "Content-Type: application/json"
  --data '{"tokenPair": {"stockTokenCode": 2, "cashTokenCode": 1}, "type": 1, "cashPriceE8": "0x2faf080", "stockAmount": "0x2540be400", "maker": "0x1234567890123456789012345678901234567890", "signature": "abc123...", tradeNonce: 22}'

Puts a LIMIT order to market's orderbook

Flow

Step 1 - Provide EIP-712 signature for the following typed structure:

types: {
  EIP712Domain: [
    { name: 'name', type: 'string' },
    { name: 'version', type: 'string' },
    { name: 'chainId', type: 'uint256' },
    { name: 'verifyingContract', type: 'address' },
  ],
  Message: [
    { name: 'title', type: 'string' },
    { name: 'action', type: 'uint256' },
    { name: 'priceE8', type: 'uint256' },
    { name: 'amount', type: 'uint256' },
    { name: 'makerFeeE5', type: 'uint256' },
    { name: 'takerFeeE5', type: 'uint256' },
    { name: 'stockTokenCode', type: 'uint256' },
    { name: 'cashTokenCode', type: 'uint256' },
    { name: 'expiryTime' , type: 'uint256' },
    { name: 'tradeNonce', type: 'uint256' }
  ]
},
primaryType: 'Message',
domain: {
  name: 'counter.market',
  version: '1',
  chainId: '12345',
  verifyingContract: `EXCHANGE_CONTRACT` address
},
message: {
  title: ...,
  action: ...,
  priceE8: ...,
  amount: ...,
  makerFeeE5: ...,
  takerFeeE5: ...,
  stockTokenCode: ...,
  cashTokenCode: ...,
  expiryTime: ...,
  tradeNonce: ...,
}

Here is desriptions for each of the fields:

Attribute Type Description
title string The following string counter.market order:
action uint256 0 for putting BUY order, 1 for putting SELL order
priceE8 uint256 Your price for stock funds in cash * 108
amount uint256 Amount of stock funds in pennies
makerFeeE5 uint256 The vallue of MAKER_FEE * 103 in HEX
takerFeeE5 uint256 The vallue of TAKER_FEE * 103 in HEX
stockTokenCode uint256 stock Token's code
cashTokenCode uint256 cash Token's code
expiryTime uint256 Unix timestamp of order's expiration
tradeNonce uint256 wallet's nonce for trade operation

Step 2 - Make an API call

HTTP Request

PUT http://staging.counter.market/arbiter/orders

Body JSON Parameters

Parameter Type Description
tokenPair.stockTokenCode number Code of the stock token
tokenPair.cashTokenCode number Code of the cash token
type number 0 for putting BUY order, 1 for putting SELL order
cashPriceE8 string Your price for stock funds in cash * 108
stockAmount string Amount of stock funds in pennies
maker string Ethereum address of your wallet to trade from
signature number Ethereum EIP-712 signature (from step 1)
tradeNonce string wallet's nonce for trade operation

Server response

Empty response

Get trades

CURL

curl "http://staging.counter.market/ts/market/DAI/ETH/trades"
  -X GET
  -H "Authorization: YOUR-AUTHORIZATION-KEY"
  -H "Content-Type: application/json"

This endpoint returns market's trades

HTTP Request

GET http://staging.counter.market/ts/market/<StockTokenSymbol>/<CashTokenSymbol>/trades

HTTP JSON Response

List of Trades:

[ items: [ Trade, ... ], total: TOTAL_NUMBER_OF_TRADES ]

Get orderbook

CURL

curl "http://staging.counter.market/arbiter/market/DAI/ETH/orderbook/sell"
  -X GET
  -H "Authorization: YOUR-AUTHORIZATION-KEY"
  -H "Content-Type: application/json"

This endpoint returns current orderbook of the market.

HTTP Request

GET http://staging.counter.market/arbiter/market/<StockTokenSymbol>/<CashTokenSymbol>/orderbook/<OrderType>

URL Parameters

Parameter Description
OrderType One of buy / sell

HTTP JSON Response

List of Order books:

[ Order book, ... ]

Canceling order

CURL

curl "http://staging.counter.market/arbiter/orders/123abcdef"
  -X DELETE
  -H "Authorization: YOUR-AUTHORIZATION-KEY"
  -H "Content-Type: application/json"
  --data '{"signature": "abcdef123123}'

This endpoint cancels order

HTTP Request

DELETE http://staging.counter.market/arbiter/orders/<OrderId>

URL Parameters

Parameter Description
OrderId Order's identificator

Body JSON Parameters

Parameter Description
signature ETH EIP712 signature

HTTP JSON Response

Empty object

Getting OHLCV

CURL

curl "http://staging.counter.market/ts/markets/DAI/ETH/ohlcv?since=1543219645&till=1543219645&step=60"
  -X GET
  -H "Authorization: YOUR-AUTHORIZATION-KEY"
  -H "Content-Type: application/json"

This endpoint cancels order

HTTP Request

GET http://staging.counter.market/ts/markets/<StockTokenSymbol>/<CashTokenSymbol>/ohlcv?since=<Since>&till=<Till>&step=<Step>

Query Parameters

Parameter Type Description
Since number left border of time frame as unix timestamp
Till number right border of time frame as unix timestamp
Step number step granularity in seconds

HTTP JSON Response

{ items: List of OHLCV, nextTime: timestamp of next trade }

Wallet

Get orders for market

CURL

curl "http://staging.counter.market/arbiter/wallets/0x1234567890123456789012345678901234567890/orders/DAI/ETH"
  -X GET
  -H "Authorization: YOUR-AUTHORIZATION-KEY"
  -H "Content-Type: application/json"

This endpoint returns unfulfilled orders of <ETHAddress> wallet in <StockTokenSymbol>/<CashTokenSymbol> market

HTTP Request

GET http://staging.counter.market/arbiter/wallets/<ETHAddress>/orders/<StockTokenSymbol>/<CashTokenSymbol>

URL Parameters

Parameter Description
ETHAddress ETH address of one of your linked wallets

Server response

List of Orders:

{ items: [ Order, ... ], total: TOTAL_NUMBER_OF_TOTALS }

Get all token accounts

CURL

curl "http://staging.counter.market/arbiter/wallets/0x1234567890123456789012345678901234567890/token-accounts"
  -X GET
  -H "Authorization: YOUR-AUTHORIZATION-KEY"
  -H "Content-Type: application/json"

This endpoint returns all Token Accounts for <ETHAddress> wallet

HTTP Request

GET http://staging.counter.market/arbiter/wallets/<ETHAddress>/token-accounts

Server response

List of Token Accounts for a binded <ETHAddress> wallet:

[ Token Account, ... ]

Get trades

CURL

curl "http://staging.counter.market/ts/wallets/0x1234567890123456789012345678901234567890/trades"
  -X GET
  -H "Authorization: YOUR-AUTHORIZATION-KEY"
  -H "Content-Type: application/json"

This endpoint returns the list of Trades of <ETHAddress> wallet

HTTP Request

GET http://staging.counter.market/ts/wallets/<ETHAddress>/trades

Server response

List of Trade's for a binded wallet with given <ETHAddress>:

{ items: [ Trade, ... ], total: TOTAL_NUMBER_OF_TRADES }

Get nonces

This endpoint returns exchange operation nonces for given <ETHAddress> wallet

CURL

curl "http://staging.counter.market/arbiter/wallets/0x1234567890123456789012345678901234567890/nonces"
  -X GET
  -H "Authorization: YOUR-AUTHORIZATION-KEY"
  -H "Content-Type: application/json"

RESPONSE

{
  trade: 22,
  withdraw: 12
}

HTTP Request

GET http://staging.counter.market/arbiter/wallets/<ETHAddress>/nonces

Server response

Dictionary of ETH transaction nonces for each of the exchange operations: trade, withdraw:

{ trade: NONCE_FOR_TRADE_OPERATION, witdraw: NONCE_FOR_WITHDRAW_OPERATION, }

Deposit

CURL

curl "http://staging.counter.market/arbiter/wallets/0x1234567890123456789012345678901234567890/deposits"
  -X PUT
  -H "Authorization: YOUR-AUTHORIZATION-KEY"
  -H "Content-Type: application/json"
  --data '{"tokenCode": 2, "amount": "0xA", "txHash": "0x123"}'

Deposit funds to <ETHAddress> wallet

Depositing ETH:

Step 1 - Invoke depositEther method of TREASURY smart contract by sending transaction from corresponding ethereum account. Set transaction value equal to amount of ETH you wanna to deposit. Refer to smart contract method's arguments:

Argument number Type Description
0 string Address of ethereum account binded to wallet to deposit to

Step 2 - Make an API call

Depositing ERC-20 tokens:

Step 1 - Invoke approve method of ERC-20 token's smart contract to grant TREASURY smart contract to operate with allowed amount of your ERC-20 tokens from your behalf. Use Token's contractAddress as a receiver address for this transaction.

Step 2 - Invoke depositERC20Token method of TREASURY smart contract with the following arguments:

Argument number Type Description
0 string Token Account id
1 string HEX of token amount to deposit in pennies

Step 3 - Make an API call

HTTP Request

PUT http://staging.counter.market/arbiter/wallets/<ETHAddress>/deposits

Body JSON Parameters

Parameter Type Description
tokenCode number Code of the token
amount string HEX of deposit amount in pennies (multiplied by 10^token decimal places count)
txHash string Hash of Ethereum transaction

Server response

Empty response

Withdraw

CURL

curl "http://staging.counter.market/arbiter/wallets/0x1234567890123456789012345678901234567890/withdrawals"
  -X PUT
  -H "Authorization: YOUR-AUTHORIZATION-KEY"
  -H "Content-Type: application/json"
  --data '{"tokenCode": 2, "amount": "0xA", "withdrawAddress": "0x123", "withdrawNonce": 10, "signature": "0x123"}'

Withdraw funds from <ETHAddress> wallet

Flow

Step 1 - Sign following structure with wallet's ethereum address you wanna to withdraw funds from

Attribute Type Description
tokenCode uint256 Token code
withdrawAddress address ETH address to withdraw to
amount uint256 Amount of funds (in pennies) to withdraw in HEX
withdrawFeeE5 uint256 The vallue of WITHDRAWAL_FEE * 103 in HEX
withdrawNonce uint256 wallet's nonce for withdraw operation

Step 2 - Make an API call

HTTP Request

PUT http://staging.counter.market/arbiter/wallets/<ETHAddress>/withdrawals

Body JSON Parameters

Parameter Type Description
tokenCode number Code of the token
amount string HEX of withdraw amount in pennies (multiplied by 10^token decimal places count)
withdrawAddress string ETH address to withdraw to
withdrawFeeE5 string The vallue of WITHDRAWAL_FEE * 103 in HEX
withdrawNonce number wallet's nonce for withdraw operation
signature string Ethereum signature (from step 1)

Server response

Empty response

Get all fundings

CURL

curl "http://staging.counter.market/arbiter/wallets/0x1234567890123456789012345678901234567890/fundings"
  -X GET
  -H "Authorization: YOUR-AUTHORIZATION-KEY"
  -H "Content-Type: application/json"

This endpoints returns list of Fundings of wallet

HTTP Request

PUT http://staging.counter.market/arbiter/wallets/<ETHAddress>/fundings

Server response

List of Fundings of the wallet binded to <ETHAddress>:

{ items: [ Funding, ... ], total: TOTAL_NUMER_OF_FUNDINGS }