Order Book

Endpoint to handle Order book operations like creating BID / ASK trades between Tatum Private Virtual accounts, obtaining trade histories, creating futures etc. It is possible to build an exchange based on the Ledger Accounts.

Store buy / sell trade

2 credits for API call, 2 credits for each fill of the counter trade. 1 API call + 2 fills = 6 credits.


Store new buy / sell trade. If there is trade already available to fill, fill as much trades as possible.
It is possible to charge fees for the trades. Fees are an extra amount on top of the trade amount and are paid in the currency that you going to block e.g.: - BUY BTC/USDT - fees will be paid in USDT - SELL BTC/ETH - fees will be paid in BTC

If you fill type of the trade with FUTURE_BUY or FUTURE_SELL the trade will behave as a trade future. The trade is concluded now but will be fulfilled in future. The date of fulfillment is by the “Seal Date” field. You can also block a percentage of the amount until the future trade has expired.

Futures can also penalize contracting parties if they don’t have the agreed balance available in their accounts. The penalty is calculated in the following way: Penalty amount = (Percentage of incomplete deal amount because of shortage from user) × (Maximum Penalty percentage of futures deal based on blocked amount and time interval) × (total blocked value).

Example of the BTC/USDT trade future:

The maker creates a sell with the following properties: 1 BTC at a price of 60000 USDT, with a blocking percentage of 22%, a penalty percentage of 45%, a system commision of 1% and with an expiration time of within 12 hours.

{
  "type": "FUTURE_SELL",
  "price": "60000",
  "amount": "1",
  "pair": "BTC/USDT",
  "currency1AccountId": "60a236db1b57f60d62612bf3",
  "currency2AccountId": "609d0696bf835c241ac2920f",
  "fee": 1,
  "feeAccountId": "609d0696bf835c251ac2920a",
  "attr": {
    "sealDate": 1621990960631,
    "percentBlock": 22,
    "percentPenalty": 45
  }
}

The taker accepts the offer with a buy and blocks 13200 USDT (60000 USDT × 0.22) in their account.

{
  "type": "FUTURE_BUY",
  "price": "60000",
  "amount": "1",
  "pair": "BTC/USDT",
  "currency1AccountId": "60a236db1b57f60d62612bf2",
  "currency2AccountId": "609d0696bf835c241ac2920a",
  "attr": {
    "sealDate": 1621990960631,
    "percentBlock": 22,
    "percentPenalty": 45
  }
}

At the time of the trade, the maker and taker have the following conditions. The maker has 0.65 BTC (35% deficit) in their account and the taker has 49200 USDT (18% deficit) in their account.

The maker penalty is equal to 0.35 × 0.22 × (0.45 × 1 BTC) = 0.03465 BTC. The taker penalty is equal to 0.18 × 0.22 × (0.45 × 60000 USDT) = 1069.2 USDT.

The system commission for the maker is 1 BTC × 1% = 0.01 BTC. The system commission for the taker is 60000 USDT × 1% = 600 USDT.

The maker’s assets after deducting penalties and commissions equals 0.65 - 0.03465 - 0.01 = 0.60535 BTC. The taker’s assets after deducting penalties and commissions equals 49200 - 1069.2 - 600 = 47530.8 USDT.

The amount received by the maker after the trade is (0.60535 × 60000) + 1069.2 = 37390.2 USDT and the taker receives 0.60535 + 0.03465 = 0.64 BTC.

SecurityX-API-Key
Request
Request Body schema: application/json
One of:
type
required
string

Type of the regular trade, BUY, SELL

Enum: "BUY" "SELL"
price
required
string <= 38 characters ^[+]?((\d+(\.\d*)?)|(\.\d+))$

Price to buy / sell

amount
required
string <= 38 characters ^[+]?((\d+(\.\d*)?)|(\.\d+))$

Amount of the trade to be bought / sold

pair
required
string [ 3 .. 30 ] characters ^[A-a-zZ0-9_\-]+\/[A-Za-z0-9_\-]+$

Trading pair

currency1AccountId
required
string = 24 characters

ID of the account of the currency 1 trade currency

currency2AccountId
required
string = 24 characters

ID of the account of the currency 2 trade currency

feeAccountId
string = 24 characters

