API docs by Redocly

bitcastle API docs (1.0.0)

Download OpenAPI specification:Download

E-mail: support@bitcastle.io Terms of Service

API Key Setup

All the endpoints will require an API Key. Please refer to this page regarding API key creation..

Once an API key is created, it is recommended to set IP restrictions on the key for security reasons.

Never share your API key/secret key to ANYONE.

If the API keys were accidentally shared, please delete them immediately and create a new key.

To manage your API keys, please go to the API Key Management page.

API Key Restrictions.

We support different options for API Key calling requests to Bitcastle:

Read Only: Request for login authentication and be able to use all the API to read info (Ex: user profile info, user’s balance info, trading history, deposit/ withdrawal history, etc.)

Spot Trading: Request to create or cancel an exchange order

Withdraw: Request to create a withdraw order

After creating the API key, the default restriction is Enable. If we see any suspicious attempts that may not be safe for our system, it would be Disabled and no longer be used.

The default rate for an API Key is:

50 calls per 10 seconds for user account.

100 calls per 10 seconds for enterprise account.

Websocket

We are support both MQTT and Websocket protocol for real time data. Data format must using MQTT package structure.

Base url:

  • Websocket: wss://socket.bitcastle.io/mqtt
  • MQTT: mqtt.bitcastle.io

Get Realtime Price Changes for All Markets:

  • Topic: public/exchange/update_ticker_24h
{
  "data": [
    {
      "coin": "ada",
      "currency": "usdt",
      "volume": "3536679.8",
      "total": "1321685.59747",
      "high": "0.38",
      "low": "0.3658",
      "price": "0.3684",
      "price_change": "-0.0096",
      "price_percentage": "-2.539682539682539683"
    }
  ],
  "last_update": "1684469752863"
}

Get Realtime Market Trades for Pair:

  • Topic: public/exchange/update_market_trade/{coin}/{currency}
  • Example: public/exchange/update_market_trade/btc/usdt
{
  "data": {
    "id": "68367233",
    "origin_order_id": "711794895602066054",
    "match_order_id": "711794895606258816",
    "coin": "btc",
    "currency": "usdt",
    "price": "26824.8",
    "net_volume": "0.00326556",
    "gross_volume": "0.00326556",
    "create_time": "1684469927659",
  },
  "last_update": "1684469927705"
}

Get Realtime Orderbook for Pair:

  • Topic: public/exchange/update_orderbook/{coin}/{currency}/{precision}
  • Example: public/exchange/update_orderbook/btc/usdt/0.01
    {
  "data": {
"coin": "btc",
"currency": "usdt",
"precision": "0.01",
"type": "ws",
"orderbook": {
  "asks": [
    {
      "price": "26851.57",
      "volume": "0.00356067"
    },
    {
      "price": "26851.49",
      "volume": "0.00423304"
    },
    {
      "price": "26851.47",
      "volume": "0.01969202"
    }
  ],
  "bids": [
    {
      "price": "26797.22",
      "volume": "0.00285109"
    },
    {
      "price": "26797.19",
      "volume": "0.00570166"
    },
    {
      "price": "26797.18",
      "volume": "0.00096345"
    }
  ]
}
  },
  "last_update": 1684469761904
}

Balance

API that get user Balances

Get user balances

Authorizations:
ApiKeyAuth
query Parameters
types[]
Array of any
Default: [3]
Example: types[]=1&types[]=2

Balance Types ([CASHBACK,BO,EXCHANGE,REWARD,1,2,3,4])

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "timestamp": 1683627338413
}

Markets

API that related to market data

Get Pairs

Market related statistics for all markets for the last 24 hours.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get 24h tickers

Market related statistics for all markets for the last 24 hours.

query Parameters
coin
string
Example: coin=btc
currency
string
Example: currency=usdt

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "last_update": 1683627338413
}

Get orderbook

Order book depth of any given trading pair, split into two different arrays for bid and ask orders.

query Parameters
coin
required
string
Example: coin=btc
currency
required
string
Example: currency=usdt
precision
required
string
Example: precision=0.01
take
number
Example: take=100

number of elements in each array, default = 100

sort
string
Enum: "ASC" "DESC"

order by: price, default = DESC

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "last_update": 1684470804010
}

Get historical trades

Used to return data on historical completed trades for a given market pair.

path Parameters
coin
required
string
Example: BTC
currency
required
string
Example: USDT

Responses

Response samples

Content type
application/json
{
  • "buy": [
    ],
  • "sell": [
    ]
}

Get market trades

Historical trade data for any given trading pair.

query Parameters
coin
required
string
Example: coin=btc
currency
required
string
Example: currency=usdt
take
number
Example: take=50

