# 数据查询服务

# RestAPI 接入文档

# 环境地址

• 【test】 https://vitex.vite.net/test
• 【Pre-mainnet】: https://vitex.vite.net/

# /api/v1/limit

获取各个基础交易对的最小下单金额

• Method: GET

• Responses

  code	msg	data
  0	success	Limit
  1	error_msg	null

• Example

  {}
  

# /api/v1/tokens

获取所有的 Token 列表

• Method: GET

• Parameters

  Name	Located In	Description	Required	Schema
  category	query	default all ; Allowed value:[ quote , all ]	no	string
  tokenSymbolLike	query	symbol like; e.g. ETH	no	string
  offset	query	start with 0 ; default 0	no	integer
  limit	query	default 500 ; max 500	no	integer

• Responses

  code	msg	data
  0	success	[ Token ]
  1	error_msg	null

• Example

  {
    "code": 0,
    "msg": "ok",
    "data": [
      {
        "tokenId": "tti_4e88a475c675971dab7ec917",
        "name": "Bitcoin",
        "symbol": "BTC",
        "originalSymbol": "BTC",
        "totalSupply": "2100000000000000",
        "owner": "vite_ab24ef68b84e642c0ddca06beec81c9acb1977bbd7da27a87a"
      }
    ]
  }
  

  {}
  

# /api/v1/token/detail

获取 Token 的详细信息

• Method: GET

• Parameters

  Name	Located In	Description	Required	Schema
  tokenSymbol	query	the symbol of token; e.g. VITE	no	string
  tokenId	query	the tokenId of token; e.g. tti_5649544520544f4b454e6e40	no	string

• Responses

  code	msg	data
  0	success	[ TokenDetail ]
  1	error_msg	null

• Example

  {
    "code": 0,
    "msg": "ok",
    "data": {
      "tokenId": "tti_4e88a475c675971dab7ec917",
      "name": "Bitcoin",
      "symbol": "BTC",
      "originalSymbol": "BTC",
      "totalSupply": "2100000000000000",
      "publisher": "vite_ab24ef68b84e642c0ddca06beec81c9acb1977bbd7da27a87a",
      "tokenDecimals": 8,
      "tokenAccuracy": "0.00000001",
      "publisherDate": null,
      "reissue": 2,
      "urlIcon": null,
      "gateway": null,
      "website": null,
      "links": null,
      "overview": null
    }
  }
  

  {}
  

# /api/v1/token/mapped

获取已开通交易对的 Token 列表

• Method: GET

• Parameters

  Name	Located In	Description	Required	Schema
  quoteTokenSymbol	query	the symbol of quote token; e.g. VITE	yes	string

• Responses

  code	msg	data
  0	success	[ TokenMapping ]
  1	error_msg	null

• Example

  {
    "code": 0,
    "msg": "ok",
    "data": [
      {
        "tokenId": "tti_c2695839043cf966f370ac84",
        "symbol": "VCP"
      }
    ]
  }
  

  {}
  

# /api/v1/token/unmapped

获取未开通交易对的 Token 列表 (上币使用)

• Method: GET

• Parameters

  Name	Located In	Description	Required	Schema
  quoteTokenSymbol	query	the symbol of quote token; e.g. VITE	yes	string

• Responses

  code	msg	data
  0	success	[ TokenMapping ]
  1	error_msg	null

• Example

  {
    "code": 0,
    "msg": "ok",
    "data": [
      {
        "tokenId": "tti_2736f320d7ed1c2871af1d9d",
        "symbol": "VTT"
      }
    ]
  }
  

  {}
  

# /api/v1/markets

获取所有的市场 (交易对)

• Method: GET

• Parameters

  Name	Located In	Description	Required	Schema
  offset	query	start with 0 ; default 0	no	integer
  limit	query	default 500 ; max 500	no	integer

• Responses

  code	msg	data
  0	success	[ Market ]
  1	error_msg	null

• Example

  {
    "code": 0,
    "msg": "ok",
    "data": [
      {
        "symbol": "BTC-A_USDT",
        "tradeTokenSymbol": "BTC-A",
        "quoteTokenSymbol": "USDT",
        "tradeToken": "tti_322862b3f8edae3b02b110b1",
        "quoteToken": "tti_973afc9ffd18c4679de42e93",
        "pricePrecision": 8,
        "quantityPrecision": 8
      }
    ]
  }
  

  {}
  