ID of the account where fee will be paid, if any. If trade is a BUY or FUTURE_BUY type, feeAccountId must have same currency as a currency of currency2AccountId, and vice versa if trade is a SELL or FUTURE_SELL type, feeAccountId must have same currency as a currency of currency1AccountId.

fee
number [ 0 .. 100 ]

Percentage of the trade amount to be paid as a fee.

Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

403

Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions.

500

Internal server error. There was an error on the server while processing the request.

post/v3/trade
Request samples
application/json
{
  • "type": "BUY",
  • "price": "8650.4",
  • "amount": "15000",
  • "pair": "BTC/EUR",
  • "currency1AccountId": "7c21ed165e294db78b95f0f1",
  • "currency2AccountId": "7c21ed165e294db78b95f0f1"
}
Response samples
application/json
{
  • "id": "5e68c66581f2ee32bc354087"
}

Obtain chart data from historical closed trades

2 credits for API call.


Obtain data from the closed trades for entering in the chart. Time interval is set between from and to and there is defined time frame. There can be obtained at most 200 time points in the time interval.

SecurityX-API-Key
Request
Request Body schema: application/json
pair
required
string [ 3 .. 30 ] characters ^[A-a-zZ0-9_\-]+\/[A-Za-z0-9_\-]+$

Trading pair

from
required
number >= 0

Start interval in UTC millis.

to
required
number >= 0

End interval in UTC millis.

timeFrame
required
string

Time frame of the chart.

Enum: "MIN_1" "MIN_3" "MIN_5" "MIN_15" "MIN_30" "HOUR_1" "HOUR_4" "HOUR_12" "DAY" "WEEK" "MONTH" "YEAR"
Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

500

Internal server error. There was an error on the server while processing the request.

post/v3/trade/chart
Request samples
application/json
{
  • "pair": "BTC/EUR",
  • "from": 1613654998398,
  • "to": 1613654998398,
  • "timeFrame": "MIN_5"
}
Response samples
application/json
[
  • {
    }
]

List all historical tradesDeprecated

1 credit per API call.


List all historical trades. It is possible to list all trades, trades for specific trading pair and/or account.

SecurityX-API-Key
Request
query Parameters
id
string

Account ID. If present, only closed trades for given account will be present.

Example: id=5e68c66581f2ee32bc354087
pair
string [ 3 .. 30 ] characters ^[A-a-zZ0-9_\-]+\/[A-Za-z0-9_\-]+$

Trade pair. If present, only closed trades on given trade pair will be present.

Example: pair=BTC/ETH
pageSize
required
number [ 1 .. 50 ]

Max number of items per page is 50.

Example: pageSize=10
offset
number

Offset to obtain next page of the data.

Example: offset=0
count
boolean

Get the total trade pair count based on the filter. Either count or pageSize is accepted.

Example: count=true
types
Array of strings

Trade types.

Items Enum: "FUTURE_BUY" "FUTURE_SELL" "BUY" "SELL"
Example: types=BUY
Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

500

Internal server error. There was an error on the server while processing the request.

get/v3/trade/history
Request samples
Response samples
application/json
[
  • {
    }
]

List all historical trades

1 credit per API call.


List all historical trades. It is possible to list all trades, trades for specific trading pair and/or account.

SecurityX-API-Key
Request
Request Body schema: application/json
id
string

Account ID. If present, only closed trades for given account will be present.

customerId
string

Customer ID. If present, only closed trades for given customer will be present.

pageSize
required
number [ 1 .. 50 ]

Max number of items per page is 50.

offset
number

Offset to obtain next page of the data.

pair
string [ 3 .. 30 ] characters ^[A-a-zZ0-9_\-]+\/[A-Za-z0-9_\-]+$

Trade pair. If present, list historical trades for that pair.

count
boolean

Get the total trade pair count based on the filter. Either count or pageSize is accepted.

types
Array of strings

Trade types.

Items Enum: "FUTURE_BUY" "FUTURE_SELL" "BUY" "SELL"
Array of objects

Amount of the trade. AND is used between filter options.

Array
op
required
string

Filtering operation.

Enum: "gte" "lte" "gt" "lt" "eq" "neq"
value
required
string

Value of the operation.