Default is 50

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get price chart candlestick

The request will respond candle stick data buy trading pair

query Parameters
coin
required
string
Example: coin=btc
currency
required
string
Example: currency=usdt
range
required
string
Example: range=24h

Write List: 24h,7d,30d

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "last_update": "1684471309175"
}

Spot Trading

API that use by user to create or cancel an exchange order

List open orders

The List Open Orders API allows you to retrieve a list of open or pending orders.

Define ENUM

  • status: PENDING = 1, FILLED = 2, CANCELED = 3, EXPIRED = 4, CANCELING = 6
  • stop_direction: UNDEFINED = 0, UP = 1, DOWN = 2
Authorizations:
ApiKeyAuth
query Parameters
order_class
number
Enum: 1 2 3 4
Example: order_class=2

MARKET = 1, LIMIT = 2, STOP_MARKET = 3, STOP_LIMIT = 4

order_type
number
Enum: 1 2
Example: order_type=2

BUY = 1, SELL = 2

currency
string
Example: currency=usdt
coin
string
Example: coin=btc
from_create_date
string
Example: from_create_date=1672053435907
to_create_date
string
Example: to_create_date=1672053435907
take
number
Default: 10
Example: take=10

Default is 10. For pagination

from
string

order_id of order

to
string

order_id of order

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "status_code": 200,
  • "msg": "Success",
  • "timestamp": "123124123123"
}

List order history

The List Order History API provides a convenient way to retrieve a user's order history

Define ENUM

  • stop_direction: UNDEFINED = 0, UP = 1, DOWN = 2
Authorizations:
ApiKeyAuth
query Parameters
order_class
number
Enum: 1 2 3 4
Example: order_class=2

MARKET = 1, LIMIT = 2, STOP_MARKET = 3, STOP_LIMIT = 4

order_type
number
Enum: 1 2
Example: order_type=2

BUY = 1, SELL = 2

currency
string
Example: currency=usdt
coin
string
Example: coin=btc
from_create_date
string
Example: from_create_date=1672053435907
to_create_date
string
Example: to_create_date=1672053435907
order_status
number
Enum: 1 2 3 4 6
Example: order_status=2

PENDING = 1, FILLED = 2, CANCELED = 3, EXPIRED = 4, CANCELING = 6

take
number
Default: 10
Example: take=10

Default is 10. For pagination

from
string

id of order

to
string

id of order

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "status_code": 200,
  • "msg": "Success",
  • "timestamp": "123124123123"
}

List trade history

The List Trade History API provides a convenient way to retrieve the trade history.

Authorizations:
ApiKeyAuth
query Parameters
order_class
number
Enum: 1 2 3 4
Example: order_class=2

MARKET = 1, LIMIT = 2, STOP_MARKET = 3, STOP_LIMIT = 4

order_type
number
Enum: 1 2
Example: order_type=2

BUY = 1, SELL = 2

currency
string
Example: currency=usdt
coin
string
Example: coin=btc
from_create_date
string
Example: from_create_date=1672053435907
to_create_date
string
Example: to_create_date=1672053435907
take
number
Default: 10
Example: take=10

Default is 10. For pagination

from
string

id of trade-history

to
string

id of trade-history

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "status_code": 200,
  • "msg": "Success",
  • "timestamp": "123124123123"
}

Open order

Open new Order

Define ENUM

  • order_class: MARKET = 1, LIMIT = 2, STOP_MARKET = 3, STOP_LIMIT = 4
  • order_type: BUY = 1, SELL = 2
Authorizations:
ApiKeyAuth
Request Body schema: application/json
order_type
required
number
order_class
required
number
coin
required
string
currency
required
string
price
required
string
stop_price
required
string
volume
required
string

Responses

Request samples

Content type
application/json
{
  • "order_type": 1,
  • "order_class": 1,
  • "coin": "btc",
  • "currency": "usdt",
  • "price": "0.1",
  • "stop_price": "0.1",
  • "volume": "0.1"
}

Response samples

Content type
application/json
{
  • "order_type": 0,
  • "order_class": 0,
  • "coin": "btc",
  • "currency": "usdt",
  • "price": "0.1234211",
  • "stop_price": "0.1234211",
  • "volume": "0.1234211"
}

Get order by id

Get user's order by order_id.

Authorizations:
ApiKeyAuth
query Parameters
order_id
required
number
Example: order_id=687611739734551300

Id of the order

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "status_code": 200,
  • "msg": "Success",
  • "timestamp": "123124123123"
}

Cancel orders by ids

The Cancel Open Order API allows you to cancel an open or pending orders by list of IDs

