REST Authenticated Endpoints

You can access the following endpoints:

product-endpoint:
- https://api.rightbtc.com
test-api-endpoint:
- https://test-api.rightbtc.com

product-endpoint provides real access of the RightBTC platform. Otherwise, test-api-endpoint is a dummy environment of RightBTC, you can apply for testing api/secret pairs in order to test with some BTC/ETP/USD/DNA balance.

{
"display":"KrAZLSCA", // your DUMMY SECRET Key(it won't be shown on product env, NEVER)
"email":"wKkSBnXu", // your DUMMY trader api key
"mnem":"wKkSBnXu"
}

All Authenticated Endpoints use POST requests.
All examples assume the test-api-endpoint.

See How to setup HTTP Headers

Trader Info

Trader Info

A Trader belongs to a account. Basic info of this trader.

/v1/trader/info

Field Type Description
null [null] null

No fields required.

$ curl --location --request POST "http://test-api.rightbtc.com/v1/trader/info" \
--header "APIKEY: apiKey" \
--header "SIGNATURE: signature" \
--header "NONCE: 1561346769" \
--header "Content-Type: application/json"
{
"mnem": "trader_id",
"display": "Hao Chen Display",
"email": "trader_id or user_id",
"makerFee": 0.002,
"takerFee": 0.002,
"orderLimitSec": 10,
"requestLimitSec": 20,
"canLending": 0,
"marginable": 1,
"maxLeverage": 3,
"marginState": 1,
"specializedFee": []
}
Key Type Description
mnem [string] global unique trader id
display [string] describtion of this trader
email [string] api key id
takerFee [decimal] taking order fee when your order is matched as role TAKER, priority over global market settings.
makerFee [decimal] fee when your order is matched as role MAKER, priority over global market settings.
orderLimitSec [integer] ORDERS(create/cancel/cancel all/multi cancel) rate limits, defaults to 10 commits per second
requestLimitSec [integer] FUNDING(transfer/loan/repay/margin info) rate limits, defaults to 20 commits per second
canLending [integer] peer to peer lending permission flag (debit), 0 to false, 1 to true
marginable [integer] margin trading permission flag, defaults to 0 means false, 1 to true when you signed the risk agreement from webpages.
maxLeverage [double] max leverage for your postion for margin trading, defualts to 3
marginState [integer] forced liquidation to 0, defualts to 1
specializedFee [array] specialized fee for markets, defaults to null array, top priority over all of fee settings.

Trader Balances

Trader Balances

An array of asset balances.
There are 3 wallet types “EXCHANGE” “MARGIN” “FUNDING” for your balances.

/v1/trader/balances

Field Type Required Description
asset [string] No specify an asset mnem, if not sent then returns a list of trader’s balances of “EXCHANGE” “MARGIN” “FUNDING”.
$ curl --location --request POST "http://test-api.rightbtc.com/v1/trader/balances" \
--header "APIKEY: apiKey" \
--header "SIGNATURE: signature" \
--header "NONCE: 1561346769" \
--header "Content-Type: application/json"
{
"EXCHANGE": [
{
"asset": "BTC",
"balance": 500000000,
"available": 500000000,
"denom": 100000000
},
{
"asset": "ETP",
"balance": 7000000000000000,
"available": 7000000000000000,
"denom": 100000000
},
{
"asset": "USDT",
"balance": 600000000000000,
"available": 600000000000000,
"denom": 100000000
}
],
"MARGIN": [],
"FUNDING": []
}

balance:500000000 and denom = 100000000 is equal to 5 BTC = 500000000/100000000

if sent field asset then returns JSON as following.

{
"EXCHANGE": {
"asset": "BTC",
"balance": 50000000000,
"available": 49999965200,
"denom": 100000000
},
"MARGIN": {
"asset": "BTC",
"balance": 150010000000,
"available": 150010000000,
"denom": 100000000
},
"FUNDING": {
"asset": "BTC",
"loan": 10000000,
"contributes": 12500,
"lend": 0,
"offer": 0,
"commissions": 0,
"balance": -10000000,
"available": -10000000
}
}
{
"EXCHANGE": {
"asset": "BTC",
"balance": 50000000000,
"available": 50000000000,
"denom": 100000000
},
"MARGIN": null,
"FUNDING": null
}

EXCHANGE and MARGIN fields