# /api/v1/order

查询订单信息

• Method: GET

• Parameters

  Name	Located In	Description	Required	Schema
  address	query	the buyer/seller address	yes	string
  orderId	query	the order id	yes	string

• Responses

  code	msg	data
  0	success	[ Order ]
  1	error_msg	null

• Example

  {
    "code": 0,
    "msg": "ok",
    "data": {
        "orderId": "quEOx/ai3o7Xyv9em+qJIbJu7pM=",
        "symbol": "VCP-4_VITE",
        "tradeTokenSymbol": "VCP.test",
        "quoteTokenSymbol": "VITE",
        "tradeToken": "tti_c2695839043cf966f370ac84",
        "quoteToken": "tti_5649544520544f4b454e6e40",
        "side": 1,
        "price": "6.00000000",
        "quantity": "1.00000000",
        "amount": "6.00000000",
        "executedQuantity": "0.00000000",
        "executedAmount": "0.00000000",
        "executedPercent": "0.00000000",
        "executedAvgPrice": "0.00000000",
        "fee": "0.00000000",
        "status": 1,
        "type": 0,
        "createTime": 1554722699
    }
  }
  

  {}
  

# /api/v1/orders/open

获取 Pending (挂单中) 状态的订单

• Method: GET

• Parameters

  Name	Located In	Description	Required	Schema
  address	query	the buyer/seller address	yes	string
  quoteTokenSymbol	query	Quote token symbol	no	string
  tradeTokenSymbol	query	Trade token symbol	no	string
  offset	query	Starting with 0 . Default 0	no	integer
  limit	query	Default 30 . Max 100	no	integer
  total	query	Total number required. 0 for not required and 1 for required. Default is not required and will return total=-1 in response	no	integer

• Responses

  code	msg	data
  0	success	OrderList
  1	error_msg	null

• Example

  {
    "code": 0,
    "msg": "ok",
    "data": {
      "order": [
        {
          "orderId": "quEOx/ai3o7Xyv9em+qJIbJu7pM=",
          "symbol": "VCP-4_VITE",
          "tradeTokenSymbol": "VCP.test",
          "quoteTokenSymbol": "VITE",
          "tradeToken": "tti_c2695839043cf966f370ac84",
          "quoteToken": "tti_5649544520544f4b454e6e40",
          "side": 1,
          "price": "6.00000000",
          "quantity": "1.00000000",
          "amount": "6.00000000",
          "executedQuantity": "0.00000000",
          "executedAmount": "0.00000000",
          "executedPercent": "0.00000000",
          "executedAvgPrice": "0.00000000",
          "fee": "0.00000000",
          "status": 1,
          "type": 0,
          "createTime": 1554722699
        }
      ],
      "total": 13
    }
  }
  

  {}
  

# /api/v1/orders

获取订单列表

• Method: GET

• Parameters

  Name	Located In	Description	Required	Schema
  address	query	the buyer/seller address	yes	string
  quoteTokenSymbol	query	the symbol of quote token	no	string
  tradeTokenSymbol	query	the symbol of trade token	no	string
  startTime	query	start time in Seconds	no	long
  endTime	query	end time in Seconds	no	long
  side	query	order side; Allowed value: [ 0 :buy, 1 :sell]	no	integer
  status	query	order status list; Allowed value: [ 1 :open, 2 :closed, 3 :canceled, 4 :failed]	no	integer
  offset	query	start with 0 ; default 0	no	integer
  limit	query	default 30 ; max 100	no	integer
  total	query	total number required, 0 for not required and 1 for required; default not required, return total=-1 in response	no	integer

• Responses

  code	msg	data
  0	success	OrderList
  1	error_msg	null