Authorizations:
ApiKeyAuth
Request Body schema: application/json
ids
Array of strings non-empty

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": { },
  • "status_code": 200,
  • "msg": "Success",
  • "timestamp": "123124123123"
}

Futures

Get futures open orders

Get futures open orders of user.

Authorizations:
ApiKeyAuth
query Parameters
limit
number
Example: limit=10

Default is 10. Min is 1. Max is 1000 . For pagination

page
number
Example: page=1

Default is 1. For pagination

Responses

Response samples

Content type
application/json
{
  • "timestamp": "1716778236408",
  • "data": [
    ],
  • "status_code": 200,
  • "pagination": {
    },
  • "links": {
    }
}

Get futures order histories

Get futures order histories of user.

Authorizations:
ApiKeyAuth
query Parameters
coin
string
Example: coin=btc

coin

currency
string
Example: currency=usdt

currency

side
number
Enum: 1 2
Example: side=1

BUY: 1, SELL: 2

status
number
Enum: 3 4
Example: status=3

CANCEL: 3, FILLED: 4

type
number
Enum: 1 2
Example: type=1

MARKET: 1, LIMIT: 2

position_id
string
Example: position_id=123124123123

Position ID

start_time
string
Example: start_time=1672053435907

Start time in ms

end_time
string
Example: end_time=1672053435907

End time in ms

limit
string
Example: limit=10

Default is 10. Min is 1. Max is 1000 . For pagination

page
string
Example: page=1

Default is 1. For pagination

order_by
string
Enum: "asc" "desc"
Example: order_by=desc

Ascending: asc, Descending: desc

Responses

Response samples

Content type
application/json
{
  • "timestamp": "1712564120647",
  • "data": [
    ],
  • "status_code": 200,
  • "pagination": {
    },
  • "links": {
    }
}

Open futures order

Open new futures order

Authorizations:
ApiKeyAuth
Request Body schema: application/json
mode
required
number
Enum: 1 2

ISOLATED: 1, CROSS: 2

side
required
number
Enum: 1 2

BUY: 1, SELL: 2

coin
required
string

coin

currency
required
string

coin

price
required
string

Price of the order

type
required
number
Enum: 1 2

MARKET: 1, LIMIT: 2

amount
required
string

Amount of the order

collateral
required
number
Enum: 1 2

USD-M: 1, COIN-M: 2

stop_loss_price
string

Price to stop loss

take_profit_price
string

Price to take profit

Responses

Request samples

Content type
application/json
{
  • "mode": 1,
  • "side": 1,
  • "coin": "btc",
  • "currency": "usdt",
  • "price": "19000",
  • "type": 1,
  • "amount": "0.1",
  • "collateral": 1,
  • "stop_loss_price": "18000",
  • "take_profit_price": "20000"
}

Response samples

Content type
application/json
{
  • "timestamp": "1712566153345",
  • "msg": "Order created",
  • "data": {
    },
  • "status_code": 200
}

Cancel futures order

Cancel futures order

Authorizations:
ApiKeyAuth
Request Body schema: application/json
id
required
string

ID of order to cancel

Responses

Request samples

Content type
application/json
{
  • "id": "1684470600000"
}

Response samples

Content type
application/json
{
  • "timestamp": "1712568171728",
  • "msg": "",
  • "status_code": 200
}

Get futures positions

Get futures positions of user.

Authorizations:
ApiKeyAuth
query Parameters
coin
string
Example: coin=btc

coin

currency
string
Example: currency=usdt

currency

side
string
Enum: "long" "short"
Example: side=long

LONG: long, SHORT: short

status
string
Enum: "open" "close"
Example: status=open

OPEN: open, CLOSE: close

sort_by
string
Enum: "id" "updated_at"
Example: sort_by=id

Sort by ID: id, sort by updated at: updated_at

start_time
string
Example: start_time=1672053435907

Start time in ms

end_time
string
Example: end_time=1672053435907

End time in ms

limit
string
Example: limit=10

Default is 10. For pagination

page
string
Example: page=1

Default is 1. For pagination

order_by
string
Enum: "asc" "desc"
Example: order_by=desc

Ascending: asc, Descending: desc

Responses

Response samples

Content type
application/json
{
  • "timestamp": "1712564117654",
  • "data": [
    ],
  • "status_code": 200,
  • "pagination": {
    },
  • "links": {
    }
}

Close futures position

Close futures position by id

Authorizations:
ApiKeyAuth
Request Body schema: application/json
position_id
required
string

ID of position to close

type
required
string
Enum: "market" "limit"

Market: market, Limit: limit

exit_price
string

exit price

Responses

Request samples

