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…