Array of objects

Fill of the trade. AND is used between filter options.

Array
op
required
string

Filtering operation.

Enum: "gte" "lte" "gt" "lt" "eq" "neq"
value
required
string

Value of the operation.

Array of objects

Price of the trade. AND is used between filter options.

Array
op
required
string

Filtering operation.

Enum: "gte" "lte" "gt" "lt" "eq" "neq"
value
required
string

Value of the operation.

Array of objects

Created date of the trade. AND is used between filter options.

Array
op
required
string

Filtering operation.

Enum: "gte" "lte" "gt" "lt" "eq" "neq"
value
required
string

Value of the operation.

sort
Array of strings (OrderBookSort)

Sorts the result by selected property. The priority of the items is determined by order of the sort properties in array.

Items Enum: "PRICE_ASC" "PRICE_DESC" "CREATED_ASC" "CREATED_DESC" "AMOUNT_ASC" "AMOUNT_DESC" "FILL_ASC" "FILL_DESC" "FEE_ASC" "FEE_DESC"
Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

500

Internal server error. There was an error on the server while processing the request.

post/v3/trade/history
Request samples
application/json
{
  • "pageSize": 10
}
Response samples
application/json
[
  • {
    }
]

List all active buy tradesDeprecated

1 credit per API call.


List all active buy trades.

SecurityX-API-Key
Request
query Parameters
id
string

Account ID. If present, list current active buy trades for that account.

Example: id=5e68c66581f2ee32bc354087
customerId
string

Customer ID. If present, list current active buy trades for that customer.

Example: customerId=5e68c66581f2ee32bc354087
pageSize
required
number [ 1 .. 50 ]

Max number of items per page is 50.

Example: pageSize=10
offset
number

Offset to obtain next page of the data.

Example: offset=0
pair
string [ 3 .. 30 ] characters ^[A-a-zZ0-9_\-]+\/[A-Za-z0-9_\-]+$

Trade pair. If present, list current active buy trades for that pair.

Example: pair=BTC/EUR
count
boolean

Get the total trade pair count based on the filter. Either count or pageSize is accepted.

Example: count=true
tradeType
string

Trade type.

Enum: "FUTURE_BUY" "BUY"
Example: tradeType=BUY
Responses
200

OK

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

500

Internal server error. There was an error on the server while processing the request.

get/v3/trade/buy
Request samples
Response samples
application/json
[
  • {
    }
]

List all active buy trades

1 credit per API call.


List all active buy trades.

SecurityX-API-Key
Request
Request Body schema: application/json
id
string

Account ID. If present, list current active sell trades for that account.

customerId
string

Customer ID. If present, list current active buy trades for that customer.

pageSize
required
number [ 1 .. 50 ]

Max number of items per page is 50.

offset
number

Offset to obtain next page of the data.

pair
string [ 3 .. 30 ] characters ^[A-a-zZ0-9_\-]+\/[A-Za-z0-9_\-]+$

Trade pair. If present, list current active sell trades for that pair.

count
boolean

Get the total trade pair count based on the filter. Either count or pageSize is accepted.

tradeType
string

Trade type.

Enum: "FUTURE_BUY" "BUY"
Array of objects

Amount of the trade. AND is used between filter options.

Array
op
required
string

Filtering operation.

Enum: "gte" "lte" "gt" "lt" "eq" "neq"
value
required
string

Value of the operation.

Array of objects

Fill of the trade. AND is used between filter options.

Array
op
required
string

Filtering operation.

Enum: "gte" "lte" "gt" "lt" "eq" "neq"
value
required
string

Value of the operation.

Array of objects

Price of the trade. AND is used between filter options.

Array
op
required
string

Filtering operation.

Enum: "gte" "lte" "gt" "lt" "eq" "neq"
value
required
string

Value of the operation.

Array of objects

Created date of the trade. AND is used between filter options.

Array
op
required
string

Filtering operation.

Enum: "gte" "lte" "gt" "lt" "eq" "neq"
value
required
string

Value of the operation.

sort
Array of strings (OrderBookSort)

Sorts the result by selected property. The priority of the items is determined by order of the sort properties in array.