Content type
application/json
{
  • "position_id": "1684470600000",
  • "type": "market",
  • "exit_price": "19000"
}

Response samples

Content type
application/json
{
  • "timestamp": "1712568517328",
  • "msg": "",
  • "data": { },
  • "status_code": 200
}

Adjust margin position

Adjust margin for futures position

Authorizations:
ApiKeyAuth
Request Body schema: application/json
id
required
string

ID of position to adjust

action
required
string
Enum: "increase" "decrease"

Increase: increase, Decrease: decrease

currency
required
string

Currency to adjust

amount
required
string

Amount to adjust

Responses

Request samples

Content type
application/json
{
  • "id": "1684470600000",
  • "action": "increase",
  • "currency": "usdt",
  • "amount": "100"
}

Response samples

Content type
application/json
{
  • "timestamp": "1712569459026",
  • "msg": "",
  • "data": {
    },
  • "status_code": 200
}

Take profit stop loss position

Modify take profit and stop loss for futures position

Authorizations:
ApiKeyAuth
Request Body schema: application/json
position_id
required
string

ID of position to update take profit stop loss

take_profit_price
required
string

Price to take profit

stop_loss_price
required
string

Price to stop loss

Responses

Request samples

Content type
application/json
{
  • "position_id": "1684470600000",
  • "take_profit_price": "21000",
  • "stop_loss_price": "19000"
}

Response samples

Content type
application/json
{
  • "timestamp": "1712569723788",
  • "msg": "",
  • "data": { },
  • "status_code": 200
}

Get leverage user setting

Get leverage user setting use for place futures order.

Authorizations:
ApiKeyAuth
query Parameters
symbol
required
string
Example: symbol=btc/usdt

symbol

Responses

Response samples

Content type
application/json
{
  • "timestamp": "1716879322196",
  • "msg": "Get leverage info success!",
  • "data": [
    ],
  • "status_code": 200
}

Get margin mode user setting

Get margin mode user setting use for place futures order.

Authorizations:
ApiKeyAuth
query Parameters
symbol
required
string
Example: symbol=btc/usdt

symbol

Responses

Response samples

Content type
application/json
{
  • "timestamp": "1716879322199",
  • "msg": "Get margin mode info success!",
  • "data": {
    },
  • "status_code": 200
}

Get position mode user setting

Get position mode user setting use for place futures order.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "timestamp": "1716879322030",
  • "msg": "Get position mode success!",
  • "data": {
    },
  • "status_code": 200
}

Update leverage

Update leverage use for place futures order

Authorizations:
ApiKeyAuth
Request Body schema: application/json
leverage
required
string

Leverage use for place futures order

side
required
string
Enum: "long" "short" "dual"

LONG: long, SHORT: short, DUAL: dual

symbol
required
string

Symbol

Responses

Request samples

Content type
application/json
{
  • "leverage": "125",
  • "side": "long",
  • "symbol": "btc/usdt"
}

Response samples

Content type
application/json
{
  • "timestamp": "1716777514301",
  • "msg": "Update leverage info success!",
  • "data": {
    },
  • "status_code": 200
}

Update position mode

Update position mode use for place futures order

Authorizations:
ApiKeyAuth
Request Body schema: application/json
use_hedge_mode
required
boolean

Use hedge mode

Responses

Request samples

Content type
application/json
{
  • "use_hedge_mode": true
}

Response samples

Content type
application/json
{
  • "timestamp": "1716777571615",
  • "msg": "Change position mode success!",
  • "data": {
    },
  • "status_code": 200
}

Update margin mode

Update margin mode use for place futures order

Authorizations:
ApiKeyAuth
Request Body schema: application/json
mode
string
Enum: "cross" "isolated"

Cross: cross, Isolated: isolated

symbol
required
string

Symbol

Responses

Request samples

Content type
application/json
{
  • "mode": "cross",
  • "symbol": "btc/usdt"
}

Response samples

Content type
application/json
{
  • "timestamp": "1716879119196",
  • "msg": "Update margin mode info success!",
  • "data": {
    },
  • "status_code": 200
}

Cancel trigger price

Cancel trigger price

Authorizations:
ApiKeyAuth
Request Body schema: application/json
position_id
required
string

ID of position to cancel trigger price

type
required
string
Enum: "take_profit_price" "stop_loss_price" "close_limit_price"

Take profit price: take_profit_price, Stop loss price: stop_loss_price, Close limit: close_limit_price

Responses

Request samples

Content type
application/json
{
  • "position_id": "1684470600000",
  • "type": "take_profit_price"
}

Response samples

Content type
application/json
{
  • "timestamp": "1716892283873",
  • "msg": "",
  • "data": { },
  • "status_code": 200
}