Public API

time

Retrieves the current time (in ms). This API endpoint can be used to check the clock skew between your software and Deribit's systems.

HTTP usage: GET /api/v1/public/time

Websocket usage: {"action": "/api/v1/public/time"}

Example

// HTTP:
//   GET /api/v1/public/time
// Websocket:
//   {"action": "/api/v1/public/time"}

{
    "result":1528814188150
}

setheartbeat

Signals the Websocket connection to send and request heartbeats. Heartbeats can be used to detect stale connections. This API endpoint cannot be used over HTTP.

When heart beats have been set up, the API server will send heartbeat messages and test_request messages. Your software should respond test_request messages by sending a /api/v1/public/test request. If your software fails to do so, the API server will close the request. If your account is configured to cancel on disconnect, any orders opened over the connection will be cancelled.

Websocket usage: {"action": "/api/v1/public/setheartbeat", "arguments": {...}}

Arguments

name type default description
interval float 60 The heartbeat interval

Response

This endpoint returns an empty message (i.e. without result field).

Example

// Websocket:
//   {"action": "/api/v1/public/setheartbeat",
//    "arguments": {"interval": 60}}

{
    ...
}

cancelheartbeat

Signals the Websocket connection to not send or request heartbeats. This API endpoint cannot be used over HTTP.

When heart beats have been set up, the API server will send heartbeat messages and test_request messages. Your software should respond test_request messages by sending a /api/v1/public/test request. If your software fails to do so, the API server will close the request. If your account is configured to cancel on disconnect, any orders opened over the connection will be cancelled.

This API endpoint does not take any arguments.

Websocket usage: {"action": "/api/v1/public/cancelheartbeat"}

Response

This endpoint returns an empty message (i.e. without result field).

Example

// Websocket:
//   {"action": "/api/v1/public/cancelheartbeat"}

{
    ...
}

test

Tests the connection to the API server, and returns its version. You can use this to make sure the API is reachable, and matches the expected version.

Arguments

name type default description
exception any Provide this parameter force an error message. This may be useful for testing wrapper libraries.

Response

Contrary to other API endpoints, there is no result field. There is, however an apiBuild field present at the root level.

HTTP usage: GET /api/v1/public/test

Websocket usage: {"action": "/api/v1/public/test"}

Example

// HTTP:
//   GET /api/v1/public/test?expired=false
// Websocket:
//   {"action": "/api/v1/public/test",
//    "arguments": {"expired": false}}

{
    "message":"public API test",
    "apiBuild":"1.2.26",
    ...
}

ping

This API endpoint always responds with "pong". This method is primarily intended to be used as a keep alive message over websocket. When used over HTTP this API endpoint could also be used to measure network delays between your software and the API server.

This request does not take any arguments.

HTTP usage: GET /api/v1/public/ping

Websocket usage: {"action": "/api/v1/public/ping"}

Response

This API endpoint returns the current time in ms since Jan 1^st 1970.

Example

// HTTP:
//   GET /api/v1/public/ping
// Websocket:
//   {"action": "/api/v1/public/ping"}

{
    "result": "pong",
    ...
}

getinstruments

Retrieves available trading instruments. This API endpoint can be used to see which instruments are available for trading, or which instrument have existed historically.

HTTP usage: GET /api/v1/public/getinstruments

Websocket usage: {"action": "/api/v1/public/getinstruments", "arguments": {...}}

Arguments

name type default description
expired boolean false Set to true to show expired instruments instead of active ones. This can be useful for retrieving historic data.

Response

This API endpoint returns a list of instruments in the result field. An instrument consists of the following fields:

name type example description
kind string "option" The type of instrument. Possible values include 'option' and 'future'
baseCurrency string "BTC" The base currency - the underlying currency being traded.
currency string "USD" The currency in which the instrument prices are quoted
minTradeSize float 0.1 Minimum size for trading
instrumentName string "BTC-23FEB18-9000-C" The name of the instrument. This name is used as an identifier for the security elsewhere in the API
isActive boolean true Indicates if the instrument can currently be traded.
settlement string "month" The settlement interval. Possible values include 'month' and 'week'
created string "2018-01-23 12:07:00 GMT" GMT date time when the instrument was first created
tickSize float 0.0001 specifies minimal price change and, as follows, the number of decimal places for instrument prices
pricePrecision string 4 Specifies the number of decimal places for instrument prices [deprecated]
expiration string "2018-02-23 08:00:00 GMT" GMT date time at which the instrument will expire
strike float 9000 The strike value. (only for options)
optionType string "call" The option type, possible values are 'call' or 'put'. (only for options)
currency string "BTC" Currency filter for the instruments, possible values 'BTC', 'ETH'. If not defined - no filtering, all instruments.
contractSize number "10" Contract size in USD (only for futures and perpetual), currently $10 for BTC futures and $1 for ETH futures

Example

// HTTP:
//   GET /api/v1/public/getinstruments?expired=false
// Websocket:
//   {"action": "/api/v1/public/getinstruments",
//    "arguments": {"expired": false}}

{
    "result": [
        {
            "kind":"future",
            "baseCurrency":"BTC",
            "currency":"USD",
            "minTradeSize":1,
            "instrumentName":"BTC-28SEP18",
            "isActive":true,
            "settlement":"month",
            "created":"2018-04-12 19:34:07 GMT",
            "tickSize":0.5,
            "pricePrecision":1,
            "expiration":"2018-09-28 08:00:00 GMT",
            "contractSize":10
        },
        ...
    ],
    ...
}

getcurrencies

Retrieves all cryptocurrencies supported by the API. This API endpoint does not take any arguments

HTTP usage: GET /api/v1/public/getcurrencies

Websocket usage: {"action": "/api/v1/public/getcurrencies"}

Response

This API endpoint returns a list of currencies in the result field. A currency consists of the following fields:

name type example description
currency string "BTC" The abbreviation of the currency. This abbreviation is used elsewhere in the API to identify the currency.
currencyLong string "Bitcoin" The full name for the currency.
minConfirmation int 2 Minimum number of block chain confirmation before deposit is accepted.
txFee float 0.0006 The min transaction fee paid for withdrawals.
isActive bool true Whether this currency is currently in use.
coinType string "BITCOIN" The type of the currency, currently only "BITCOIN"
baseAddress string null Not used
txFee float 0.0001 Minimal transaction fee

Example

// HTTP:
//   GET /api/v1/public/getcurrencies?expired=false
// Websocket:
//   {"action": "/api/v1/public/getcurrencies"}

{
    "result": [
        {
            "txFee"
            "currency": "BTC",
            "currencyLong": "Bitcoin",
            "minConfirmation": 2,
            "txFee": 0.0006,
            "isActive": true,
            "coinType": "BITCOIN",
            "baseAddress": null
        }
    ],
    ...
}

index

Retrieves the current index price for the BTC-USD instruments. This API endpoint does not take any arguments

HTTP usage: GET /api/v1/public/index

Websocket usage: {"action": "/api/v1/public/index", "arguments": {...}}

Arguments

name type example description
currency string "BTC" Currency of the index. Possible values 'BTC', 'ETH'. Default is 'BTC'.

Response

This API endpoint returns two prices in the result field.