Key Type Description
asset [string] mnem of asset
balance [integer] balance
available [interger] available amount to trade
denom [interger] defaults to 100000000 = 8 decimal places once asset listed never be changed.

FUNDING fields, denom shares EXCHANGE’s

Key Type Description
asset [string] mnem of asset
loan [integer] loaned amount pending on repay
cotributes [interger] interest amount pending on repay
lend [interger] lended amount pending on
offer [interger] net-transfering-in from other wallet types, available
commissions [interger] accumulative total commissions from lending
balance [integer] balance = offer - loan
available [interger] available amount to debit = balance - lend

/v1/trader/balance

Field Type Required Description
asset [string] No specify an asset mnem, if not sent then returns a list of trader’s “EXCHANGE” balances.
from [string] No specify an wallet type of “EXCHANGE” “MARGIN” “FUNDING”, if not sent then returns “EXCHANGE” balance by default.
$ curl --location --request POST "http://test-api.rightbtc.com/v1/trader/balance" \
--header "APIKEY: apiKey" \
--header "SIGNATURE: signature" \
--header "NONCE: 1561346769" \
--header "Content-Type: application/json"
--data "{\"asset\":\"BTC\",\"from\":\"EXCHANGE\"}"
{
"asset": "BTC",
"balance": 500000000,
"available": 400000000,
"denom": 100000000,
}

if NOT sent field asset then returns JSON array as following.
Always list those assets which had incoming (bought/deposits).

[
{
"asset": "BTC",
"balance": 500000000,
"available": 400000000,
"denom": 100000000,
},
{
"asset": "ETP",
"balance": 20000000000,
"available": 19800000000,
"denom": 100000000,
}
]

if sent field from is one of “MARGIN” “FUNDING” which has no incoming(funding/margin/transfer).
it will returns:

[]

if sent field asset under field from is one of “MARGIN” “FUNDING” which has no incoming(funding/margin/transfer).
it will returns:

null

/v1/trader/transfer

Field Type Required Description
asset [string] Yes specify an asset mnem.
from [string] Yes specify an wallet type of “EXCHANGE” “MARGIN” “FUNDING”.
to [string] Yes specify an wallet type of “EXCHANGE” “MARGIN” “FUNDING”.
amount [integer] Yes how many amount you want to transfer.
$ curl --location --request POST "http://test-api.rightbtc.com/v1/trader/balance" \
--header "APIKEY: apiKey" \
--header "SIGNATURE: signature" \
--header "NONCE: 1561346769" \
--header "Content-Type: application/json"
--data "{\"asset\":\"USDT\",\"from\":\"EXCHANGE\",\"to\":\"MARGIN\",\"amount\":100000}"
{
"MARGIN": {
"asset": "USDT",
"balance": 100000,
"available": 100000,
"denom": 100000000
},
"EXCHANGE": {
"asset": "USDT",
"balance": 600000000100000,
"available": 600000000100000,
"denom": 100000000
}
}

Trader Margin

Trader Loan and Repay and Info

/v1/margin/loan

Field Type Required Description
asset [string] Yes specify an asset mnem.
amount [integer] Yes how many amount you want to loan.
$ curl --location --request POST "http://test-api.rightbtc.com/v1/margin/loan" \
--header "APIKEY: apiKey" \
--header "SIGNATURE: signature" \
--header "NONCE: 1561346769" \
--header "Content-Type: application/json"
--data "{\"asset\":\"BTC\",\"amount\":10000000}"
{
"FUNDING": {
"asset": "BTC",
"loan": 20000000,
"contributes": 25000,
"lend": 0,
"offer": 0,
"commissions": 0,
"balance": -20000000,
"available": -20000000,
"denom": 100000000,
"trader": "chenhao",
"lends": 0,
"loans": 20000000
}
}

/v1/margin/repay

Field Type Required Description
asset [string] Yes specify an asset mnem.
amount [integer] Yes how many amount you want to repay.
$ curl --location --request POST "http://test-api.rightbtc.com/v1/margin/repay" \
--header "APIKEY: apiKey" \
--header "SIGNATURE: signature" \
--header "NONCE: 1561346769" \
--header "Content-Type: application/json"
--data "{\"asset\":\"BTC\",\"amount\":150000000}"
{
"FUNDING": {
"asset": "BTC",
"loan": 19825000,
"contributes": 0,
"lend": 0,
"offer": 0,
"commissions": 0,
"balance": -19825000,
"available": -19825000,
"denom": 100000000,
"trader": "chenhao",
"lends": 0,
"loans": 20000000
}
}