• Example

  {
    "code": 0,
    "msg": "ok",
    "data": {
      "order": [
        {
          "orderId": "ZDFDKEcwCs2BVs8fE8vULzb10/g=",
          "symbol": "CSTT-47E_VITE",
          "tradeTokenSymbol": "CSTT.test",
          "quoteTokenSymbol": "VITE",
          "tradeToken": "tti_b6f7019878fdfb21908a1547",
          "quoteToken": "tti_5649544520544f4b454e6e40",
          "side": 0,
          "price": "1.00000000",
          "quantity": "118222.20000000",
          "amount": "118222.20000000",
          "executedQuantity": "0.00000000",
          "executedAmount": "0.00000000",
          "executedPercent": "0.00000000",
          "executedAvgPrice": "0.00000000",
          "fee": "0.00000000",
          "status": 4,
          "type": 0,
          "createTime": 1554702092
        }
      ],
      "total": 1215
    }
  }
  

  {}
  

# /api/v1/ticker/24hr

获取 ticker 的 24 小时价格变化统计信息

• Method: GET

• Parameters

  Name	Located In	Description	Required	Schema
  symbols	query	market pair symbols; split by , ; e.g. ABC-000_VITE,ABC-001_VITE	no	string
  quoteTokenSymbol	query	the symbol of quote token	no	string
  quoteTokenCategory	query	the category of quote token,e.g. [ VITE , ETH , BTC , USDT ]	no	string

• Responses

  code	msg	data
  0	success	[ TickerStatistics ]
  1	error_msg	null

• Example

  {
    "code": 0,
    "msg": "ok",
    "data": [
      {
        "symbol": "CSTT-47E_VITE",
        "tradeTokenSymbol": "CSTT",
        "quoteTokenSymbol": "VITE",
        "tradeToken": "tti_b6f7019878fdfb21908a1547",
        "quoteToken": "tti_5649544520544f4b454e6e40",
        "openPrice": "1.00000000",
        "prevClosePrice": "0.00000000",
        "closePrice": "1.00000000",
        "priceChange": "0.00000000",
        "priceChangePercent": 0.0,
        "highPrice": "1.00000000",
        "lowPrice": "1.00000000",
        "quantity": "45336.20000000",
        "amount": "45336.20000000",
        "pricePrecision": 8,
        "quantityPrecision": 8
      }
    ]
  }
  

  {}
  

# /api/v1/ticker/bookTicker

获取 ticker 的最佳价格

• Method: GET

• Parameters

  Name	Located In	Description	Required	Schema
  symbol	query	market pair symbol. e.g. ABC-000_VITE	yes	string

• Responses

  code	msg	data
  0	success	BookTicker
  1	error_msg	null

• Example

  {
    "code": 0,
    "msg": "ok",
    "data": {
        "symbol": "CSTT-47E_VITE",
        "bidPrice": "1.00000000",
        "bidQuantity": "45336.20000000",
        "askPrice": "1.00000000",
        "askQuantity": "45336.20000000"
      }
  }
  

  {}
  

# /api/v1/trades

获取所有的交易 (订单撮合) 记录

• Method: GET

• Parameters

  Name	Located In	Description	Required	Schema
  symbol	query	market pair symbol ; e.g. BTC-000_VITE .	yes	string
  orderId	query	order id.	no	string
  startTime	query	start time in Seconds.	no	long
  endTime	query	end time in Seconds.	no	long
  side	query	order side. Allowed value: [ 0 :buy, 1 :sell].	no	integer
  offset	query	start with 0 ; default 0 .	no	integer
  limit	query	default 30 ; max 100 .	no	integer
  total	query	total number required ; 0 for not required and 1 for required; default not required, return total=-1 in response	no	integer

• Responses

  code	msg	data
  0	success	TradeList
  1	error_msg	null

• Example

  {
    "code": 0,
    "msg": "ok",
    "data": {
      "trade": [
        {
          "tradeId": "4EOgUqsCyZ73O4+A2gZuK9RfOXs=",
          "symbol": "VTT-F_ETH",
          "tradeTokenSymbol": "VTT",
          "quoteTokenSymbol": "ETH",
          "tradeToken": "tti_2736f320d7ed1c2871af1d9d",
          "quoteToken": "tti_06822f8d096ecdf9356b666c",
          "price": "0.10000000",
          "quantity": "1.00000000",
          "amount": "0.10000000",
          "time": 1554793244,
          "side": 0,
          "buyerOrderId": "DqpoIXTCT+4s1rMBFVCoWY9iDys=",
          "sellerOrderId": "FB4eiknqAQpIEOYi+HgamZOj/ac=",
          "buyFee": "0.00010000",
          "sellFee": "0.00010000",
          "blockHeight": 2806
        }
      ],
      "total": 1
    }
  }
  

  {}
  

