1 package org.oxerr.okcoin.rest; 2 3 import java.io.IOException; 4 import java.math.BigDecimal; 5 6 import javax.ws.rs.FormParam; 7 import javax.ws.rs.GET; 8 import javax.ws.rs.POST; 9 import javax.ws.rs.Path; 10 import javax.ws.rs.Produces; 11 import javax.ws.rs.QueryParam; 12 import javax.ws.rs.core.MediaType; 13 14 import org.oxerr.okcoin.rest.dto.AccountRecords; 15 import org.oxerr.okcoin.rest.dto.BatchTradeResult; 16 import org.oxerr.okcoin.rest.dto.BorrowOrderInfo; 17 import org.oxerr.okcoin.rest.dto.BorrowResult; 18 import org.oxerr.okcoin.rest.dto.BorrowsInfo; 19 import org.oxerr.okcoin.rest.dto.CancelOrderResult; 20 import org.oxerr.okcoin.rest.dto.CandlestickChart; 21 import org.oxerr.okcoin.rest.dto.Depth; 22 import org.oxerr.okcoin.rest.dto.LendDepth; 23 import org.oxerr.okcoin.rest.dto.OrderFee; 24 import org.oxerr.okcoin.rest.dto.OrderHistory; 25 import org.oxerr.okcoin.rest.dto.OrderResult; 26 import org.oxerr.okcoin.rest.dto.TickerResponse; 27 import org.oxerr.okcoin.rest.dto.Trade; 28 import org.oxerr.okcoin.rest.dto.TradeResult; 29 import org.oxerr.okcoin.rest.dto.Type; 30 import org.oxerr.okcoin.rest.dto.UnrepaymentsInfo; 31 import org.oxerr.okcoin.rest.dto.UserInfo; 32 import org.oxerr.okcoin.rest.dto.Withdrawal; 33 34 import si.mazi.rescu.ParamsDigest; 35 36 /** 37 * RESTful API. 38 */ 39 @Path("/api/v1/") 40 @Produces(MediaType.APPLICATION_JSON) 41 public interface OKCoin { 42 43 /** 44 * Get price ticker. 45 * 46 * @param symbol the symbol: btc_cny, ltc_cny. 47 * @return price ticker. 48 * @throws IOException indicates I/O exception. 49 */ 50 @GET 51 @Path("ticker.do") 52 TickerResponse getTicker(@QueryParam("symbol") String symbol) 53 throws IOException; 54 55 /** 56 * Get market depth. 57 * 58 * @param symbol the symbol: btc_cny, ltc_cny. 59 * @param size must be between 1 - 200 60 * @param merge 1 (merge depth) 61 * @return market depth. 62 * @throws IOException indicates I/O exception. 63 */ 64 @GET 65 @Path("depth.do") 66 Depth getDepth( 67 @QueryParam("symbol") String symbol, 68 @QueryParam("size") Integer size, 69 @QueryParam("merge") Integer merge) 70 throws IOException; 71 72 /** 73 * Get trade history. 74 * 75 * @param symbol the symbol: btc_cny, ltc_cny. 76 * @param since get 600 pieces of data starting from the given tid(optional). 77 * @return the trade history. 78 * @throws IOException indicates I/O exception. 79 */ 80 @GET 81 @Path("trades.do") 82 Trade[] getTrades( 83 @QueryParam("symbol") String symbol, 84 @QueryParam("since") Long since) 85 throws IOException; 86 87 /** 88 * Get BTC/LTC candlestick data. 89 * 90 * @param symbol the symbol: btc_cny, ltc_cny. 91 * @param type 92 * <ul> 93 * <li>1min : 1 minute candlestick data</li> 94 * <li>3min : 3 minutes candlestick data</li> 95 * <li>5min : 5 minutes candlestick data</li> 96 * <li>15min : 15 minutes candlestick data</li> 97 * <li>30min : 30 minutes candlestick data</li> 98 * <li>1day : 1 day candlestick data</li> 99 * <li>3day : 3 days candlestick data</li> 100 * <li>1week : 1 week candlestick data</li> 101 * <li>1hour : 1 hour candlestick data</li> 102 * <li>2hour : 2 hours candlestick data</li> 103 * <li>4hour : 4 hours candlestick data</li> 104 * <li>6hour : 6 hours candlestick data</li> 105 * <li>12hour : 12 hours candlestick data</li> 106 * </ul> 107 * @param size specify data size to be acquired. 108 * @param since timestamp(eg:1417536000000). 109 * data after the timestamp will be returned 110 * @return candlestick. 111 * @throws IOException indicates I/O exception. 112 */ 113 @GET 114 @Path("kline.do") 115 CandlestickChart getCandlestickChart( 116 @QueryParam("symbol") String symbol, 117 @QueryParam("type") String type, 118 @QueryParam("size") Integer size, 119 @QueryParam("since") Long since) 120 throws IOException; 121 122 /** 123 * Get top 10 lending entries. 124 * 125 * @param symbol the symbol, such as btc_cny, ltc_cny, cny. 126 * @return the top 10 lending entries. 127 * @throws IOException indicates I/O exception. 128 */ 129 @GET 130 @Path("lend_depth.do") 131 LendDepth getLendDepth( 132 @QueryParam("symbol") String symbol) 133 throws OKCoinException, IOException; 134 135 /** 136 * Get user account info. 137 * 138 * @param apiKey API key of the user. 139 * @param sign signature of request parameters 140 * @return user account info. 141 * @throws OKCoinException indicates request failed. 142 * @throws IOException indicates I/O exception. 143 */ 144 @POST 145 @Path("userinfo.do") 146 UserInfo getUserInfo( 147 @FormParam("api_key") String apiKey, 148 @FormParam("sign") ParamsDigest sign) 149 throws OKCoinException, IOException; 150 151 /** 152 * Place order. 153 * 154 * @param apiKey the API key of the user. 155 * @param symbol the symbol: btc_cny, ltc_cny. 156 * @param type order type: limit order(buy/sell) market order(buy_market/sell_market). 157 * @param price order price. For limit orders, the price must be 158 * between 0~1,000,000. IMPORTANT: for market buy orders, the price is to 159 * total amount you want to buy, and it must be higher than the current 160 * price of 0.01 BTC (minimum buying unit) or 0.1 LTC. 161 * @param amount order quantity. Must be higher than 0.01 for BTC, or 0.1 for LTC. 162 * @param sign signature of request parameters 163 * @return 164 * result: true means order placed successfully 165 * order_id: order ID of the newly placed order 166 * @throws OKCoinException indicates request failed. 167 * @throws IOException indicates I/O exception. 168 */ 169 @POST 170 @Path("trade.do") 171 TradeResult trade( 172 @FormParam("api_key") String apiKey, 173 @FormParam("symbol") String symbol, 174 @FormParam("type") Type type, 175 @FormParam("price") BigDecimal price, 176 @FormParam("amount") BigDecimal amount, 177 @FormParam("sign") ParamsDigest sign) 178 throws OKCoinException, IOException; 179 180 /** 181 * Get Trade History (Not for Personal). 182 * 183 * @param apiKey the API key of the user. 184 * @param symbol the symbol: btc_cny, ltc_cny. 185 * @param since get 600 pieces of data starting from the given tid (Required). 186 * @param sign signature of request parameters. 187 * @return the trade history. 188 * @throws OKCoinException indicates request failed. 189 * @throws IOException indicates I/O exception. 190 */ 191 @POST 192 @Path("trade_history.do") 193 Trade[] getTradeHistory( 194 @FormParam("api_key") String apiKey, 195 @FormParam("symbol") String symbol, 196 @FormParam("since") Long since, 197 @FormParam("sign") ParamsDigest sign 198 ) throws OKCoinException, IOException; 199 200 /** 201 * Batch trade. 202 * 203 * @param apiKey the API key of the user. 204 * @param symbol the symbol: btc_cny, ltc_cny. 205 * @param type optional, order type for limit orders (buy/sell). 206 * @param ordersData JSON string Example: [{price:3,amount:5,type: 207 * 'sell'},{price:3,amount:3,type:'buy'},{price:3,amount:3}] max 208 * order number is 5，for 'price' and 'amount' parameter, refer to 209 * trade/API. Final order type is decided primarily by 'type' 210 * field within 'orders_data' and subsequently by 'type' field 211 * (if no 'type' is provided within 'orders_data' field) 212 * @param sign signature of request parameters. 213 * @return 214 * result: true indicates order successfully placed 215 * order_id: order ID 216 * Note: return true if any one order is placed successfully 217 * returned orders info and 'orders_data' are in same sequence 218 * if fail to place order: order_id is -1 219 * @throws OKCoinException indicates request failed. 220 * @throws IOException indicates I/O exception. 221 */ 222 @POST 223 @Path("batch_trade.do") 224 BatchTradeResult batchTrade( 225 @FormParam("api_key") String apiKey, 226 @FormParam("symbol") String symbol, 227 @FormParam("type") Type type, 228 @FormParam("orders_data") String ordersData, 229 @FormParam("sign") ParamsDigest sign) 230 throws OKCoinException, IOException; 231 232 /** 233 * Cancel orders. 234 * 235 * @param apiKey the API key of the user. 236 * @param symbol the symbol: btc_cny, ltc_cny. 237 * @param orderId order ID (multiple orders are separated by a comma ',', 238 * Max of 3 orders are allowed per request) 239 * @param sign signature of request parameters. 240 * @return 241 * result: request result (applicable to single order) 242 * order_id: order ID (applicable to single order) 243 * success: success order IDs (applicable to batch orders) 244 * error: failed order IDs (applicable to batch orders) 245 * @throws OKCoinException indicates request failed. 246 * @throws IOException indicates I/O exception. 247 */ 248 @POST 249 @Path("cancel_order.do") 250 CancelOrderResult cancelOrder( 251 @FormParam("api_key") String apiKey, 252 @FormParam("symbol") String symbol, 253 @FormParam("order_id") String orderId, 254 @FormParam("sign") ParamsDigest sign) 255 throws OKCoinException, IOException; 256 257 /** 258 * Get order info. 259 * 260 * @param apiKey the API key of the user. 261 * @param symbol the symbol: btc_cny, ltc_cny. 262 * @param orderId if order_id is -1, then return all unfilled orders, 263 * otherwise return the order specified 264 * @param sign signature of request parameters. 265 * @return the order with the specified order ID or all unfilled orders. 266 * @throws OKCoinException indicates request failed. 267 * @throws IOException indicates I/O exception. 268 */ 269 @POST 270 @Path("order_info.do") 271 OrderResult getOrder( 272 @FormParam("api_key") String apiKey, 273 @FormParam("symbol") String symbol, 274 @FormParam("order_id") long orderId, 275 @FormParam("sign") ParamsDigest sign) 276 throws OKCoinException, IOException; 277 278 /** 279 * Get order information in batch. 280 * 281 * @param apiKey the API key of the user. 282 * @param symbol the symbol: btc_cny, ltc_cny. 283 * @param type query type: 0 for unfilled (open) orders, 1 for filled orders 284 * @param orderId order ID (multiple orders are separated by ',', 285 * 50 orders at most are allowed per request). 286 * @param sign signature of request parameters 287 * @return order information. 288 * @throws OKCoinException indicates request failed. 289 * @throws IOException indicates I/O exception. 290 */ 291 @POST 292 @Path("orders_info.do") 293 OrderResult getOrders( 294 @FormParam("api_key") String apiKey, 295 @FormParam("symbol") String symbol, 296 @FormParam("type") int type, 297 @FormParam("order_id") String orderId, 298 @FormParam("sign") ParamsDigest sign) 299 throws OKCoinException, IOException; 300 301 /** 302 * Returns the most recent 7 days orders. 303 * 304 * @param apiKey the API key of the user. 305 * @param symbol the symbol: btc_cny, ltc_cny. 306 * @param status query status: 0 for unfilled orders, 1 for filled orders. 307 * @param currentPage current page number. 308 * @param pageLength number of orders returned per page, maximum 200. 309 * @param sign signature of request parameters 310 * @return recent orders with specified parameters, 311 * only the most recent 7 days are returned. 312 * @throws OKCoinException indicates request failed. 313 * @throws IOException indicates I/O exception. 314 */ 315 @POST 316 @Path("order_history.do") 317 OrderHistory getOrderHistory( 318 @FormParam("api_key") String apiKey, 319 @FormParam("symbol") String symbol, 320 @FormParam("status") int status, 321 @FormParam("current_page") int currentPage, 322 @FormParam("page_length") int pageLength, 323 @FormParam("sign") ParamsDigest sign) 324 throws OKCoinException, IOException; 325 326 /** 327 * BTC/LTC Withdraw. 328 * 329 * @param apiKey the API key of the suer. 330 * @param symbol the symbol: BTC, LTC. 331 * @param chargeFee network transaction fee. By default, fee is between 332 * 0.0001 - 0.01 for BTC, and 0.001 - 0.2 for LTC, transaction gets 333 * confirmed faster with higher fees. For withdraws to another OKCoin 334 * address, chargefee can be 0 and the withdraw will be 0 confirmation 335 * as well. 336 * @param tradePassword trade/admin password. 337 * @param withdrawAddress withdraw address. 338 * @param withdrawAmount withdraw amount in BTC or LTC. 339 * @param sign signature of request parameters. 340 * @return 341 * withdraw_id: withdrawal request ID 342 * result: true means request successful 343 * @throws OKCoinException indicates request failed. 344 * @throws IOException indicates I/O exception. 345 */ 346 @POST 347 @Path("withdraw.do") 348 Withdrawal withdraw( 349 @FormParam("api_key") String apiKey, 350 @FormParam("symbol") String symbol, 351 @FormParam("chargefee") BigDecimal chargeFee, 352 @FormParam("trade_pwd") String tradePassword, 353 @FormParam("withdraw_address") String withdrawAddress, 354 @FormParam("withdraw_amount") BigDecimal withdrawAmount, 355 @FormParam("sign") ParamsDigest sign) 356 throws OKCoinException, IOException; 357 358 /** 359 * Withdrawal Cancellation Request. 360 * 361 * @param apiKey the API key of the user. 362 * @param symbol the symbol: BTC, LTC. 363 * @param withdrawId withdrawal request ID. 364 * @param sign signature of request parameters. 365 * @return 366 * result: true for success, false for error 367 * withdraw_id: withdrawal request ID 368 * @throws OKCoinException indicates request failed. 369 * @throws IOException indicates I/O exception. 370 */ 371 @POST 372 @Path("cancel_withdraw.do") 373 Withdrawal cancelWithdraw( 374 @FormParam("api_key") String apiKey, 375 @FormParam("symbol") String symbol, 376 @FormParam("withdraw_id") long withdrawId, 377 @FormParam("sign") ParamsDigest sign) 378 throws OKCoinException, IOException; 379 380 /** 381 * Query fee. 382 * 383 * @param apiKey the API key of the user. 384 * @param symbol the symbol: btc_cny, ltc_cny. 385 * @param orderId the order ID. 386 * @param sign the signature of request parameters. 387 * @return the order fee. 388 * @throws OKCoinException indicates request failed. 389 * @throws IOException indicates I/O exception. 390 */ 391 @POST 392 @Path("order_fee.do") 393 OrderFee getOrderFee( 394 @FormParam("api_key") String apiKey, 395 @FormParam("symbol") String symbol, 396 @FormParam("order_id") long orderId, 397 @FormParam("sign") ParamsDigest sign) 398 throws OKCoinException, IOException; 399 400 /** 401 * Get user borrow information. 402 * 403 * @param apiKey the API key of the user. 404 * @param symbol the symbol, such as btc_cny, ltc_cny, cny. 405 * @param sign signature of request parameters. 406 * @return the borrow information of the user. 407 * @throws OKCoinException indicates request failed. 408 * @throws IOException indicates I/O exception. 409 */ 410 @POST 411 @Path("borrows_info.do") 412 BorrowsInfo getBorrowsInfo( 413 @FormParam("api_key") String apiKey, 414 @FormParam("symbol") String symbol, 415 @FormParam("sign") ParamsDigest sign) 416 throws OKCoinException, IOException; 417 418 /** 419 * Request borrow. 420 * 421 * @param apiKey the API key of the user. 422 * @param symbol the symbol, such as btc_cny, ltc_cny, cny. 423 * @param days days of borrow: three, seven, fifteen, thirty, sixty, ninety. 424 * @param amount borrow amount. 425 * @param rate borrow rate [0.0001, 0.01]. 426 * @param sign signature of request parameters. 427 * @return the borrow. 428 * @throws OKCoinException indicates request failed. 429 * @throws IOException indicates I/O exception. 430 */ 431 @POST 432 @Path("borrow_money.do") 433 BorrowResult borrowMoney( 434 @FormParam("api_key") String apiKey, 435 @FormParam("symbol") String symbol, 436 @FormParam("days") String days, 437 @FormParam("amount") BigDecimal amount, 438 @FormParam("rate") BigDecimal rate, 439 @FormParam("sign") ParamsDigest sign) 440 throws OKCoinException, IOException; 441 442 /** 443 * Cancel borrow order. 444 * 445 * @param apiKey the API key of the user. 446 * @param symbol the symbol, such as btc_cny, ltc_cny, cny. 447 * @param borrowId the borrow order ID. 448 * @param sign signature of request parameters. 449 * @return the cancelled borrow order. 450 * @throws OKCoinException indicates request failed. 451 * @throws IOException indicates I/O exception. 452 */ 453 @POST 454 @Path("cancel_borrow.do") 455 BorrowResult cancelBorrow( 456 @FormParam("api_key") String apiKey, 457 @FormParam("symbol") String symbol, 458 @FormParam("borrow_id") long borrowId, 459 @FormParam("sign") ParamsDigest sign) 460 throws OKCoinException, IOException; 461 462 /** 463 * Get borrowing order info. 464 * 465 * @param apiKey the API key of the user. 466 * @param borrowId the borrow order ID. 467 * @param sign signature of request parameters. 468 * @return the borrowing order info. 469 * @throws OKCoinException indicates request failed. 470 * @throws IOException indicates I/O exception. 471 */ 472 @POST 473 @Path("borrow_order_info.do") 474 BorrowOrderInfo getBorrowOrderInfo( 475 @FormParam("api_key") String apiKey, 476 @FormParam("borrow_id") long borrowId, 477 @FormParam("sign") ParamsDigest sign) 478 throws OKCoinException, IOException; 479 480 /** 481 * Pay off debt. 482 * 483 * @param apiKey the API key of the user. 484 * @param borrowId the borrow order ID. 485 * @param sign signature of request parameters. 486 * @return the borrowing order info. 487 * @throws OKCoinException indicates request failed. 488 * @throws IOException indicates I/O exception. 489 */ 490 @POST 491 @Path("repayment.do") 492 BorrowResult repay( 493 @FormParam("api_key") String apiKey, 494 @FormParam("borrow_id") long borrowId, 495 @FormParam("sign") ParamsDigest sign) 496 throws OKCoinException, IOException; 497 498 /** 499 * Get debt list. 500 * 501 * @param apiKey the API key of the user. 502 * @param symbol the symbol, such as btc_cny, ltc_cny, cny. 503 * @param currentPage the current page number. 504 * @param pageLength data entries number per page, maximum 50. 505 * @param sign signature of request parameters 506 * @return the debt list. 507 * @throws OKCoinException indicates request failed. 508 * @throws IOException indicates I/O exception. 509 */ 510 @POST 511 @Path("unrepayments_info.do") 512 UnrepaymentsInfo getUnrepaymentsInfo( 513 @FormParam("api_key") String apiKey, 514 @FormParam("symbol") String symbol, 515 @FormParam("current_page") int currentPage, 516 @FormParam("page_length") int pageLength, 517 @FormParam("sign") ParamsDigest sign) 518 throws OKCoinException, IOException; 519 520 /** 521 * Get user deposits or withdraw Records. 522 * 523 * @param apiKey the API key of the user. 524 * @param symbol the symbol: btc_cny, ltc_cny, cny 525 * @param type 0: deposits, 1: withdraw. 526 * @param currentPage the current page number. 1 based. 527 * @param pageLength the data entries number per page, maximum 50. 528 * @param sign the signature of request parameters. 529 * @return user deposits or withdraw records. 530 * @throws OKCoinException indicates request failed. 531 * @throws IOException indicates I/O exception. 532 */ 533 @POST 534 @Path("account_records.do") 535 AccountRecords getAccountRecords( 536 @FormParam("api_key") String apiKey, 537 @FormParam("symbol") String symbol, 538 @FormParam("type") int type, 539 @FormParam("current_page") int currentPage, 540 @FormParam("page_length") int pageLength, 541 @FormParam("sign") ParamsDigest sign) 542 throws OKCoinException, IOException; 543 544 }