/v1/margin/info

Field Type Required Description
asset [string] No specify an asset mnem.
$ curl --location --request POST "http://test-api.rightbtc.com/v1/margin/info" \
--header "APIKEY: apiKey" \
--header "SIGNATURE: signature" \
--header "NONCE: 1561346769" \
--header "Content-Type: application/json"
--data "{\"asset\":\"BTC\"}"
{
"maxAvailable": 1109545722047,
"maxTransferable": 150019800000
}

if NOT sent field asset, it will returns:

{
"marginValue": 5.54953e+15,
"unpaidValue": 1.19952e+12
}
Key Type Description
maxAvailable [double] max Available to loan under specified asset.
maxTransferable [double] max Available to transfer under specified asset.
Key Type Description
marginValue [double] margin amount in dollars
unpaidValue [double] unpaid amount in dollars

Create New Order

Order/New

Palace a new order to a market.
EXCHANGE trading supports LIMIT,MARKET,STOP,FOK,IOC,TRAILINGSTOP and Hidden orders(non-display in orderbooks through public api calls).
MARGIN trading supports MarginLIMIT,MarginMARKET,MarginSTOP,MarginFOK,MarginIOC,MarginTRAILINGSTOP and Hidden orders(non-display in orderbooks through public api calls).

/v1/order/new

Field Type Required Description
market [string] Yes mnem of market from markets
side [string] Yes order side “BUY” or “SELL”
lots [lots] Yes order lots, precision is defined by contract
ticks [ticks] Yes order ticks, precision is defined by contract
type [integer] No order types defaults to 0, 0-LIMIT;1-MARKET;2-STOP;3-TRAILINGSTOP;4-FOK;5-IOC; 10-MarginLIMIT;11-MarginMARKET;12-MarginSTOP;13-MarginTRAILINGSTOP;14-MarginFOK;15-MarginIOC
factor [integer] No order attribute, 2-HIDDEN , defaults to null (non-Hidden)
$ curl --location --request POST "http://test-api.rightbtc.com/v1/order/new" \
--header "APIKEY: apiKey" \
--header "SIGNATURE: signature" \
--header "NONCE: 1561346769" \
--header "Content-Type: application/json"
{
"id": 100000011,
"market": "BTCUSD",
"state": "ACCEPTED"
}
Key Type Description
id [integer] id of order
market [string] mnem of market
state [string] Always “ACCEPTED” if POST ok, asynchronous processing

Order is unique identitfied by market and id(primary key), not single id.

Cancel Active Order

Order/Cancel

Order/Cancel to cancel one single order
Order/Cancel/Multi to cancel multiable orders
Order/Cancel/All to cancel all orders

/v1/order/cancel

Field Type Required Description
id [integer] Yes id of order
market [string] Yes mnem of market from markets
$ curl --location --request POST "http://test-api.rightbtc.com/v1/order/cancel" \
--header "APIKEY: apiKey" \
--header "SIGNATURE: signature" \
--header "NONCE: 1561346769" \
--header "Content-Type: application/json"
{
"id": 100000011,
"market": "BTCUSD",
"state": "ACCEPTED"
}
Key Type Description
id [integer] id of order
market [string] mnem of market
state [string] Always “ACCEPTED” if POST ok, asynchronous processing

/v1/order/cancel/multi

Field Type Required Description
ids [array of integer] Yes array of id of each order
market [string] Yes mnem of market from markets
$ curl --location --request POST "http://test-api.rightbtc.com/v1/order/cancel/multi" \
--header "APIKEY: apiKey" \
--header "SIGNATURE: signature" \
--header "NONCE: 1561346769" \
--header "Content-Type: application/json"
{
"idsOnError": [100000011,100000012]
"market": "BTCUSD",
"state": "ACCEPTED"
}
Key Type Description
idsOnError [array of integer] id of order which has exception on cancel
market [string] mnem of market
state [string] Always “ACCEPTED” if POST ok, asynchronous processing

/v1/order/cancel/all

This API call will cancel all avtive orders under a market.

Field Type Required Description
market [string] Yes mnem of market from markets
{
"market": "BTCUSD",
"state": "ACCEPTED"
}

Query Active Orders

Order/Status