Items Enum: "PRICE_ASC" "PRICE_DESC" "CREATED_ASC" "CREATED_DESC" "AMOUNT_ASC" "AMOUNT_DESC" "FILL_ASC" "FILL_DESC" "FEE_ASC" "FEE_DESC"
Responses
200

OK

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

500

Internal server error. There was an error on the server while processing the request.

post/v3/trade/buy
Request samples
application/json
{
  • "pageSize": 10
}
Response samples
application/json
[
  • {
    }
]

List all active sell tradesDeprecated

1 credit per API call.


List all active sell trades.

SecurityX-API-Key
Request
query Parameters
id
string

Account ID. If present, list current active sell trades for that account.

Example: id=5e68c66581f2ee32bc354087
customerId
string

Customer ID. If present, list current active buy trades for that customer.

Example: customerId=5e68c66581f2ee32bc354087
pageSize
required
number [ 1 .. 50 ]

Max number of items per page is 50.

Example: pageSize=10
offset
number

Offset to obtain next page of the data.

Example: offset=0
pair
string [ 3 .. 30 ] characters ^[A-a-zZ0-9_\-]+\/[A-Za-z0-9_\-]+$

Trade pair. If present, list current active sell trades for that pair.

Example: pair=BTC/EUR
count
boolean

Get the total trade pair count based on the filter. Either count or pageSize is accepted.

Example: count=true
tradeType
string

Trade type.

Enum: "FUTURE_SELL" "SELL"
Example: tradeType=SELL
Responses
200

OK

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

500

Internal server error. There was an error on the server while processing the request.

get/v3/trade/sell
Request samples
Response samples
application/json
[
  • {
    }
]

List all active sell trades

1 credit per API call.


List all active sell trades.

SecurityX-API-Key
Request
Request Body schema: application/json
id
string

Account ID. If present, list current active sell trades for that account.

customerId
string

Customer ID. If present, list current active buy trades for that customer.

pageSize
required
number [ 1 .. 50 ]

Max number of items per page is 50.

offset
number

Offset to obtain next page of the data.

pair
string [ 3 .. 30 ] characters ^[A-a-zZ0-9_\-]+\/[A-Za-z0-9_\-]+$

Trade pair. If present, list current active sell trades for that pair.

count
boolean

Get the total trade pair count based on the filter. Either count or pageSize is accepted.

tradeType
string

Trade type.

Enum: "FUTURE_SELL" "SELL"
Array of objects

Amount of the trade. AND is used between filter options.

Array
op
required
string

Filtering operation.

Enum: "gte" "lte" "gt" "lt" "eq" "neq"
value
required
string

Value of the operation.

Array of objects

Fill of the trade. AND is used between filter options.

Array
op
required
string

Filtering operation.

Enum: "gte" "lte" "gt" "lt" "eq" "neq"
value
required
string

Value of the operation.

Array of objects

Price of the trade. AND is used between filter options.

Array
op
required
string

Filtering operation.

Enum: "gte" "lte" "gt" "lt" "eq" "neq"
value
required
string

Value of the operation.

Array of objects

Created date of the trade. AND is used between filter options.

Array
op
required
string

Filtering operation.

Enum: "gte" "lte" "gt" "lt" "eq" "neq"
value
required
string

Value of the operation.

sort
Array of strings (OrderBookSort)

Sorts the result by selected property. The priority of the items is determined by order of the sort properties in array.

Items Enum: "PRICE_ASC" "PRICE_DESC" "CREATED_ASC" "CREATED_DESC" "AMOUNT_ASC" "AMOUNT_DESC" "FILL_ASC" "FILL_DESC" "FEE_ASC" "FEE_DESC"
Responses
200

OK

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

500

Internal server error. There was an error on the server while processing the request.

post/v3/trade/sell
Request samples
application/json
{
  • "pageSize": 10
}
Response samples
application/json
[
  • {
    }
]

List all matched orders from FUTURE_SELL/FUTURE_BUY trades

1 credit per API call.


List all matched orders from the FUTURE_BUY OR FUTURE_SELL orders.

SecurityX-API-Key
Request
Request Body schema: application/json
id
string

Account ID. If present, list matched FUTURE_BUY/FUTURE_SELL orders trades for that account.

customerId
string

