Resources
Docs Version Switcher
Search

# ViteX REST API

Note

  • New v2 ViteX API is released. The v1 API is deprecated and service has been suspended. Please upgrade your client accordingly.

# Overview

ViteX API enables users to trade on ViteX DEX without exposing private keys. ViteX API is categorized into trading API and market trends API. Trading API (also known as private API) requires authentication and authorization, and provides functions such as placing and canceling orders. Market trends API (also known as public API) provides market data, information query, etc. Market trends API can be accessed publicly without authentication.

# Base Endpoint

  • [MainNet]: https://api.vitex.net/
  • [TestNet]: https://buidl.vitex.net/open

# API Response

API response is returned in JSON.

HTTP code:

  • HTTP 200 API returned successfully
  • HTTP 4XX Wrong API request
  • HTTP 5XX Service error

Response format:

Key Value
code 0 - success. An error code is returned if the API request failed
msg Detailed error message
data Return data

Example:

Copy { "code": 1, "msg": "Invalid symbol", "data": {} }

Error code:

  • 0 API returned successfully
  • 1 General error - view the specific error message in msg field.
  • 1001 Too frequent request - request exceeds limit.
  • 1002 Invalid parameter - this may include invalid timestamp, wrong order price, invalid amount, order too small, invalid market, insufficient permission, invalid ticker, etc.
  • 1003 Network - network jam, network issues, insufficient Quota and so on.
  • 1004 Other failures - such as attempting to cancel an order of another address, attempting to cancel a filled order, order status exception
  • 1005 Service error - unexpected API error
  • 1006 Minimum order quantity not satisfied - order quantity doesn't reach the minimal requirement in the market
  • 1007 Insufficient exchange balance - user's balance stored on the exchange is not enough

# Data Definition

# Order Status

Code Status Description
0 Unknown Status unknown
1 Pending Request Order submitted, a corresponding request transaction has been created on the blockchain
2 Received Order received by ViteX smart contract but not yet dispatched into the matching engine
3 Open Order unfilled
4 Filled Order completely filled
5 Partially Filled Order partially filled
6 Pending Cancel Cancel order request submitted, a corresponding request transaction has been created on the blockchain
7 Cancelled Order cancelled
8 Partially Cancelled Order partially cancelled (order is partially filled and then cancelled)
9 Failed Order failed
10 Expired Order expired

# Order Type

Code Status Description
0 Limit Order Limit Order
1 Market Order Market Order (to be added in 7th Mainnet upgrade)

# Side

Code Status Description
0 Buy Order Buy
1 Sell Order Sell

# Time In Force

Code Status Description
0 GTC - Good till Cancel Place an order and wait for it to be fully filled or cancelled
1 IOC - Immediate or Cancel Place an order and immediately cancel unfilled (not supported yet)
2 FOK - Fill or Kill Place an order only when it can be fully filled (not supported yet)

# Private API Authorization

To use ViteX Private REST API, you must authorize it on Trade Delegation (opens new window) first in order for ViteX API to trade on your behalf. You need to fill in the delegation address, which is generated by the API service when you applied for the API Key on ViteX API (opens new window). You DO NOT need to provide your private key or mnemonic phrase.

Step 1: Create API Key on ViteX API (opens new window) create-API-key

Step 2: Connect Vite Wallet API-connect-wallet

API-created

  • By providing API Key and API Secret (instead of private key or mnemonics) to a trustworthy third party market-maker, your fund remains safe in your ViteX account and it cannot be misappropriated.
  • You need to enable the API on selected trading pairs. Attempting to trade on unauthorized pairs will cause error.
  • Authorization can be canceled at any time. In this case, ViteX can still reject API trading requests even if the API Key and API Secret are still valid.

It's highly recommended to enable API authorization ONLY on specific trading pairs that you wish to trade.
API-add-trading-pairs

Delegation Address and Quota

ViteX API will generate a unique delegation address for each user. Orders placed by the API are signed by the delegation address instead of your private key. Therefore, DO NOT give your private key or account mnemonics to anyone.

Meanwhile, Quota in the delegation address is zero by default. Users need to provide Quota to the address. API-lock-Quota

# Trigger Limit

ViteX Private API has a trigger limit. The limit is reset every cycle (60s). When the limit is reached, subsequent API requests in the cycle will be rejected.

# API Authentication

Private API requires signature authentication by API Key and API Secret, which you can apply for on ViteX API (opens new window). Please note that API Key and API Secret are both case sensitive.