name type example description
btc float 11628.81 The current index price for BTC-USD. It is present if currency = `BTC'.
eth float 165.15 The current index price for ETH-USD. It is present if currency = 'ETH'.
edp float 11628.81 Estimated delivery price for the passed currency. For more details, see Documentation > General > Expiration Price

Example

// HTTP:
//   GET /api/v1/public/index
// Websocket:
//   {"action": "/api/v1/public/index"}

{
    "result": [{
        "btc": 11628.81,
        "edp": 11628.81
    }],
}

getorderbook

HTTP usage: GET /api/v1/public/getorderbook

Websocket usage: {"action": "/api/v1/public/getorderbook", "arguments": {...}}

Retrieves the order book, along with other market values for a given instrument.

Arguments

Parameter type default description
instrument string REQUIRED. The instrument name for which to retrieve the order book, see getinstruments to obtain instrument names.
depth integer The number of entries to return for bids and asks.

Response

The response contains the requested values in the result field.

name type example description
instrument string "BTC-23FEB18" REQUIRED, The name of the instrument.
bids list (see below) The list of all bids, best bid first. See below for entry details
asks list (see below) The list of all asks, best ask first. See below for entry details
tstamp int 1517329113791 The order book timestamp in milliseconds
last float 10350 The price for the last trade
low float 10296.11 The 24h low for the instrument
high float 10916.03 The 24h high for the instrument
mark float 10334.06 The mark price for the instrument
state string "open" The state of the order book. Possible values are "open" and "closed".
settlementPrice float 11013.37 The settlement price for this instrument. Only when state=open
deliveryPrice float 11013.37 The settlement price for this instrument. Only when state=closed
uPx float 10408.16 (Only for option) underlying price used for ask/bid implied volatility
uIx string "BTC-30MAR18" (Only for option) underlying future instrument name or "index_price"
iR float 0 (Only for option) Interest rate used for implied volatility calculations
markIv float 135 (Only for option) implied volatility for mark price
askIv float 130.06 (Only for option) implied volatility for best ask
bidIv float 109.99 (Only for option) implied volatility for best bid
delta float -.35199 (Only for options) The delta value for the option
gamma float 0.00011 (Only for options) The gamma value for the option
vega float 11.98132 (Only for option) The vega value for the option
theta float -6.7319 (Only for option) The theta value for the option
max float (Only for futures) The maximum price for the future. Any buy orders you submit higher than this price, will be clamped to this maximum.
min float (Only for futures) The minimum price for the future. Any sell orders you submit lower than this price will be clamped to this minimum.
contractMultiplier number 10 (Only for futures) Price in USD per 1 contract

The fields bids and asks are lists of order book price level entries, sorted from best to worst.

name type example description
quantity number 800 The total quantity of orders for this price level
amount number 8000 The amount as quantity in contract currency units
price float 10322.5 The price level
cm number 800 The cumulative quantity
cm_amount number 8000 The cumulative amount in contract currency units
oid string (Only for options)The order id of an unfilled order you have at this price. This field only shows if you have an order at this price level, and the request has been signed.

Example

// HTTP:
//   GET /api/v1/public/getorderbook?instrument=BTC-23FEB18
// Websocket:
//   {"action": "/api/v1/public/getorderbook",
//    "arguments": {"instrument": "BTC-23FEB18"}}

{
    "result": {
        "state": "open",
        "settlementPrice": 11013.37,
        "instrument": "BTC-23FEB18",
        "bids": [
            {
                "quantity": 800,
                "price": 10322.56,
                "cm": 800
            },
           ...
        ],
        "asks": [
            {
                "quantity": 510,
                "price": 10334.06,
                "cm": 510
            },
            ...
        ],
        "tstamp": 1517329113791,
        "last": 10350,
        "low": 10296.11,
        "high": 10916.03,
        "mark": 10334.06,
        "uPx": 10408.16,
        "uIx": "BTC-30MAR18",
        "iR": 0,
        "markIv": 135,
        "askIv": 130.06,
        "bidIv": 109.99
        "contractMultiplier":10
    },
}

getlasttrades

Retrieve the latest trades that have occurred for a specific instrument. Trades are identified in two ways:

  • the trade is (tradeId), which is unique between all instruments, but is not guaranteed to be strictly sequential.
  • the trade sequence (tradeSeq), which starts at 1 for each instruments, and is strictly sequential. Under rare circumstances, it is possible for the trade sequence to skip a few numbers.

HTTP usage: GET /api/v1/public/getlasttrades

Websocket usage: {"action": "/api/v1/public/getlasttrades", "arguments": {...}}

Arguments

Parameter type default description
sort string "desc" DEPRECATED, "asc" for ascending, "desc" for descending
instrument string REQUIRED Either the name of the instrument, or "all" for all active instruments, "futures" for all active futures, or "options" for all active options.
count integer 10 The number of trades returned (clamped to max 1000)
startId integer The ID of the first trade to be returned
endId integer The ID of the last trade to be returned
startSeq integer The trade sequence of the first trade to be returned
endSeq integer The trade sequence of the last trade to be returned
startTimestamp integer The timestamp (in ms) of the first trade to be returned
endTimestamp integer The timestamp (in ms) of the last trade to be returned
since integer DEPRECATED, The ID after which trades are returned, for backward compatibility
direction string DEPRECATED, alias to "sort", for backward compatibility
includeOld bool false to get archived trades for expired instruments when true (added from performance considerations)
currency string "BTC" Currency of the trades. Possible values 'BTC', 'ETH'. Default is 'BTC'.

Response

The response contains the a list of trades in the result field. A trade consists of the following fields:

name type example description
tradeId string 49366 The ID for the trade
instrument string "BTC-25AUG17-3900-C" The name of the instrument
tradeSeq string 1 The trade sequence number
timeStamp string 1503439494351 The timestamp of the trade in ms
quantity number 5 The quantity traded
amount number 5 The amount as quantity in contract currency units (for example USD for futures)
price string 0.055 The price of the trade
direction string "buy" Trade direction of the taker
tickDirection string 1 Direction of the "tick". 0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick
indexPrice string 4101.46 Index price at trade
iv string 70.71 option implied volatility for the price (Options only)

Example:

// HTTP:
//   GET /api/v1/public/getlasttrades?startId=49366&instrument=BTC-25AUG17-3900-C
// Websocket:
//   {"action": "/api/v1/public/getlasttrades",
//    "arguments": {"startId": 49366, "instrument": "BTC-25AUG17-3900-C"}}

{
    "result": [
        {
            "tradeId": 49366,
            "instrument": "BTC-25AUG17-3900-C",
            "tradeSeq": 1,
            "timeStamp": 1503439494351,
            "quantity": 5,
            "amount": 5,
            "price": 0.055,
            "direction": "buy",
            "tickDirection": 1,
            "indexPrice": 4101.46,
            "iv": 70.71
        }
        ...
    ],
    ...
}

getsummary

Retrieves the summary information such as open interest, 24h volume, etc. for a specific instrument.

HTTP usage: GET /api/v1/public/getsummary

Websocket usage: {"action": "/api/v1/public/getsummary", "arguments": {...}}

Arguments

Parameter type default description
instrument string REQUIRED Either the name of the instrument, or "all" for all active instruments, 'futures' for all active futures, or 'options' for all active options.
currency string "BTC" Currency of the summary in case of instrument="all". Possible values 'BTC', 'ETH', 'all' (the last one is the alias for all currencies). Default is 'BTC'.

Response

The result field contains a list of instrument data, if multiple instruments were requested, or a single object when a single instrument was requested.

name type example description
instrumentName string "BTC-27JUL18-5000-C" The instrument name
openInterest float 0.5 The total number of outstanding contracts
high float "" Price of the 24h highest trade
low float "" Price of the 24h lowest trade
volume float "" The total 24h traded volume (in contracts)
volumeBtc float "" Deprecated. The total 24h traded volume (for BTC securities - in BTC, otherwise in base currency)
last float 0.354 The price of the latest trade
bidPrice float 7022.89 The current best bid price
askPrice float 7022.89 The current best ask price
midPrice float 7022.89 The average of the best bid and ask
markPrice float 7022.89 The current instrument mark
uPx float 6745.34 underlying price for implied volatility calculations (options only)
uIx string "index_price" Name of the underlying future, or 'index_price' (options only)
iR float 0 Interest rate used in implied volatility calculations (options only)
created string "2018-06-10 18:46:35 GMT" GMT time at which this summary was created
estDelPrice float 10029.5 Estimated delivery price (futures only)

Example

Retrieving a single instrument summary:

// HTTP:
//   GET /api/v1/public/getsummary?instrument=BTC-23FEB18
// Websocket:
//   {"action": "/api/v1/public/getsummary",
//    "arguments": {"instrument": "BTC-23FEB18"}}

{
    "result": {
        "instrumentName": "BTC-23FEB18",
        "openInterest": 16525,
        "high": 10916.03,
        "low": 10000,
        "volume": 4967,
        "volumeBtc": 4.81149499,
        "last": 10000,
        "bidPrice": 10022.89,
        "askPrice": 10034.39,
        "midPrice": 10028.64,
        "markPrice": 10022.89,
        "estDelPrice": 10023.01,
        "created": "2018-01-30 18:36:34 GMT"
    },
    ...
}

Retrieving a instrument summaries for all futures:

// HTTP:
//   GET /api/v1/public/getsummary?instrument=futures
// Websocket:
//   {"action": "/api/v1/public/getsummary",
//    "arguments": {"instrument": "futures"}}

{
    "result": 
        [
            {
            "instrumentName": "BTC-23FEB18",
            "openInterest": 16525,
            "high": 10916.03,
            "low": 10000,
            "volume": 4967,
            "volumeBtc": 4.81149499,
            "last": 10000,
            "bidPrice": 10022.89,
            "askPrice": 10034.39,
            "midPrice": 10028.64,
            "markPrice": 10022.89,
            "estDelPrice": 10023.01,
            "created": "2018-01-30 18:36:34 GMT"
            }
        ],
    ...
}

stats

Retrieves aggregated 24h trade volumes for different instrument types. This API endpoint does not take any arguments.

HTTP usage: GET /api/v1/public/stats

Websocket usage: {"action": "/api/v1/public/stats"}

Response

The result field contains a created field, which is the GMT date for the statistics, and a field for each currency pair supported by the exchange.

Each currency pair contains the following fields:

name type example description
futuresVolume float 30.5178 Total 24h trade volume for futures. This is expressed in the base currency, e.g. BTC for btc_usd
putsVolume float 60.2 Total 24h trade volume for put options. This is expressed in the base currency, e.g. BTC for btc_usd
callsVolume float 2.1 Total 24h trade volume for call options. This is expressed in the base currency, e.g. BTC for btc_usd

Example

// HTTP:
//   GET /api/v1/public/stats?expired=false
// Websocket:
//   {"action": "/api/v1/public/stats"}

{
    "result": {
        "btc_usd": {
            "futuresVolume": 30.5178,
            "putsVolume": 60.2,
            "callsVolume": 2.1
        },
        "created": "2018-01-30 19:00:30 GMT"
    },
}

getannouncements

Retrieves announcements from last 30 days. This API endpoint does not take any arguments.

HTTP usage: GET /api/v1/public/getannouncements

Websocket usage: {"action": "/api/v1/public/getannouncements"}

Response

The result field contains a list of announcements. Each announcement has the following fields:

name type example description
title string "Example announcement" The title of the announcement
body string "An announcement" The HTML body of the announcement
important bool false Whether the announcement is marked as important
id int 19288317 A unique identifier for the announcement
date int 1527844253000 Timestamp in ms at which the announcement was published

Example

// HTTP:
//   GET /api/v1/public/getannouncements
// Websocket:
//   {"action": "/api/v1/public/getannouncements"}

{
    "result": [
        {
            "title": "DERIBIT TESTNET announcement",
            "important": false,
            "id": 1516016139692,
            "date": 1516016117000,
            "body": "DERIBIT TESTNET announcement"
        }
    ],
}

getlastsettlements

Retrieves settlement, delivery and bankruptcy events that have occurred.

HTTP usage: GET /api/v1/public/getlastsettlements

Websocket usage: {"action": "/api/v1/public/getlastsettlements", "arguments": {...}}

Arguments

name type example description
instrument string "all" The instrument name, or "all" to retrieve settlements for all instruments
count integer 10 The number of entries to be returned. This is clamped to max 1000
type integer The type of settlements to return. Possible values "settlement", "delivery", "bankruptcy"
startTstamp integer The latest timestamp to return result for
continuation string Continuation token for pagination. Each response contains a token to be used for continuation
currency string "BTC" Possible values 'BTC', 'ETH'. Default is 'BTC'.

Response

The result field contains two fields: continuation, which is the continuation token for pagination and settlements. Settlements contain the following fields:

name type example description
type string "settlement" The type of settlement
timeStamp string 1517299201923 The timestamp of the settlement
sessionProfitLoss string 4.17243092 Total profit and loss made by all clients.
position string 1000 Total position size (settlement and delivery only)
instrument string "BTC-30MAR18" instrument name (settlement and delivery only)
indexPrice float 11008.37 Underlying index price at time of event (settlement and delivery only)
markPrice float 11000 Mark price for at the time (settlement and delivery only)
profitLoss float 0 profit and loss (settlement and delivery only)
funded string 0 The amount of the bankruptcy losses funded from the insurance fund (bankruptcy only)
socialized float -3e-9 The amount of the bankruptcy losses funded by the clients (bankruptcy only)
sessionBankrupcy float 0.001160788 Total amount of bankruptcies during this particular settlement (bankruptcy only, in BTC)
sessionTaxRate float 0.000103333 Percentage of profits used to socialize losses (bankruptcy only)
sessionTax float -3e-9

Example

// HTTP:
//   GET /api/v1/public/getlastsettlements?instrument=BTC-23MAR18-9500-P
// Websocket:
//   {"action": "/api/v1/public/getlastsettlements",
//    "arguments": {"instrument": BTC-23MAR18-9500-P}}

{
    "result": {
        "settlements": [
            {
                "instrument":"BTC-23MAR18-9500-P"
                "position":26591.7
                "indexPrice":8407.01
                "markPrice":0.130009361
                "profitLoss":-1.973096726
                "type":"delivery"
                "timeStamp":1521792000104
                "sessionProfitLoss":820.137161473},
            {
                "instrument":"BTC-30MAR18"
                "position":151042
                "indexPrice":7530.81
                "markPrice":7498.3
                "profitLoss":-9.060882648999993
                "type":"settlement"
                "timeStamp":1522310400113
                "sessionProfitLoss":40791.1364678138},
            {
                "funded":0.12781214200000002
                "socialized":0.0
                "sessionBankrupcy":1.0232674799999997
                "sessionTaxRate":0.0
                "sessionTax":0.12781214200000002
                "type":"bankruptcy"
                "timeStamp":1522396800132
                "sessionProfitLoss":1923.3313302059998},
            ...
        ],
        "continuation": "xY7T6cut9u3vfTpDNun2T88wzDVfrNdKFeSDVgBGzmKdsMHgNxEwX"
    }
    ...
}

Private API

account

Retrieves user account summary. This API endpoint requires your request to be signed.

HTTP Usage: GET /api/v1/private/account

Websocket usage: {"action": "/api/v1/private/account", "arguments": {...}}

Arguments

name type example description
ext boolean false Requests additional fields
currency string "BTC" Possible values 'BTC', 'ETH'. Default is 'BTC'.

Response

name type example description
currency string BTC The currency of the account returned
equity string 2.6437733 The account's current equity
maintenanceMargin float 0.1334519 The maintenance margin.
initialMargin float 0.379882 The account's initial margin
availableFunds float 2.2638913 The account's available funds
balance float 3.4906363 The account's balance
marginBalance float 3.3 The account's margin balance
depositAddress string "14diAAyXL5UzhPTCKC998ch2GV7DMb7yDi" The deposit address for the account
SUPL float 0.846863 Session unrealized profit and loss
SRPL float 0.1 Session realized profit and loss
PNL float 0.02032221 Profit and loss
optionsPNL float 0 Options profit and Loss
optionsSUPL float 0 Options session unrealized profit and Loss
optionsSRPL float 0 Options session realized profit and Loss
optionsD float 0 Options summary delta
optionsG float 0 Options summary gamma
optionsV float 0 Options summary vega
optionsTh float 0 Options summary theta
futuresPNL float 0 Futures profit and Loss
futuresSUPL float 0 Futures session unrealized profit and Loss
futuresSRPL float 0 Futures session realized profit and Loss
deltaTotal float 0.1334 The sum of position deltas
sessionFunding float 0.0 The session funding value
depositAddress string Last generated deposit address for the currency
nick string "myname" User nickname (only when called with ext=true)
email string "support@deribit.com" User email (only when called with ext=true)
tfa bool false Whether two factor authentication is enabled
type string main main or subaccount
subaccount_name string user1 name of the account or subaccount

Example

// HTTP:
//   GET /api/v1/public/account?ext=true
// Websocket:
//   {"action": "/api/v1/private/account",
//    "arguments": {"ext": true}}

{
    "result": {
        "equity": 4417.99967254,
        "maintenanceMargin": 382.7182731431261,
        "initialMargin": 497.53375508606393,
        "availableFunds": 3920.465917454,
        "balance": 5222.757514792,
        "depositAddress": "14diAAyXL5UzhPTCKC998ch2GV7DMb7yDi",
        "SUPL": 25.62979379,
        "SRPL": -7.12234779,
        "PNL": 7.6426592,
        "optionsPNL": 8.24769235,
        "optionsSUPL": 25.64732556,
        "optionsSRPL": -7.67997179,
        "optionsD": 446.5224,
        "optionsG": -0.2021,
        "optionsV": -31145.8756,
        "optionsTh": 36827.1771,
        "futuresPNL": -0.60503314,
        "futuresSUPL": -0.01753178,
        "futuresSRPL": 0.557624,
        "deltaTotal": 1254.3925,

        "nick": "User1",
        "email": "user1@yahoo.com",
        "tfa": false
    },
    ...
}

buy

Places a buy order for an instrument. This API endpoint requires your request to be signed. When used over HTTP, this API endpoint requires POST.

HTTP Usage: POST /api/v1/private/buy

Websocket usage: {"action": "/api/v1/private/buy", "arguments": {...}}

Arguments

name type default description
instrument string "BTC-23FEB18" Name of the instrument to buy
quantity number The number of contracts to buy
amount number The amount as quantity in contract currency units
type string "limit" The order type, possible types: "limit", "stop_limit", "market", "stop_market"
label string "" user defined label for the order (maximum 32 characters)
price float The order price (Only valid for limit and stop_limit orders)
time_in_force string "good_til_cancelled" Specifies how long the order remains in effect, possible values "good_til_cancelled", "fill_or_kill", "immediate_or_cancel"
max_show number 1 Maximum quantity within an order to be shown to other customers, 0 for invisible order.
max_show_amount number 10 Maximum amount within an order in contract currency units (see amount above) to be shown to other customers, 0 for invisible order.
post_only boolean false If true, the order is considered post-only. If the new price would cause the order to be filled immediately (as taker), the price will be changed to be just below the bid.
reduce_only boolean false If true, the order is considered reduce-only intended to only reduce a position.
stopPx string Stop price required for stop limit orders (Only valid for stop orders)
execInst string Defines trigger type, required for "stop_limit" and "stop_narket" order type, possible values "index_price", "mark_price", "last_price" (Only valid for stop orders)
adv string "" Advanced option order type, can be "implv", "usd". (Only valid for options)

}

  • When submitting an option order with adv=implv, the field price should be a value of implied volatility in percentages. For example, price=100, means implied volatility of 100%.
  • When submitting an option order with adv=usd, the field price should be the option price value in USD.
  • adv=implv and adv=usd cannot be combined with post_only=true.
  • max_show and post_only are only valid in combination with time_in_force=good_til_cancelled

Response

The result field contains two fields: the created order in order and a list of the resulting trades in trades.

Order consists of

name type example description
orderId string 713637304 id of the order
type string "limit" order type, "limit", "market", "stop_limit","stop_market"
instrument string "BTC-23FEB18" instrument name of the order
direction string "buy" direction, "buy" or "sell"
price float 10100.0 price
label string "MyOrder" user defined label (up to 32 characters)
quantity number 1000 The number of contracts to be traded
amount number 10000 The amount as quantity in contract currency units
filledQuantity number 700 The number of contracts already filled
filledAmount number The already filled amount in contract currency units
avgPrice float 10100.0 average fill price of the order
commission float 0 Commission paid so far (in BTC)
created integer 1517614581664 The timestamp (in ms) that the order was created
lastUpdate integer 1517614581664 The timestamp (in ms) that the order was last updated
state string "open" order state
postOnly boolean true true for post-only orders only
reduceOnly boolean true true for reduce-only orders only
api boolean true true - created with API
max_show number 1 Deprecated. Maximum quantity within an order to be shown to other customers, 0 for invisible order.
maxShow number 1 Maximum quantity within an order to be shown to other customers, 0 for invisible order.
maxShowAmount number 10 Maximum amount in contract currency units within an order to be shown to other customers, 0 for invisible order.
adv boolean/string false advanced type (false, or "usd" or "implv")
implv float 250 Option implied volatility in percent. (Only when adv=implv)
usd float 50 Option price in USD (Only if adv=usd)
stopPx float 10000.0 stop price (Only for future stop orders)
execInst string "index_price" Defines trigger type, required for stop limit orders, possible values index_price, mark_price (Only valid for stop orders)
triggered boolean false Whether the stop order has been triggered (Only for future stop orders)

When the order resulted in trades immediately (e.g. market order), there will also be a number of trades:

name type example description
label string "" Order label, if you were participating in this trade.
selfTrade bool false true if the trade is against own order, it can happen only when your account has self-trading enabled. Contact an administrator if you think you need that.
quantity number 1 Trade quantity
amount number 10 Trade amount in contract currency units
price float 8358.12 Price
tradeSeq integer 36223 Trade sequence number for the instrument
matchingId string 723513284 Matching order id

Example

// HTTP:
//   POST /api/v1/private/buy
//   instrument=BTC-23FEB18&type=market&quantity=10
// Websocket:
//   {"action": "/api/v1/private/buy",
//    "arguments": {"instrument": "BTC-23FEB18",
//                  "type": "market",
//                  "quantity": 10}}

{
    "result": {
        "order": {
            "orderId": 713637304,
            "type": "limit",
            "instrument": "BTC-23FEB18",
            "direction": "buy",
            "price": 10100.0,
            "label": "",
            "quantity": 10,
            "filledQuantity": 10,
            "avgPrice": 8913.21,
            "commission": 0.0000280482,
            "created": 1517614581664,
            "lastUpdate": 1517614581664,
            "state": "filled",
            "postOnly": true,
            "api": true,
            "adv": false,
        },
        "trades": [
            {
                "label": "",
                "selfTrade": false,
                "quantity": 10,
                "price": 8913.21,
                "tradeSeq": 36223,
                "matchingId": 723513284
            },
            ...
        ]
    }
}

sell

Places a sell order for an instrument. This API endpoint requires your request to be signed. When used over HTTP, this API endpoint requires POST.

HTTP Usage: POST /api/v1/private/sell

Websocket usage: {"action": "/api/v1/private/sell", "arguments": {...}}

Arguments

name type default description
instrument string "BTC-23FEB18" Name of the instrument to sell
quantity number The number of contracts to sell
amount number The amount as quantity in contract currency units
type string "limit" The order type, possible types: "limit", "stop_limit", "market","stop_market"
label string "" user defined label for the order (maximum 32 characters)
price float The order price (Only valid for limit and stop_limit orders)
time_in_force string "good_til_cancelled" Specifies how long the order remains in effect, possible values "good_til_cancelled", "fill_or_kill", "immediate_or_cancel"
max_show number 1 Deprecated. Maximum quantity within an order to be shown to other customers, 0 for invisible order.
maxShow number 1 Maximum quantity within an order to be shown to other customers, 0 for invisible order.
maxShowAmount number 10 Maximum amount in contract currency units within an order to be shown to other customers, 0 for invisible order.
post_only string true Deprecated. If true, the order is considered post-only. If the new price would cause the order to be filled immediately (as taker), the price will be changed to be just below the bid.
postOnly string true If true, the order is considered post-only. If the new price would cause the order to be filled immediately (as taker), the price will be changed to be just below the bid.
reduce_only boolean true Deprectated. true for reduce-only orders only
reduceOnly boolean true true for reduce-only orders only
stopPx string 1 Stop price required for stop limit orders (Only valid for stop orders)
execInst string "index_price" Defines trigger type, required for "stop_limit" order type, possible values "index_price", "mark_price" (Only valid for stop orders)
adv string "" Advanced option order type, can be "implv", "usd". (Only valid for options)

}

  • When submitting an option order with adv=implv, the field price should be a value of implied volatility in percentages. For example, price=100, means implied volatility of 100%.
  • When submitting an option order with adv=usd, the field price should be the option price value in USD.
  • adv=implv and adv=usd cannot be combined with post_only=true.
  • max_show and post_only are only valid in combination with time_in_force=good_til_cancelled

Response

The result field contains two fields: the created order in order and a list of the resulting trades in trades.

Order consists of

name type example description
orderId string 713637304 id of the order
type string "limit" order type, "limit", "market", "stop_limit", "stop_market"
instrument string "BTC-23FEB18" instrument name of the order
direction string "sell" direction, "buy" or "sell"
price float 10100.0 price
label string "MyOrder" user defined label (up to 32 characters)
quantity number 1000 The number of contracts to be traded
amount number 10000 The amount as quantity in contract currency units
filledQuantity number 700 The number of contracts already filled
filledAmount number The already filled amount in contract currency units
avgPrice float 10100.0 average fill price of the order
commission float 0 Commission paid so far (in BTC)
created integer 1517614581664 The timestamp (in ms) that the order was created
lastUpdate integer 1517614581664 The timestamp (in ms) that the order was last updated
state string "open" order state. Possible values include "rejected", "filled", "cancelled", "open"
postOnly boolean true true for post-only orders only
reduceOnly boolean true true for reduce-only orders only
api boolean true true - created with API
max_show number 1 Deprecated. Maximum quantity within an order to be shown to other customers, 0 for invisible order.
maxShow number 1 Maximum quantity within an order to be shown to other customers, 0 for invisible order.
maxShowAmount number 10 Maximum amount in contract currency units within an order to be shown to other customers, 0 for invisible order.
adv boolean/string false advanced type (absent, or "usd" or "implv")
implv float 250 Option implied volatility in percent. (Only when adv=implv)
usd float 50 Option price in USD (Only if adv=usd)
stopPx float 10000.0 stop price (Only for future stop orders)
execInst string "index_price" Defines trigger type, required for stop limit orders, possible values index_price, mark_price (Only for stop orders)
triggered boolean false Whether the stop order has been triggered (Only for future stop orders)
cost float 0.131

When the order resulted in trades immediately (e.g. market order), there will also be a number of trades:

name type example description
label string "" trade label
selfTrade bool false true if the trade is against own order, it can happen only when your account has self-trading enabled. Contact an administrator if you think you need that.
quantity number 1 Trade quantity
amount number 10 The trade amount in contract currency units
price float 8358.12 Price
tradeSeq integer 36223 Trade sequence number for the instrument
matchingId string 723513284 Matching order id

Example

// HTTP:
//   POST /api/v1/private/sell
//   instrument=BTC-23FEB18&type=market&quantity=10
// Websocket:
//   {"action": "/api/v1/private/sell",
//    "arguments": {"instrument": "BTC-23FEB18",
//                  "type": "market",
//                  "quantity": 10}}

{
    "result": {
        "order": {
            "orderId": 713637304,
            "type": "limit",
            "instrument": "BTC-23FEB18",
            "direction": "sell",
            "price": 10100.0,
            "label": "",
            "quantity": 10,
            "filledQuantity": 10,
            "avgPrice": 8913.21,
            "commission": 0.0000280482,
            "created": 1517614581664,
            "lastUpdate": 1517614581664,
            "state": "filled",
            "postOnly": true,
            "api": true,
            "adv": false,
        },
        "trades": [
            {
                "label": "",
                "selfTrade": false,
                "quantity": 10,
                "price": 8913.21,
                "tradeSeq": 36223,
                "matchingId": 723513284
            },
            ...
        ]
    }
}

edit

Changes price and/or quantity of the own order. This API endpoint requires your request to be signed. When used over HTTP, this API endpoint requires POST.

HTTP Usage: POST /api/v1/private/edit

Websocket usage: {"action": "/api/v1/private/edit", "arguments": {...}}

Arguments

name type example description
orderId string 713637304 REQUIRED, ID of the order to edit
quantity number 1 REQUIRED if no amount. The new order quantity
amount number 10 REQUIRED if no quantity. The amount as quantity in contract currency units
price float 7020.8 REQUIRED, The new order price
post_only boolean true Deprecated. If true, the edited order is considered post-only. If the new price would cause the order to be filled immediately (as taker), the price will be changed to be just below the bid (for buy orders) or just above the ask (for sell orders).
postOnly boolean true If true, the edited order is considered post-only. If the new price would cause the order to be filled immediately (as taker), the price will be changed to be just below the bid (for buy orders) or just above the ask (for sell orders).
reduceOnly boolean true If true, the edited order is considered reduce-only, if false - the reduce-only flag will be removed, if not defined - not change of the flag.
adv string "implv" The new advanced order type (only valid for option orders)
stopPx float 1 The new stop price (only valid for stop limit orders)
  • When editing an option order with adv=implv, the field price should be a value of implied volatility in percentages. For example, price=100, means implied volatility of 100%.
  • When editing an option order with adv=usd, the field price should be the option price value in USD.
  • adv=implv and adv=usd cannot be combined with post_only=true.
  • max_show and post_only are only valid in combination with time_in_force=good_til_cancelled
  • If you have posted an advanced option order, it is necessary to re-supply the adv parameter when editing it.

Response

The result field contains two fields: the created order in order and a list of the resulting trades in trades.

Order consists of

name type example description
orderId integer 713637304 id of the order
type string "limit" order type, "limit", "market", "stop_limit", "stop_market"
instrument string "BTC-23FEB18" instrument name of the order
direction string "buy" direction, "buy" or "sell"
price float 10100.0 price
label string "MyOrder" user defined label (up to 32 characters)
quantity number 1000 The number of contracts to be traded
amount number 10000 The amount as quantity in contract currency units
filledQuantity number 700 The number of contracts already filled
filledAmount number The already filled amount in contract currency units
avgPrice float 10100.0 average fill price of the order
commission float 0 Commission paid so far (in BTC)
created integer 1517614581664 The timestamp (in ms) that the order was created
lastUpdate integer 1517614581664 The timestamp (in ms) that the order was last updated
state string "open" order state
postOnly boolean true true for post-only orders only
reduceOnly boolean true true for reduce-only orders only
api boolean true true - created with API
max_show number 1 Deprecated. Maximum quantity within an order to be shown to other customers, 0 for invisible order.
maxShow number 1 Maximum quantity within an order to be shown to other customers, 0 for invisible order.
maxShowAmount number 10 Maximum amount in contract currency units within an order to be shown to other customers, 0 for invisible order.
adv boolean/string false advanced type (false, or "usd" or "implv")
implv float 250 Option implied volatility in percent. (Only when adv=implv)
usd float 50 Option price in USD (Only if adv=usd)
stopPx float 10000.0 stop price (Only for future stop orders)
execInst string "index_price" Defines trigger type, required for stop limit orders, possible values "index_price", "mark_price" (Only valid for stop orders)
triggered boolean false Whether the stop order has been triggered (Only for future stop orders)

When the edit resulted in trades immediately (e.g. crossed the bid/ask), there will also be a number of trades:

name type example description
label string "" trade label
selfTrade bool false true if the trade is against own order, it can happen only when self-trading allowed.
quantity number 1 Trade quantity
price float 8358.12 Price
tradeSeq integer 36223 Trade sequence number for the instrument
matchingId integer 723513284 Matching order id

Example

// HTTP:
//   POST /api/v1/private/edit
//   orderId=713637304&quantity=1&price=10100
// Websocket:
//   {"action": "/api/v1/private/edit",
//    "arguments": {"orderId": "713637304",
//                  "price": "10100",
//                  "quantity": 1}}

{
    "result": {
        "order": {
            "orderId": 713637304,
            "type": "limit",
            "instrument": "BTC-23FEB18",
            "direction": "sell",
            "price": 10100.0,
            "label": "",
            "quantity": 1,
            "filledQuantity": 10,
            "avgPrice": 8913.21,
            "commission": 0.0000280482,
            "created": 1517614581664,
            "lastUpdate": 1517614581664,
            "state": "filled",
            "postOnly": true,
            "api": true,
            "adv": false,
        },
        "trades": []
    }
    ...
}

cancel

Cancels an order, specified by order id. This API endpoint requires your request to be signed. When used over HTTP, this API endpoint requires POST.

HTTP Usage: POST /api/v1/private/cancel

Websocket usage: {"action": "/api/v1/private/cancel", "arguments": {...}}

Arguments

name type example description
orderId string 713637304 The order id of the order to be cancelled

Response

The result field contains a single order field. This order consists of the following entries:

name type example description
orderId integer 713637304 id of the order
type string "limit" order type, "limit", "market", "stop_limit", "stop_market"
instrument string "BTC-23FEB18" instrument name of the order
direction string "buy" direction, "buy" or "sell"
price float 10100.0 price
label string "MyOrder" user defined label (up to 32 characters)
quantity number 1000 The number of contracts to be traded
amount number 10000 The amount as quantity in contract currency units
filledQuantity number 700 The number of contracts already filled
filledAmount number 7000 The already filled amount in contract currency units
avgPrice float 10100.0 average fill price of the order
commission float 0 Commission paid so far (in BTC)
created integer 1517614581664 The timestamp (in ms) that the order was created
lastUpdate integer 1517614581664 The timestamp (in ms) that the order was last updated
state string "open" order state
postOnly boolean true true for post-only orders only
reduceOnly boolean true true for reduce-only orders only
api boolean true true - created with API
max_show number 1 Maximum quantity within an order to be shown to other customers, 0 for invisible order.
maxShow number 1 Maximum quantity within an order to be shown to other customers, 0 for invisible order.
maxShowAmount number 10 Maximum amount in contract currency units within an order to be shown to other customers, 0 for invisible order.
adv boolean/string false advanced type (false, or "usd" or "implv")
implv float 250 Option implied volatility in percent. (Only when adv=implv)
usd float 50 Option price in USD (Only if adv=usd)
stopPx float 10000.0 stop price (Only for future stop orders)
execInst string "index_price" Defines trigger type, required for stop limit orders, possible values "index_price", "mark_price" (Only valid for stop orders)
triggered boolean false Whether the stop order has been triggered (Only for future stop orders)

Example

// HTTP:
//   POST /api/v1/private/cancel
//   orderId=713637304
// Websocket:
//   {"action": "/api/v1/private/cancel",
//    "arguments": {"orderId": "713637304"}}

{
    "result": {
        "order": {
            "orderId": 713637304,
            "type": "limit",
            "instrument": "BTC-23FEB18",
            "direction": "sell",
            "price": 7000,
            "label": "",
            "quantity": 1,
            "filledQuantity": 0,
            "avgPrice": 0,
            "commission": 0,
            "created": 1517614581664,
            "lastUpdate": 1517614581664,
            "state": "cancelled",
            "postOnly": true,
            "api": true,
            "max_show": 1,
            "adv": false,
        }
    }
}

cancelall

HTTP Usage: POST /api/v1/private/cancelall

Websocket usage: {"action": "/api/v1/private/cancelall", "arguments": {...}}

Cancels all orders, optionally filtered by instrument or instrument type. This API endpoint requires your request to be signed. When used over HTTP, this API endpoint requires POST.

Arguments

name type default description
type string "all" Which type of orders to cancel. Valid values are "all", "futures", "options"
instrument string The name of the instrument for which to cancel all orders
currency string "BTC" Possible values 'BTC', 'ETH', 'all' (the last one is the alias for all currencies). Default is 'BTC'.

Response

The response contains just the common response fields. There is no result field.

Example

// HTTP:
//   POST /api/v1/private/cancelall
//   type=options
// Websocket:
//   {"action": "/api/v1/private/cancelall",
//    "arguments": {"type": "options"}}

{
    ...
}

getopenorders

Retrieves open orders. This API endpoint requires your request to be signed.

HTTP Usage: GET /api/v1/private/getopenorders

Websocket usage: {"action": "/api/v1/private/getopenorders", "arguments": {...}}

Arguments

name type default description
instrument string Instrument to return open orders for
orderId integer order ID
type string Order types to return. Valid values include "limit", "stop_limit", "any"
currency string "BTC" Possible values 'BTC', 'ETH', 'all' (the last one is the alias for all currencies). Default is 'BTC'.

Response

The result field contains a a list of orders. These orders consists of the following fields:

name type example description
orderId integer 713637304 id of the order
type string "limit" order type, "limit","market", "stop_limit", "stop_market"
instrument string "BTC-23FEB18" instrument name of the order
direction string "buy" direction, "buy" or "sell"
price float 10100.0 price
label string "MyOrder" user defined label (up to 32 characters)
quantity number 1000 The number of contracts to be traded
amount number 10000 The amount as quantity in contract currency units
filledQuantity number 700 The number of contracts already filled
filledAmount number 7000 The already filled amount in contract currency units
avgPrice float 10100.0 average fill price of the order
commission float 0 Commission paid so far (in BTC)
created integer 1517614581664 The timestamp (in ms) that the order was created
lastUpdate integer 1517614581664 The timestamp (in ms) that the order was last updated
state string "open" order state
postOnly boolean true true for post-only orders only
reduceOnly boolean true true for reduce-only orders only
api boolean true true - created with API
max_show number 1 Deprecated. Maximum quantity within an order to be shown to other customers, 0 for invisible order.
maxShow number 1 Maximum quantity within an order to be shown to other customers, 0 for invisible order.
maxShowAmount number 10 Maximum amount in contract currency units within an order to be shown to other customers, 0 for invisible order.
adv boolean/string false advanced type (false, or usd or implv)
implv float 250 Option implied volatility in percent. (Only when adv=implv)
usd float 50 Option price in USD (Only if adv=usd)
stopPx float 10000.0 stop price (Only for future stop orders)
execInst string "index_price" Defines trigger type, required for stop limit orders, possible values "index_price", "mark_price" (Only valid for stop orders)
triggered boolean false Whether the stop order has been triggered (Only for future stop orders)

Example

// HTTP:
//   GET /api/v1/private/getopenorders?orderId=713637304
// Websocket:
//   {"action": "/api/v1/private/getopenorders",
//    "arguments": {"orderId": 713637304}}

{
    "result": [
        {
            "orderId": 713637304,
            "type": "limit",
            "instrument": "BTC-23FEB18",
            "direction": "sell",
            "price": 10000,
            "label": "1",
            "quantity": 1,
            "filledQuantity": 0,
            "avgPrice": 0,
            "commission": 0,
            "created": 1517614581664,
            "lastUpdate": 1517614581664,
            "state": "open",
            "postOnly": true,
            "api": true,
            "max_show": 1,
            "adv": false,
        }
    ]
}

positions

Retrieves current positions. This API endpoint requires your request to be signed. This API endpoint does not take any arguments

HTTP Usage: GET /api/v1/private/positions

Websocket usage: {"action": "/api/v1/private/positions"}

Arguments

name type default description
currency string "BTC" Possible values 'BTC', 'ETH', 'all' (the last one is the alias for all currencies). Default is 'all'.

Response

name type example description
instrument "BTC-30MAR18" name of the instrument
kind string "future" The type of instrument. "future" or "option"
size integer 5893 The position size in contracts. Can be negative (short) or positive (long)
amount float 58930 Position size-amount in contract currency units. Can be negative (short) or positive (long)
averagePrice float 9693.502194671 average price for the position
direction string "buy" The direction of the position. Can be "buy" (long) or "sell" (short)
size float 1000 Position size in contract units
sizeBtc float 7.14775214 Position size in BTC (for BTC base currency only)
sizeEth float 5.14775 Position size in ETH (only in case of ETH base currency)
floatingPl float -0.703874042 floating PnL
realizedPl float 0, realized PnL
estLiqPrice float 99999.99 Estimated liquidation price
markPrice float 8244.55 mark price
indexPrice float 8242.12 index price
maintenanceMargin float 0.214432564 maintenance margin
initialMargin float 0.357387607 initial margin
settlementPrice float 9145.26 The settlement price for the instrument
delta float 7.14775214 The position delta
openOrderMargin float 0 The margin used to back the position
profitLoss float -1.068422015 The PnL for the position

Example

// HTTP:
//   GET /api/v1/private/positions
// Websocket:
//   {"action": "/api/v1/private/positions"}

{
    "result": [
        {  
            "instrument": "BTC-30MAR18",
            "kind": "future",
            "size": 5893,
            "averagePrice": 9693.502194671,
            "direction": "buy",
            "sizeBtc": 7.14775214,
            "floatingPl": -0.703874042,
            "realizedPl": 0,
            "estLiqPrice": 99999.99,
            "markPrice": 8244.55,
            "indexPrice": 8242.12,
            "maintenanceMargin": 0.214432564,
            "initialMargin": 0.357387607,
            "settlementPrice": 9145.26,
            "delta": 7.14775214,
            "openOrderMargin": 0,
            "profitLoss": -1.068422015
        }
    ],
}

orderhistory

Retrieves history of orders that have been partially or fully filled. This API endpoint requires your request to be signed.

HTTP Usage: GET /api/v1/private/orderhistory

Websocket usage: {"action": "/api/v1/private/orderhistory", "arguments": {...}}

Arguments

name type default description
count integer 100 the number of items to be returned.
instrument string Either the name of an instrument, "future" of "option"
offset integer 0 The offset for pagination
currency string "BTC" When it is applicable. Possible values 'BTC', 'ETH'. Default is 'BTC'.
includeEarlyCanceled boolean false Include cancelled fully unfilled orders.

Response

The result field contains a a list of orders. These orders consists of the following fields:

name type example description
orderId integer 713637304 id of the order
type string "limit" order type, "limit", "market", "stop_limit","stop_market"
instrument string "BTC-23FEB18" instrument name of the order
direction string "buy" direction, "buy" or "sell"
price float 10100.0 price
label string "MyOrder" user defined label (up to 32 characters)
quantity number 1000 The number of contracts to be traded
amount number 10000 The amount as quantity in contract currency units
filledQuantity integer 700 The number of contracts already filled
filledAmount number The already filled amount in contract currency units
avgPrice float 10100.0 average fill price of the order
commission float 0 Commission paid so far (in BTC)
created integer 1517614581664 The timestamp (in ms) that the order was created
lastUpdate integer 1517614581664 The timestamp (in ms) that the order was last updated
state string "open" order state
postOnly boolean true true for post-only orders only
reduceOnly boolean true true for reduce-only orders only
api boolean true true - created with API
max_show number 1 Maximum quantity within an order to be shown to other customers, 0 for invisible order.
maxShow number 1 Maximum quantity within an order to be shown to other customers, 0 for invisible order.
maxShowAmount number 10 Maximum amount in contract currency units within an order to be shown to other customers, 0 for invisible order.
adv boolean/string false advanced type (false, or "usd" or "implv")
implv float 250 Option implied volatility in percent. (Only when adv=implv)
usd float 50 Option price in USD (Only if adv=usd)
stopPx float 10000.0 stop price (Only for future stop orders)
execInst string "index_price" Defines trigger type, required for stop limit orders, possible values "index_price", "mark_price" (Only valid for stop orders)
triggered boolean false Whether the stop order has been triggered (Only for future stop orders)

Example

// HTTP:
//   GET /api/v1/private/orderhistory?count=10
// Websocket:
//   {"action": "/api/v1/private/orderhistory",
//    "arguments": {"count": 10}}

{
    "result": [
        {
            "orderId": 723289117,
            "type": "limit",
            "instrument": "BTC-23FEB18-10500-P",
            "direction": "sell",
            "price": 0.2633,
            "quantity": 5,
            "filledQuantity": 5,
            "avgPrice": 0.26,
            "state": "filled",
            "created": 1517765999188,
            "tstamp": 1517766824804,
            "commission": 0,
            "modified": 1517766824810,
            "label": "",
            "postOnly": false,
        }
    ],
}

orderstate

Retrieve order details state by order id. This API endpoint requires your request to be signed.

HTTP Usage: GET /api/v1/private/orderstate

Websocket usage: {"action": "/api/v1/private/orderstate", "arguments": {...}}

Arguments

name type default description
orderId integer 100 Required, the ID of the order to be retrieved

Response

The result field contains single order. An order consists of the following fields:

name type example description
orderId integer 713637304 id of the order
type string "limit" order type, "limit", "market", "stop_limit", "stop_market"
instrument string "BTC-23FEB18" instrument name of the order
direction string "buy" direction, "buy" or "sell"
price float 10100.0 price
label string "MyOrder" user defined label (up to 32 characters)
quantity number 1000 The number of contracts to be traded
amount number 10000 The amount as quantity in contract currency units
filledQuantity number 700 The number of contracts already filled
filledAmount number 7000 The already filled amount in contract currency units
avgPrice float 10100.0 average fill price of the order
commission float 0 Commission paid so far (in BTC)
created integer 1517614581664 The timestamp (in ms) that the order was created
lastUpdate integer 1517614581664 The timestamp (in ms) that the order was last updated
state string "open" order state
postOnly boolean true true for post-only orders only
reduceOnly boolean true true for reduce-only orders only
api boolean true true - created with API
max_show number 1 Deprectated. Maximum quantity within an order to be shown to other customers, 0 for invisible order.
maxShow number 1 Maximum quantity within an order to be shown to other customers, 0 for invisible order.
maxShowAmount number 10 Maximum amount in contract currency units within an order to be shown to other customers, 0 for invisible order.
adv boolean/string false advanced type (false, or "usd" or "implv")
implv float 250 Option implied volatility in percent. (Only when adv=implv)
usd float 50 Option price in USD (Only if adv=usd)
stopPx float 10000.0 stop price (Only for future stop orders)
execInst string "index_price" Defines trigger type, required for stop limit orders, possible values "index_price", "mark_price" (Only valid for stop orders)
triggered boolean false Whether the stop order has been triggered (Only for future stop orders)

Example

// HTTP:
//   GET /api/v1/private/orderstate?orderId=723289117
// Websocket:
//   {"action": "/api/v1/private/orderstate",
//    "arguments": {"orderId": 723289117}}

{
    "result": {
        "orderId": 723289117,
        "type": "limit",
        "instrument": "BTC-23FEB18-10500-P",
        "direction": "sell",
        "price": 0.2633,
        "quantity": 5,
        "filledQuantity": 5,
        "avgPrice": 0.26,
        "state": "filled",
        "created": 1517765999188,
        "tstamp": 1517766824804,
        "commission": 0,
        "modified": 1517766824810,
        "label": "",
        "postOnly": false,
    },
}

tradehistory

Retrieve the trade history of the account. This API endpoint requires your request to be signed.

HTTP Usage: GET /api/v1/private/tradehistory

Websocket usage: {"action": "/api/v1/private/tradehistory", "arguments": {...}}

Arguments

Parameter type default description
sort string "desc" DEPRECATED, "asc" for ascending, "desc" for descending
instrument string REQUIRED Either the name of the instrument, or "all" for instruments, "futures" for all futures, or "options" for all options.
count integer 10 The number of trades returned (clamped to max 1000)
startId integer The ID of the first trade to be returned
endId integer The ID of the last trade to be returned
startSeq integer The trade sequence of the first trade to be returned
endSeq integer The trade sequence of the last trade to be returned
startTimestamp integer The timestamp (in ms) of the first trade to be returned
endTimestamp integer The timestamp (in ms) of the last trade to be returned
since integer DEPRECATED, The ID after which trades are returned, for backward compatibility
direction string DEPRECATED, alias to "sort", for backward compatibility
includeOld bool false to get archived trades for expired instruments when true (added from performance considerations)
currency string "BTC" When it is applicable. Possible values 'BTC', 'ETH'. Default is 'BTC'.

Response

The response contains the a list of trades in the result field. A trade consists of the following fields:

name type example description
tradeId string 49366 The ID for the trade
instrument string "BTC-25AUG17-3900-C" The name of the instrument
tradeSeq string 1 The trade sequence number
timeStamp string 1503439494351 The timestamp of the trade in ms
quantity number 5 The quantity traded
amount number 5 The amount as quantity in contract currency units
price string 0.055 The price of the trade
side string "buy" Trade side from the user's point of view
tickDirection string 1 Direction of the "tick". 0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick
indexPrice string 4101.46 Index price at trade
orderId string 1630491422 Order id if the user is taker
matchingId string 1630491555 Order id if the user is maker
liquidity string T T - user is taker, M - user is maker
fee number 0.00024347 fee paid so far
feeCurrency string BTC currency of the fee
selfTrade boolean false could be true on test-server if self trading allowed for the account by the admin
label string order1 label of the user's order
iv string 70.71 option implied volatility for the price (Options only)

Example


// HTTP:
//    GET /api/v1/private/tradehistory?instrument=all
// Websocket:
//   {"action": "/api/v1/private/tradehistory",
//    "arguments": {"instrument": "all"}}

{
    "success": true,
    "testnet": false,
    "message": "",
    "usIn": 1528814000104342,
    "usOut": 1528814000104611,
    "result": [
        {
            "tradeId": 7186202,
            "instrument": "BTC-28SEP18",
            "timeStamp": 1528631913389,
            "tradeSeq": 252216,
            "quantity": 30,
            "price": 7093,
            "side": "buy",
            "orderId": 4479673241,
            "matchingId": 4853295396,
            "liquidity": "M",
            "fee": -0.000008459,
            "feeCurrency": "BTC",
            "tickDirection": 2,
            "indexPrice": 7069.14,
            "selfTrade": false
        },
        ...
    ]
}

newannouncements

Retrieves announcements that have not been marked read by the current user. This API endpoint requires your request to be signed. This API endpoint does not take any arguments.

HTTP usage: GET /api/v1/private/newannouncements

Websocket usage: {"action": "/api/v1/private/newannouncements"}

Response

The result field contains a list of announcements. Each announcement has the following fields:

name type example description
title string "Example announcement" The title of the announcement
body string "An announcement" The HTML body of the announcement
important bool false Whether the announcement is marked as important
id int 19288317 A unique identifier for the announcement
date int 1527844253000 Timestamp in ms at which the announcement was published

Example

// HTTP:
//   GET /api/v1/public/newannouncements
// Websocket:
//   {"action": "/api/v1/public/newannouncements"}

{
    "result": [
        {
            "title": "DERIBIT TESTNET announcement",
            "important": false,
            "id": 1516016139692,
            "date": 1516016117000,
            "body": "DERIBIT TESTNET announcement"
        }
    ],
}

logout

Logs out the websocket connection. The server will respond by closing the connection. This API endpoint requires your request to be signed. This API endpoint does not take any arguments.

Websocket usage: {"action": "/api/v1/private/logout"}

Response

The server will respond by closing the connection

Example

// Websocket:
//   {"action": "/api/v1/private/logout"}

cancelondisconnect

Enables or disables "COD" (cancel on disconnect) for the current connection. This API endpoint requires your request to be signed. This does not change the default account setting. This API endpoint cannot be used over HTTP

Websocket usage: {"action": "/api/v1/private/cancelondisconnect"}

Arguments

name type default description
state string REQUIRED. Whether COD is to be enabled for this connection. "enabled" or "disabled"

Response

This API endpoint will return an empty response (i.e. without an result field)

Example

// Websocket:
//   {"action": "/api/v1/public/cancelondisconnect",
//    "arguments": { "state": "enabled"}}

{
    ...
}

datatable

This is a private API endpoint intended for the user interface. This API is subject to change, and should not be used outside the Deribit interface.

getemaillang

Retrieves the language to be used for emails. This API endpoint requires your request to be signed. This API does not take any parameters.

HTTP usage: GET /api/v1/private/getemaillang

Websocket usage: {"action": "/api/v1/private/getemaillang"}

Response

The result field will be a string with the abbreviated language name (e.g. "en", "ko", "zh")

Example

// HTTP:
//   GET /api/v1/private/getemaillang
// Websocket:
//   {"action": "/api/v1/private/getemaillang"}

{
    "result": "en",
}

setemaillang

Changes the language to be used for emails. This API endpoint requires your request to be signed. When used over HTTP, this API endpoint requires POST.

HTTP usage: GET /api/v1/private/setemaillang

Websocket usage: {"action": "/api/v1/private/setemaillang"}

Arguments

name type default description
lang string REQUIRED, the abbreviated language name. Valid values include "en", "ko", "zh"

Response

This API endpoint will return an empty response (i.e. without an result field)

Example

// HTTP:
//   POST /api/v1/private/setemaillang
//   lang=en
// Websocket:
//   {"action": "/api/v1/private/setemaillang",
//    "arguments": {"lang": "en"}}

{
    "result": null,
}

setannouncementasread

Marks an announcement as read, so it will not be shown in newannouncements. This API endpoint requires your request to be signed. When used over HTTP, this API endpoint requires POST.

HTTP usage: GET /api/v1/private/setannouncementasread

Websocket usage: {"action": "/api/v1/private/setannouncementasread

Arguments

name type default description
announcementid integer REQUIRED, the ID of the announcement

Example

// HTTP:
//   POST /api/v1/private/setannouncementasread
//   announcementid=199238817
// Websocket:
//   {"action": "/api/v1/private/setannouncementasread",
//    "arguments": {"announcementid": "199238817"}}
{
    "result": "ok",
}

settlementhistory

Retrieves settlement, delivery and bankruptcy events that have affected your account. This API endpoint requires your request to be signed.

HTTP usage: GET /api/v1/private/settlementhistory

Websocket usage: {"action": "/api/v1/private/settlementhistory", "arguments": {...}}

Arguments

name type example description
instrument string all The instrument name, or "all" to retrieve settlements for all instruments.
count integer 10 The number of entries to be returned. This is clamped to max 1000
type integer The type of settlements to return. Possible values "settlement", "delivery", "bankruptcy"
startTstamp integer The latest timestamp to return result for.
continuation string Continuation token for pagination. Each response contains a token to be used for continuation.
currency string "BTC" Possible values 'BTC', 'ETH'. Default is 'BTC'.

Response

The result field contains two fields: continuation, which is the continuation token for pagination and settlements. Settlements contain the following fields:

name type example description
type string "settlement" The type of settlement
timeStamp string 1517299201923 The timestamp of the settlement
sessionProfitLoss string 4.17243092
position string 1000 position size (settlement and delivery only)
instrument string "BTC-30MAR18" instrument name (settlement and delivery only)
indexPrice float 11008.37 Underlying index price at time of event (settlement and delivery only)
markPrice float 11000 Mark price for at the time (settlement and delivery only)
profitLoss float 0 profit and loss (settlement and delivery only)
funded string 0 Funded amount (bankruptcy only)
socialized float -3e-9 The amount of the losses socialized
sessionBankrupcy float 0.001160788 in BTC
sessionTaxRate float 0.000103333 in BTC
sessionTax float -3e-9 in BTC

Example

// HTTP:
//   GET /api/v1/private/settlementhistory?instrument=BTC-23MAR18-9500-P
// Websocket:
//   {"action": "/api/v1/private/settlementhistory",
//    "arguments": {"instrument": BTC-23MAR18-9500-P}}

{
    "result": {
        "settlements": [
            {
                "instrument":"BTC-23MAR18-9500-P"
                "position":26591.7
                "indexPrice":8407.01
                "markPrice":0.130009361
                "profitLoss":-1.973096726
                "type":"delivery"
                "timeStamp":1521792000104
                "sessionProfitLoss":820.137161473},
            {
                "instrument":"BTC-30MAR18"
                "position":151042
                "indexPrice":7530.81
                "markPrice":7498.3
                "profitLoss":-9.060882648999993
                "type":"settlement"
                "timeStamp":1522310400113
                "sessionProfitLoss":40791.1364678138},
            {
                "funded":0.12781214200000002
                "socialized":0.0
                "sessionBankrupcy":1.0232674799999997
                "sessionTaxRate":0.0
                "sessionTax":0.12781214200000002
                "type":"bankruptcy"
                "timeStamp":1522396800132
                "sessionProfitLoss":1923.3313302059998},
            ...
        ],
        "continuation": "xY7T6cut9u3vfTpDNun2T88wzDVfrNdKFeSDVgBGzmKdsMHgNxEwX"
    }
    ...
}

subscribe

Subscribes to a notification channel. See Websocket notifications for details. This API endpoint cannot be used over HTTP.

Calling subscribe will replace all previous subscriptions for this connection.

Websocket usage: {"action": "/api/v1/private/subscribe", "arguments": {...}}

Arguments

name type default description
event array of strings REQUIRED, the events to subscribe to. See below for available event channels.
instrument array of strings all REQUIRED, the instrument names to subscribe for. Use "futures", "options" or "all" to subscribe to groups of instruments.
continue bool false OPTIONAL, set the continue to true to not override previous subscription, otherwise previous subscribe will be cancelled
depth number 20 OPTIONAL, max depth of the order book snapshot, used for the order_book subscription. Allowed values are: 1, 10, 20.
group number OPTIONAL, to group the futures' order book entries by USD group, if specified - allowed values 1, 5, 10, 100.
currency string "BTC" When it is applicable. Possible values 'BTC', 'ETH', 'all' (the last is the alias for all currencies). Default is 'BTC'.

Warning! The instruments of different currencied can't be mixed in the subscribe. It is recommended to use "currency" always to avoid unexpected fallback to BTC currency

The following events can be subscribed to:

  • order_book, notifies of order book changes
  • trade, trade notifications
  • my_trade, trade notifications, filtered for user trades.
  • user_order, notifies of opened, changed or filled user orders.
  • portfolio, notifies of portfolio changes.
  • announcement, notifies of index value at frequent intervals.
  • delivery, notifies of deliveries.

Special instrument index - can be used to subscribe for price index changes.

Response

This API endpoint will return an empty response (i.e. without an result field), and start sending notification of events as they occur.

Example

// Websocket:
//   {"action": "/api/v1/private/subscribe",
//    "arguments": {"event": ["order_book"],
//                  "instrument": ["BTC-28SEP18-35000-P"]}}

{
    ...
}

unsubscribe

Unsubscribes from a notification channel. See Websocket notifications for details. This API endpoint cannot be used over HTTP.

Websocket usage: {"action": "/api/v1/private/unsubscribe", "arguments": {...}}

Arguments

name type default description
event array of strings REQUIRED, the events to unsubscribe from.
instrument array of strings REQUIRED, the instrument names to unsubscribe for. Use "futures", "options" or "all" to unsubscribe for groups of instruments.

Response

This API endpoint will return an empty response (i.e. without an result field)

Example

// Websocket:
//   {"action": "/api/v1/private/unsubscribe",
//    "arguments": {"event": ["order_book"],
//                  "instrument": ["BTC-28SEP18-35000-P"]}}

{
    ...
}

results matching ""

    No results matching ""