Customer ID. If present, list matched FUTURE_BUY/FUTURE_SELL orders trades for that customer.

pageSize
required
number [ 1 .. 50 ]

Max number of items per page is 50.

offset
number

Offset to obtain next page of the data.

pair
string [ 3 .. 30 ] characters ^[A-a-zZ0-9_\-]+\/[A-Za-z0-9_\-]+$

Trade pair. If present, list matched FUTURE_BUY/FUTURE_SELL orders trades for that pair.

count
boolean

Get the total trade pair count based on the filter. Either count or pageSize is accepted.

type
string

Trade type.

Enum: "FUTURE_SELL" "FUTURE_BUY"
Array of objects

Amount of the trade. AND is used between filter options.

Array
op
required
string

Filtering operation.

Enum: "gte" "lte" "gt" "lt" "eq" "neq"
value
required
string

Value of the operation.

Array of objects

Fill of the trade. AND is used between filter options.

Array
op
required
string

Filtering operation.

Enum: "gte" "lte" "gt" "lt" "eq" "neq"
value
required
string

Value of the operation.

Array of objects

Price of the trade. AND is used between filter options.

Array
op
required
string

Filtering operation.

Enum: "gte" "lte" "gt" "lt" "eq" "neq"
value
required
string

Value of the operation.

Array of objects

Created date of the trade. AND is used between filter options.

Array
op
required
string

Filtering operation.

Enum: "gte" "lte" "gt" "lt" "eq" "neq"
value
required
string

Value of the operation.

sort
Array of strings (OrderBookSort)

Sorts the result by selected property. The priority of the items is determined by order of the sort properties in array.

Items Enum: "PRICE_ASC" "PRICE_DESC" "CREATED_ASC" "CREATED_DESC" "AMOUNT_ASC" "AMOUNT_DESC" "FILL_ASC" "FILL_DESC" "FEE_ASC" "FEE_DESC"
Responses
200

OK

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

500

Internal server error. There was an error on the server while processing the request.

post/v3/trade/matched
Request samples
application/json
{
  • "pageSize": 10
}
Response samples
application/json
[
  • {
    }
]

Get existing trade

1 credit for API call


Get existing opened trade.

SecurityX-API-Key
Request
path Parameters
id
required
string

Trade ID

Example: 5e68c66581f2ee32bc354087
Responses
200

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

500

Internal server error. There was an error on the server while processing the request.

get/v3/trade/{id}
Request samples
Response samples
application/json
{
  • "id": "7c21ed165e294db78b95f0f1",
  • "type": "BUY",
  • "price": "8650.4",
  • "amount": "15000",
  • "pair": "BTC/EUR",
  • "isMaker": true,
  • "fill": "1500",
  • "feeAccountId": "7c21ed165e294db78b95f0f1",
  • "fee": 1.5,
  • "currency1AccountId": "7c21ed165e294db78b95f0f1",
  • "currency2AccountId": "7c21ed165e294db78b95f0f1",
  • "created": 1585170363103,
  • "attr": {
    }
}

Cancel existing trade

1 credit for API call


Cancel existing trade.

SecurityX-API-Key
Request
path Parameters
id
required
string

Trade ID

Example: 5e68c66581f2ee32bc354087
Responses
204

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

500

Internal server error. There was an error on the server while processing the request.

delete/v3/trade/{id}
Request samples
Response samples
application/json
{
  • "errorCode": "validation.failed",
  • "message": "Request validation failed. Please see data for additional information.",
  • "statusCode": 400,
  • "data": [
    ]
}

Cancel all existing trades for account

1 credit for API call, 1 credit for each cancelled trade. 1 API call + 2 cancellations = 3 credits.


Cancel all trades for account.

SecurityX-API-Key
Request
path Parameters
id
required
string

Account ID

Example: 5e68c66581f2ee32bc354087
Responses
204

OK

400

Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.

401

Unauthorized. Not valid or inactive subscription key present in the HTTP Header.

500

Internal server error. There was an error on the server while processing the request.

delete/v3/trade/account/{id}
Request samples
Response samples
application/json
{
  • "errorCode": "validation.failed",
  • "message": "Request validation failed. Please see data for additional information.",
  • "statusCode": 400,
  • "data": [
    ]
}