Besides parameters defined by the specific API methods, 3 additional parameters key, timestamp and signature also need to be included.

  • key - Your API Key
  • timestamp - UNIX timestamp in milliseconds. To avoid replay attacks, API request will be rejected if the timestamp in request is 5,000 ms earlier or 1,000 ms later than standard time.
  • signature - HMAC SHA256 signature on request string, using API Secret as secret key

Sample code of timestamp checking at server side:

Copy if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= 5000) { // process request } else { // reject request }

# Signature of Request String

  • List all parameters (including key and timestamp) in alphabetical order;
  • Generate request string by concatenating parameters with = and & in above order;
  • Sign the request string by HMAC SHA256, using API Secret as the secret key. If request string and request body are both available, put the request string ahead of the request body;
  • Signature is case in-sensitive;
  • Attach the signature to request string in signature field.

# Example

Let's place an order through API /api/v2/order and assume that we have the following API Key and API Secret:

API Key API Secret
913423DE46E97751CCC734F018F09217 F6BED9F34912C0B658B58C73B6531721

We place an order on market ETH-000_BTC-000 to buy 10 ETH at price 0.09 BTC. The API request has the following parameters:

Key Value
symbol ETH-000_BTC-000
side 0
amount 10
price 0.09
timestamp 1567067137937

The request string is:

amount=10&key=913423DE46E97751CCC734F018F09217&price=0.09&side=0&symbol=ETH-000_BTC-000&timestamp=1567755178560

Create signature:

Copy $ echo -n "amount=10&key=913423DE46E97751CCC734F018F09217&price=0.09&side=0&symbol=ETH-000_BTC-000&timestamp=1567755178560" | openssl dgst -sha256 -hmac "F6BED9F34912C0B658B58C73B6531721" (stdin)= 47033f6086b2afc54a0a1f837dccb4ea6fe56a0312bab311e0bbc3941efaf8d6

Call API to place the order:

Copy $ curl -X POST -d "amount=10&key=913423DE46E97751CCC734F018F09217&price=0.09&side=0&symbol=ETH-000_BTC-000&timestamp=1567755178560&signature=47033f6086b2afc54a0a1f837dccb4ea6fe56a0312bab311e0bbc3941efaf8d6" https://api.vitex.net/test/api/v2/order/test

# Private REST API

# Place Order (Test)

Copy POST /api/v2/order/test

The request will not be submitted to the exchange for order testing. This API is generally used to verify if the signature is correct.

Quota consumption: 0 UT

Parameter:

Name Type Required? Description
symbol STRING YES Trading pair name, for example, ETH-000_BTC-000
amount STRING YES Order amount (in trade token)
price STRING YES Order price
side INT YES Buy - 0, Sell - 1
timestamp LONG YES Timestamp (s)
key STRING YES API Key
signature STRING YES HMAC SHA256 signature of request string

Response:

Copy { "code": 0, "msg": "ok", "data": null }

# Place Order

Copy POST /api/v2/order

Quota consumption: 1 UT

Parameter:

Name Type Required? Description
symbol STRING YES Trading pair name, for example, ETH-000_BTC-000
amount STRING YES Order amount (in trade token)
price STRING YES Order price
side INT YES Buy - 0, Sell - 1
timestamp LONG YES Timestamp (s)
key STRING YES API Key
signature STRING YES HMAC SHA256 signature of request string

Response:

Name Type Description
symbol STRING Trading pair name
orderId STRING Order ID
status INTEGER Order status
Copy { "code": 0, "msg": "ok", "data": { "symbol": "VX_ETH-000", "orderId": "c35dd9868ea761b22fc76ba35cf8357db212736ecb56399523126c515113f19d", "status": 1 } }

# Cancel Order

Copy DELETE /api/v2/order

Quota consumption: 1 UT

Parameter:

Name Type Required? Description
symbol STRING YES Trading pair name, for example, ETH-000_BTC-000
orderId STRING YES Order ID
timestamp LONG YES Timestamp (s)
key STRING YES API Key
signature STRING YES HMAC SHA256 signature of request string

Response:

Name Type Description
symbol STRING Trading pair name
orderId STRING Order ID
cancelRequest STRING Cancel request ID
status INTEGER Order status
Copy { "code": 0, "msg": "ok", "data": { "symbol": "VX_ETH-000", "orderId": "c35dd9868ea761b22fc76ba35cf8357db212736ecb56399523126c515113f19d", "cancelRequest": "2d015156738071709b11e8d6fa5a700c2fd30b28d53aa6160fd2ac2e573c7595", "status": 6 } }

# Cancel All Orders

Copy DELETE /api/v2/orders

Quota consumption: N UT (N=Orders)

Parameters:

Name Type Required? Description
symbol STRING YES Trading pair name, for example, ETH-000_BTC-000
timestamp LONG YES Timestamp (s)
key STRING YES API Key
signature STRING YES HMAC SHA256 signature of request string

Response:

Name Type Description
symbol STRING Trading pair name
orderId STRING Order ID
cancelRequest STRING Cancel request ID
status INTEGER Order status
Copy { "code": 0, "msg": "ok", "data": [ { "symbol": "VX_ETH-000", "orderId": "de185edae25a60dff421c1be23ac298b121cb8bebeff2ecb25807ce7d72cf622", "cancelRequest": "355b6fab007d86e7ff09b0793fbb205e82d3880b64d948ed46f88237115349ab", "status": 6 }, { "symbol": "VX_ETH-000", "orderId": "7e079d4664791207e082c0fbeee7b254f2a31e87e1cff9ba18c5faaeee3d400a", "cancelRequest": "55b80fe42c41fa91f675c04a8423afa85857cd30c0f8878d52773f7096bfac3b", "status": 6 } ] }

# Public REST API

# Get Order Limit

Copy GET /api/v2/limit

Get minimum order quantity for all markets

  • Response:

# Get All Tokens

Copy GET /api/v2/tokens
  • Parameters:
Name Type Required? Description
category STRING NO Token category, [quote,all], default all
tokenSymbolLike STRING NO Token symbol, for example, VITE. Fuzzy search supported.
offset INTEGER NO Search starting index, starts at 0, default 0
limit INTEGER NO Search limit, max 500, default 500

  • Response:

# Get Token Detail

Copy GET /api/v2/token/detail
  • Parameters:
Name Type Required? Description
tokenSymbol STRING NO Token symbol, for example, VITE
tokenId STRING NO Token id, for example, tti_5649544520544f4b454e6e40

  • Response:

# Get Listed Tokens

Copy GET /api/v2/token/mapped

Get tokens that are already listed in a specific market

  • Parameters:
Name Type Required? Description
quoteTokenSymbol STRING YES Quote token symbol, for example, VITE

  • Response:

# Get Unlisted Tokens

Copy GET /api/v2/token/unmapped

Get tokens that are not yet listed in a specific market

  • Parameters:
Name Type Required? Description
quoteTokenSymbol STRING YES Quote token symbol, for example, VITE

  • Response:

# Get Trading Pair

Copy GET /api/v2/market

Get trading pair in detail

  • Parameters:
Name Type Required? Description
symbol STRING YES Trading pair name, for example, GRIN-000_BTC-000

  • Response：

# Get All Trading Pairs

Copy GET /api/v2/markets
  • Parameters:
Name Type Required? Description
offset INTEGER NO Search starting index, starts at 0, default 0
limit INTEGER NO Search limit, max 500, default 500

  • Response:

# Get Order

Copy GET /api/v2/order
  • Parameters:
Name Type Required? Description
address STRING YES User's account address (not delegation address)
orderId STRING YES Order id

  • Response:

# Get Open Order

Copy GET /api/v2/orders/open

Get orders that are unfilled or partially filled.

  • Parameters:
Name Type Required? Description
address STRING YES User's account address (not delegation address)
symbol STRING NO Trading pair name, for example, GRIN-000_BTC-000
quoteTokenSymbol STRING NO Quote token symbol, for example, BTC-000
tradeTokenSymbol STRING NO Trade token symbol, for example, GRIN-000
offset INTEGER NO Search starting index, starts at 0, default 0
limit INTEGER NO Search limit, default 30, max 100
total INTEGER NO Include total number searched in result? 0 - not included, 1 - included. Default is 0, in this case total=-1 in response

  • Response:

# Get Orders

Copy GET /api/v2/orders
  • Parameters:
Name Type Required? Description
address STRING YES User's account address (not delegation address)
symbol STRING NO Trading pair name, for example, GRIN-000_BTC-000
quoteTokenSymbol STRING NO Quote token symbol, for example, BTC-000
tradeTokenSymbol STRING NO Trade token symbol, for example, GRIN-000
startTime LONG NO Start time (s)
endTime LONG NO End time (s)
side INTEGER NO Order side. 0 - buy, 1 - sell
status INTEGER NO Order status, valid in [0-10]. 3,5 - returns orders that are unfilled or partially filled; 7,8 - returns orders that are cancelled or partially cancelled
offset INTEGER NO Search starting index, starts at 0, default 0
limit INTEGER NO Search limit, default 30, max 100
total INTEGER NO Include total number searched in result? 0 - not included, 1 - included. Default is 0, in this case total=-1 in response

  • Response:

# Get 24H Price Changes

Copy GET /api/v2/ticker/24hr
  • Parameters:
Name Type Required? Description
symbols STRING NO Trading pairs, split by ","
quoteTokenSymbol STRING NO Quote token symbol, for example, USDT-000. Returns all pairs if unavailable

  • Response:

# Get Order Book Ticker

Copy GET /api/v2/ticker/bookTicker

Get current best price/qty on the order book for a trading pair

  • Parameters:
Name Type Required? Description
symbol STRING YES Trading pair name, for example, GRIN-000_VITE

  • Response:

# Get Trade Summary

Copy GET /api/v2/trades

Get trade records in summary

  • Parameters:
Name Type Required? Description
symbol STRING YES Trading pair name, for example.GRIN-000_VITE
limit INTEGER NO Search limit, default 500

  • Response：

# Get Trade Records

Copy Get /api/v2/trades/all

Get trade records in detail

  • Parameters:
Name Type Required? Description
symbol STRING YES Trading pair name, for example, GRIN-000_VITE
orderId STRING NO Order id
startTime LONG NO Start time (s)
endTime LONG NO End time (s)
side INTEGER NO Order side. 0 - buy, 1 - sell
offset INTEGER NO Search starting index, starts at 0, default 0
limit INTEGER NO Search limit, default 30, max 100
total INTEGER NO Include total number searched in result? 0 - not included, 1 - included. Default is 0, in this case total=-1 in response

  • Response:

# Get Order Book Depth

Copy GET /api/v2/depth
  • Parameters:
Name Type Required? Description
symbol STRING YES Trading pair name, for example, GRIN-000_VITE
limit INTEGER NO Search limit, max 100, default 100
precision INTEGER NO Price precision

  • Response:

# Get Klines/Candlestick Chart

Copy GET /api/v2/klines
  • Parameters:
Name Type Required? Description
symbol STRING YES Trading pair name, for example, GRIN-000_VITE
interval STRING YES Interval, [minute, hour, day, minute30, hour6, hour12, week]
limit INTEGER NO Search limit, max 1500, default 500
startTime LONG NO Start time (s)
endTime LONG NO End time (s)
  • Response:
Name Type Description
t LONG Timestamp
c STRING Close price
p STRING Open price
h STRING Highest price
l STRING Lowest price
v STRING Trade volume

# Get Deposit-Withdrawal Records

Copy /api/v2/deposit-withdraw
  • Parameters:
Name Type Required? Description
address STRING YES Account address
tokenId STRING YES Token id, for example, tti_5649544520544f4b454e6e40
offset INTEGER NO Search starting index, starts at 0, default 0
limit INTEGER NO Search limit, max 100, default 100

  • Response:

# Get Exchange Rate

Copy GET /api/v2/exchange-rate
  • Parameters:
Name Type Required? Description
tokenSymbols STRING NO Trading pairs, split by ",". For example, VITE,ETH-000
tokenIds STRING NO Token ids, split by ",". For example, tti_5649544520544f4b454e6e40,tti_5649544520544f4b454e6e40

  • Response:

# Get USD-CNY Rate

Copy GET /api/v2/usd-cny

  • Parameters: None

  • Response:

# Get Exchange Balance

Copy /api/v2/balance

Parameters:

Name Type Required? Description
address STRING YES Account address

Response:

Name Type Description
available STRING Available balance
locked STRING Balance locked by open order

# Get Trade Mining Info

Get the current cycle's trade mining pool size and real-time accumulated fees

Copy GET /api/v2/trade_fee_info

Response:

Name Type Description
tradePoolVx OBJECT Minable VX to be distributed in 4 markets at the cycle end
tradePoolFee OBJECT Real-time cumulative trading fees in 4 markets

1: VITE 2: ETH-000 3: BTC-000 4: USDT-000

# Get Server Time

Copy GET /api/v2/time GET /api/v2/timestamp

  • Parameters: None

  • Response:

Found an Issue?
Help us improve this page by suggesting edits on GitHub.
vite.org
© 2023 Vite Labs.