# /api/v1/depth

获取市场 (交易对) 的深度

• Method: GET

• Parameters

  Name	Located In	Description	Required	Schema
  symbol	query	market pair symbol ; e.g. CSTT-47E_VITE .	yes	string
  limit	query	default 100 ; max 100 .	no	integer

• Responses

  code	msg	data
  0	success	[ MarketDepth ]
  1	error_msg	null

• Example

  {
    "code": 0,
    "msg": "ok",
    "data": {
      "asks": [
        {
          "price": "1.00000000",
          "quantity": "111233.50000000",
          "amount": "111233.50000000"
        }    
      ],
      "bids": [
        {
          "price": "2.00000000",
          "quantity": "111233.50000000",
          "amount": "111233.50000000"
        }
      ]
    }
  }
  

  {}
  

# /api/v1/klines

获取市场 (交易对) 的 K 线

• Method: GET

• Parameters

  Name	Located In	Description	Required	Schema
  symbol	query	market pair symbol ; e.g. CSTT-47E_VITE .	yes	string
  interval	query	interval. Allowed value: [ minute 、 hour 、 day 、 minute30 、 hour6 、 hour12 、 week ]	yes	string
  limit	query	default 500 ; max 1500 .	no	integer
  startTime	query	start time in Seconds.	no	integer
  endTime	query	end time in Seconds.	no	integer

• Responses

  code	msg	data
  0	success	[ MarketKline ]
  1	error_msg	null

• Example

  {
    "code": 0,
    "msg": "ok",
    "data": {
      "t": [
        1554207060
      ],
      "c": [
        1.0
      ],
      "p": [
        1.0
      ],
      "h": [
        1.0
      ],
      "l": [
        1.0
      ],
      "v": [
        12970.8
      ]
    }
  }
  

  {}
  

# /api/v1/deposit-withdraw

获取充提记录

• Method: GET

• Parameters

  Name	Located In	Description	Required	Schema
  address	query	the buyer/seller address	yes	string
  tokenId	query	token id.	yes	string
  offset	query	start with 0 ; default 0 .	no	integer
  limit	query	default 100 ; max 100 .	no	integer

• Responses

  code	msg	data
  0	success	DepositWithdrawList
  1	error_msg	null

• Example

  {
    "code": 0,
    "msg": "ok",
    "data": {
      "record": [
        {
          "time": 1555057049,
          "tokenSymbol": "VITE",
          "amount": "1000000.00000000",
          "type": 1
        }
      ],
      "total": 16
    }
  }
  

  {}
  

# /api/v1/exchange-rate

获取 Token 的汇率

• Method: GET

• Parameters

  Name	Located In	Description	Required	Schema
  tokenSymbols	query	token symbols ; split by , ; e.g. VITE,ETH .	no	string
  tokenIds	query	token ids ; split by , ; e.g. tti_5649544520544f4b454e6e40,tti_5649544520544f4b454e6e40 .	no	string

• Responses

  code	msg	data
  0	success	[ ExchangeRate ]
  1	error_msg	null

• Example

  {
    "code": 0,
    "msg": "ok",
    "data": [
      {
        "tokenId": "tti_5649544520544f4b454e6e40",
        "tokenSymbol": "VITE",
        "usdRate": 0.03,
        "cnyRate": 0.16
      }
    ]
  }
  

  {}
  

# /api/v1/usd-cny

获取 USD-CNY 的汇率

• Method: GET

• Parameters

  Name	Located In	Description	Required	Schema

• Responses

  code	msg	data
  0	success	double
  1	error_msg	null

• Example

  {
    "code": 0,
    "msg": "ok",
    "data": 6.849
  }
  

  {}
  

# /api/v1/time

获取服务器时间 (ms)

• Method: GET

• Parameters

  Name	Located In	Description	Required	Schema

• Responses

  code	msg	data
  0	success	long
  1	error_msg	null

• Example

  {
    "code": 0,
    "msg": "ok",
    "data": 1559033445000
  }
  

  {}
  