Order State must be in [NEW,TRADE,CANCEL] and [PENDING,ACCEPTED]

  • NEW - order is newly placed, not filled yet.
  • TRADE - order is full_filled or particularly_filled (you can check resd for particularly or full filled).
  • CANCEL - order is canceled by trader or system (STOP/FOK/IOC).
  • PENDING - a temporary state between acception and execution, extremely short.
  • ACCEPTED - a temporary state, extremely short.

This API provides ACTIVE order query ONLY.
If order is done(CANCEL/full_filled), please use History/Order, otherwise order not found(404).

/v1/order/status

Field Type Required Description
id [integer] No id of order, query a active order under a market.
market [string] No if specify mnem of market, then return orders under this market. if not specified, return all active orders.
page [integer] No page index, defaults to page 1, each page lists max 100 orders.
factor [integer] No 14 to EXCHANGE orders, 128 to MARGIN orders, defaults to null returns ALL of active orders
$ curl --location --request POST "http://test-api.rightbtc.com/v1/order/status" \
--header "APIKEY: apiKey" \
--header "SIGNATURE: signature" \
--header "NONCE: 1561346769" \
--header "Content-Type: application/json"
{
"orders": [
{
"trader": "trader_id",
"market": "BTCUSD",
"contr": "BTCUSD",
"id": 100000015,
"ref": null,
"type": "LIMIT",
"state": "TRADE",
"side": "BUY",
"lots": 1000000,
"ticks": 1100,
"resd": 800000,
"exec": 200000,
"cost": 220000000,
"lastLots": 200000,
"lastTicks": 1100,
"created": 1561022000931,
"modified": 1561022008615
},
{
"trader": "trader_id",
"market": "BTCUSD",
"contr": "BTCUSD",
"id": 100000018,
"ref": null,
"type": "MarginLIMIT",
"state": "NEW",
"side": "SELL",
"lots": 200000,
"ticks": 5000,
"resd": 200000,
"exec": 0,
"cost": 0,
"hidden": true,
"lastLots": null,
"lastTicks": null,
"created": 1561022064035,
"modified": 1561022064035
}
],
"page": 1,
"total_pages": 1,
"total_count": 2
}
Key Type Description
trader [string] mnem of trader
market [string] mnem of market
contr [string] mnem of contract of market
id [integer] id of order
ref [string] client id , defaults to null
type [string] enum of “LIMIT” “MARKET” “STOP” “TRAILINGSTOP” “FOK” “IOC” for EXCHANGE orders, “MarginLIMIT” “MarginMARKET” “MarginSTOP” “MarginTRAILINGSTOP” “MarginFOK” “MarginIOC” for MARGIN orders
state [string] enum of “NEW” “TRADE” “CANCEL” “PENDING”
side: [string] enum of “BUY” “SELL”
lots: [lots] order lots filled by trader when created
ticks: [ticks] order ticks filled by trader when created
resd: [lots] residues of order lots, if resd != 0 and state TRADE means particularly_filled
exec: [lots] execution of order lots, if exec == lots and state TRADE means full_filled
cost: [integer] cost = Σ(lastLots * lastTicks)
lastLots [lots] last taken lots
lastTicks [ticks] last taken ticks
created [time] timestamp of created in milliseconds
modified [time] timestamp of modified(taken/cancel) in milliseconds

Due to I/O limits of network, system returns max 100 orders at once, all orders paged by each 100 orders.
You can set field page number if your active orders are over 100.

Query History Order

This API provides HISTORY(CANCEL/full_filled) order query ONLY.
If active order, please use Order/Status, otherwise order not found(404).

/api/trader/v1/order/history

List your history orders of a market.

Field Type Description
market [string] mnem of market
pageIndex [integer] page index
pageSize [integer] total pages
curl --location --request POST "/api/trader/v1/order/history" \
--header "apikey: apikey" \
--header "signature: signature" \
--header "nonce: xxxxxx" \
--header "Content-Type: application/json" \
--data "{
\"market\": \"BTCETP\",
\"pageIndex\": 0,
\"pageSize\": 20
}"

/api/trader/v1/order/

Get a history order by market and id.

Field Type Description
market [string] mnem of market
id [integer] id of order
curl --location --request POST "/api/trader/v1/order/" \
--header "apikey: apikey" \
--header "signature: signature" \
--header "nonce: nonce" \
--header "Content-Type: application/json" \
--data "{
\"market\": \"BTCETP\",
\"id\": 111111
}"

Query History Trade

History/Trade

Only provides query method by order, not listing.

/v1/history/trade

to be written…