# WS 接入文档

# 1. 环境地址：

• 【Pre-mainnet】wss://vitex.vite.net/websocket
• 【测试】wss://vitex.vite.net/test/websocket
• op_type: ping 消息包需要至少 1 分钟周期发送，如果：心跳间隔超过 1 分钟后，注册的 event 会失效清理

# 2. 协议模型：

syntax = "proto3";
package protocol;
option java_package = "org.vite.data.dex.bean.protocol";
option java_outer_classname = "DexProto";
message DexProtocol {
    string client_id = 1; //Identify a single client
    string topics = 2; //见下面
    string op_type = 3; // sub,un_sub,ping,pong,push
    bytes message = 4; //proto数据
    int32 error_code = 5; //错误编码 0:normal, 1:illegal_client_id，2:illegal_event_key，3:illegal_op_type,5:visit limit
}

# 3. op_type 说明：

• sub, 表示订阅
• un_sub, 表示取消订阅
• ping, 表示心跳请求，保证 10s 内一次，用于判断客户端 client_id 是否有效；
• pong, 服务端响应，无须关注
• push, 表示服务推送数据

# 4. topics 说明：

支持单个订阅，多个订阅使用 , 分割；比如： xxx,xxx

# 5. message 数据格式定义

syntax = "proto3";
option java_package = "org.vite.data.dex.bean.proto";
option java_outer_classname = "DexPushMessage";
message TickerStatisticsProto {
    //symbol
    string symbol = 1;
    //symbol
    string tradeTokenSymbol = 2;
    //symbol
    string quoteTokenSymbol = 3;
    //tokenId
    string tradeToken = 4;
    //tokenId
    string quoteToken = 5;
    //价格
    string openPrice = 6;
    //价格
    string prevClosePrice = 7;
    //价格
    string closePrice = 8;
    //价格
    string priceChange = 9;
    //变化率
    string priceChangePercent = 10;
    //价格
    string highPrice = 11;
    //价格
    string lowPrice = 12;
    //数量
    string quantity = 13;
    //成交额
    string amount = 14;
    //price精度
    int32 pricePrecision = 15;
    //quantity精度
    int32 quantityPrecision = 16;
}
message TradeListProto {
    repeated TradeProto trade = 1;
}
message TradeProto {
    string tradeId = 1;
    //symbol
    string symbol = 2;
    //symbol
    string tradeTokenSymbol = 3;
    //symbol
    string quoteTokenSymbol = 4;
    //tokenId
    string tradeToken = 5;
    //tokenId
    string quoteToken = 6;
    //price
    string price = 7;
    //quantity
    string quantity = 8;
    //amount
    string amount = 9;
    //time
    int64 time = 10;
    //side
    int32 side = 11;
    //orderId
    string buyerOrderId = 12;
    //orderId
    string sellerOrderId = 13;
    //fee
    string buyFee = 14;
    //fee
    string sellFee = 15;
    //height
    int64 blockHeight = 16;
}
message KlineProto {
    int64 t = 1;
    double c = 2;
    double o = 3;
    double h = 4;
    double l = 5;
    double v = 6;
}
message OrderProto {
    //订单ID
    string orderId = 1;
    //symbol
    string symbol = 2;
    //symbol
    string tradeTokenSymbol = 3;
    //symbol
    string quoteTokenSymbol = 4;
    //tokenId
    string tradeToken = 5;
    //tokenId
    string quoteToken = 6;
    //方向
    int32 side = 7;
    //价格
    string price = 8;
    //数量
    string quantity = 9;
    //交易量
    string amount = 10;
    //成交Quantity
    string executedQuantity = 11;
    //成交Amount
    string executedAmount = 12;
    //成交率
    string executedPercent = 13;
    //均价
    string executedAvgPrice = 14;
    //手续费
    string fee = 15;
    //状态
    int32 status = 16;
    //类型
    int32 type = 17;
    //时间
    int64 createTime = 18;
    //地址
    string address = 19;
}
message DepthListProto {
    repeated DepthProto asks = 1;
    repeated DepthProto bids = 2;
}
message DepthProto {
    //价格
    string price = 1;
    //数量
    string quantity = 2;
    //交易量
    string amount = 3;
}