Tradias API v2

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Welcome to the tradias API documentation!

Bankhaus Scheich / tradias offers the essential infrastructure and services necessary to empower institutional investors to tap into the vast potential of digital assets. Drawing from decades of accumulated expertise, Bankhaus Scheich has established itself as a prominent securities trading bank and market maker on the Frankfurt Stock Exchange. Today, this wealth of knowledge is seamlessly integrated into Bankhaus Scheich’s FinTech arm, tradias, which offers services in OTC trading and market making in FX and digital assets. The options for interaction with tradias span from trading via API, to frontend trading, and even chat trading. The digital assets supported include more than 150 cryptocurrencies, as well as tokenized assets in the secondary market.

For more about tradias and our offerings, contact info-api@tradias.de or view additional information on https://www.tradias.de/.

The API provides the functionality of subscribing to live pricing, the submitting of orders, the viewing of live and historic executions as well as the initiation and tracking of settlement requests, enabling the automation of the settlement procedure.

Subscribing to current prices, placing orders and listening to order executions is achieved by means of the WebSocket protocol. The initiation and tracking of settlement requests, the retrieval of static and historic data and the placing of bulk orders uses the REST protocol.

In this documentation we separate the endpoints into several sections: Static Data, Pricing, Trading, Historic Data and Settlement.

Features:

tradias offers more than 150 digital assets. The Instruments endpoint returns an overview of all tradeable instruments.
tradias offers post-trade settlement based on a contractually agreed trading line and collateral requirements. The settlement procedure can be automated using our Settlement API, in the section Settlement Procedure. More on the parameters for the computation of risk figures can be found in the section for the endpoint Risk Figures.
Currently all orders are executed as Fill or Kill (FoK) orders. As a result, orders are either executed in their entirety or rejected, allowing for a simple yet powerful order management.
The placing of limit orders is possible, however, only “Fill or Kill”-limit orders are currently supported. More on the execution of limit orders can be found in the section for the Orders endpoint.

The following base URLs can be used for testing and productive usage, respectively:

Testing environment: https://api.preprod.tradias.link/ or
Productive environment: https://api.tradias.link/

Using any of the endpoints provided requires the authentication by the means of a long-lived Bearer token passed in the headers of each request (REST) or connection opening (WebSocket). The Bearer token is unique for a client and should be treated with the appropriate precaution. All requests to the productive environment need to originate from whitelisted IP addresses.

You will not be able to access the productive environment from IP addresses that are not whitelisted.

About tradias

The core products:

tradias is the FinTech arm of Bankhaus Scheich Wertpapierspezialist AG, a well-established fully regulated and licenced (BaFin) trading house specialized in Market Making and OTC Bond trading with 35+ years of experience;
tradias specializes in trading digital assets as a market maker and principal OTC Desk;
tradias is one of the biggest regulated OTC trading houses within the EU;
the team operates as regulated security trading house with asset manager capabilities,
the headquarters are situated in Europe’s heart of finance, Frankfurt, Germany.
tradias aggregates global crypto liquidity and has strong capabilities to service high numbers of trades and large volumes with a low risk approach;
tradias’ platform operates 24/7 trading everywhere with a >99.9% uptime;
tradias is the leading player in servicing EUR trading pairs;
tradias focuses on a strong and robust product delivery and an excellent execution quality.
tradias offers a post-trade settlement setup, enabling efficient liquidity management lower counterparty risk;
payment-for-orderflow setup enables retail platform business;
the platform is multi-asset capable - trading cryptocurrencies, digital assets, FX and tokenized assets is possible using the same connection to the same platform.

Further services provided by tradias & Bankhaus Scheich:

Tokenization
Borrowing/Lending
Asset Management

Overview

The API can be separated into the following sections:

Static Data: using the Instruments endpoint, you can view the tradeable instruments.
- Instruments (REST)
Pricing: the prices channel can be used to get live pricing for a given tradeable instrument.
- Prices (WebSocket)
Trading: the endpoints in this section allow the placing of orders and tracking of the resulting trades. It consists of the following endpoints:
- Orders (WebSocket)
- Trades (WebSocket)
- Bulk Orders (REST)
Historic Data: the Historic Data functionality consists of the following endpoints:
- Get Orders (REST) & Get Orders By Sequence ID (REST)
- Get Trades (REST) & Get Trades By Sequence ID (REST)
Settlement: the following endpoints serve the function to initiate, track and complete settlement requests. This process covers the accumulation of trades, net settlement amounts and corresponding linking of transactions, which enables a robust, reconciled and automatable settlement procedure:
- Settlement Request (REST)
- Get Settlement Request Status (REST)
- Get Settlement Request (REST)
- Get Settlement Transactions (REST)
- Map Transaction with Settlement Request Amount (REST)

The above separation solely aims to clarify the API’s structure, as the sections may intersect depending on the final setup.

First steps

Before accessing the API, the following steps need to be completed:

Sign up with tradias You can contact us for more information and sign up via info-api@tradias.de. Subsequently, our team will reach out to you to gather all necessary information to set you up for trading.
Share required data We will need to collect some data for the configurations in our system. This may include (but is not restricted to):
- Production IP-address to be whitelisted;
- PGP public key, to exchange sensitive information (see: PGP Encryption);
- Wallet addresses;
- Bank account addresses (e.g. IBAN);
- Proof of ownership of shared addresses (wallet and bank accounts).
Acquire the API key To acquire your API key (=Bearer token), we will need your public key. Additionally, you will need our public key, it can be found in the section PGP Encryption. The steps are:
1. Save our public key.
2. Send the public key of your PGP key pair to info-api@tradias.de.
3. We will send back the encrypted secret.
4. Decrypt the message using the private key of your PGP key pair.

Authentication

After successful registration with tradias, an API Key, which is a JSON Web Token (JWT), is generated and shared using a secure method.

The system allows only one active JWT per user account at a time. By default, all tokens have an expiry date - you will be approached once it is time for your token to be renewed. A newly generated Bearer token invalidates the previous one, however, for a grace period of at least 1 week, you will be able to use both tokens at the same time, to allow for a smooth transition.

Any request to the tradias API requires a valid JWT in the headers. The example on the right illustrates the correct format for including the JWT in the headers (python syntax).

headers = {"Authorization" : f"Bearer {YOUR_JWT}"}

Request and Response Format

Messages are sent in the JSON format. The first key indicates the message’s purpose and uniquely defines the schema of the value’s content. An example is given in the column on the right.

{
    "heartbeat": {
        "header": {
            "channel": "prices",
            "timestamp": "1970-01-01T00:00:00.000000Z"
        }
    }
}

More specifically, the formats of the REST and WebSocket requests and responses look as described below.

REST endpoints

The requests always include a key called “req_header”. This header consists of two keys, a request ID: “req_id” and user data: “user_data”, these are ‘external’ references, meaning that the user has control over what values he wants to pass here and he will be able to view those values when querying the result later on. The request ID can be used as an idempotency key, meaning that when we see two requests with the same request ID, we do not process the most recent of those requests. The value for “user_data” is an object where the key-value pairs can be chosen freely by the user sending the request.
Next to these external references, we also have ‘internal’ references. Those are references, given by tradias, to the requests. For example, orders are always given an order_id and trades are given a trade_id. These IDs are chosen by tradias, so the user has no influence on their value.
When applicable, the responses always return the request ID and the user data, to help you distinguish to which request the response belongs.

WebSocket endpoints

Upon connecting with a WebSocket endpoint, a channel subscription message must be sent. The WebSocket channels serve logically separated purposes (e.g. pricing or trading) and can be unsubscribed from any time. An example of a subscription message format is shown on the right.

{
    "subscribe_price_channel": {
        "channel": "prices",
        "heartbeat_interval": 30
    }
}

Responses from WebSocket endpoints always contain a header with channel name and timestamp, along with the content of the message, which is channel-specific. An example is given on the right.

{
    "channel_subscription_confirmation": {
        "header": {
            "channel": "prices",
            "timestamp": "1970-01-01T00:00:00.000000Z"
        },
        "status": "ACTIVE",
        "heartbeat_interval": 30
    }
}

Errors and Status Codes

The status codes and errors that occur the tradias REST API responses are:

Response Code	Description
200	Successful response.
202	Successful response (Settlement & Bulk Order endpoints).
401	Unauthorized. Check your authentication.
403	Forbidden. You are not allowed to execute the desired action.
404	Not found. The information you are requesting cannot be found.
409	Duplicate request. The value for “req_id” has been used before.
422	Unprocessable content/validation error, check the validity of the passed format.
500	Internal server error. An unexpected error occurred.

Error responses from the WebSocket API consist of a message with an “error” key defining the error type and a descriptive “error_text” key containing further details. The specific possible errors in the WebSocket API are dealt with in the respective sections.

PGP Encryption

To exchange sensitive information, PGP Encryption is the preferred method. Below you can find an explanation on how to set up your key pair and encrypt and decrypt files. The PGP public key belonging to tradias can be found at the end of this section.

In the following section the setup of PGP is described using the open source GPG implementation with Kleopatra as the GUI on a Windows system. Depending on your operating system, other implementations may require slight variations in the steps described. For more details, please check https://www.gnupg.org/.

Set up a PGP key pair by following these steps:

Download the OpenPGP software: https://www.gnupg.org/download/index.html.
Make sure to install Kleopatra along with the GPG Backend (default in the gpg4win package).
Open Kleopatra and click ‘File’ -> ‘New Key Pair…’ -> ‘Create a personal OpenPGP key pair’.
Name your key and enter an email address, add a passphrase for extra security if desired. After this, you should see the name of your key pair in the list ‘Certificates’.

Share your public key by following these steps:

Open Kleopatra and go to ‘Certificates’.
Click on the key pair for which you want to share your public key.
Click ‘Export’ on the top tool bar. This automatically exports your public key, you can save it anywhere you want on your computer.
Share the file you saved in step 3 with whomever you want to exchange sensitive information with.

Decrypt a file by following these steps:

If the file is encrypted using PGP, it will be a .gpg file. Right click on the file and select: ‘open in Kleopatra’.
Kleopatra will decrypt the file (in the case that your key is protected with a passphrase, enter it), after decryption, you can choose to save or open the file.

The public key for tradias is given in the column on the right.

Contact

If you have any questions or suggestions, please contact info-api@tradias.de. We are more than happy to hear your remarks. Thank you for trading with tradias!

Servers

Base URLs:

https://api.{environment}.tradias.link
- environment - Tradias provides different environments. Default: “preprod”
  - “”
  - “preprod”
wss://ws.{environment}.tradias.link
- environment - Tradias provides different environments. Default: “preprod”
  - “”
  - “preprod”

Authentication

HTTP Authentication, scheme: bearer

Static Data

Tradias offers 150+ tradeable digital and fiat assets. They can be traded against several fiat or other crypto currencies. The list of tradeable asset is subject to regular review.

The following section consists of endpoints returning static data. Such data will include information about instrument names, assets within a pair, related precision and maximum order sizes. This section contains the following endpoint(s):

Instruments (REST)

Get List of tradeable Instruments

Code samples

import requests
import json

PROTOCOL = "https"
ENVIRONMENT = "preprod"
MY_TOKEN = "ENTER YOUR TOKEN HERE"

URL = f"{PROTOCOL}://api.{ENVIRONMENT}.tradias.link/api/instruments"

rest_api_header = {
  "Authorization": "Bearer " + MY_TOKEN
}

tradeable_instruments = requests.get(url=URL, headers=rest_api_header)

print(json.dumps(tradeable_instruments.json(), indent=4))

GET /api/instruments

The Get List of tradeable Instruments endpoint returns a list of all instruments an API user can trade on the system. Apart from the instrument name, the response contains information about the instrument (e.g. the type of instrument, its legs and tenor), the trading limits and precisions. An instrument is a trading pair and it always consists of two assets, a leg 1 asset and a leg 2 asset. The leg 1 asset is the first asset that occurs in the pair and the leg 2 asset is the second. In some implementations they are referred to as the base asset and quote asset, respectively. The assets can be cryptocurrencies (including stablecoins) or fiats. Each asset has an associated precision, specifying up to how many decimals the amounts in this currency are accepted and computed. Each instrument has a maximum_leg_1_quantity associated with it, which indicates maximum order size for the instrument expressed in units of the leg 1 asset.

Example responses

200 Response

{
  "instrument_list": [
    {
      "instrument": "ALGO-EUR",
      "leg_1_asset": {
        "name": "Algorand",
        "code": "ALGO",
        "precision": 6
      },
      "leg_2_asset": {
        "name": "Euro",
        "code": "EUR",
        "precision": 2
      },
      "maximum_leg_1_quantity": "290000.0"
    },
    {
      "instrument": "AMP-EUR",
      "leg_1_asset": {
        "name": "Amp",
        "code": "AMP",
        "precision": 18
      },
      "leg_2_asset": {
        "name": "Euro",
        "code": "EUR",
        "precision": 2
      },
      "maximum_leg_1_quantity": "2400000.0"
    },
    {
      "instrument": "BTC-EUR/SP",
      "leg_1_asset": {
        "name": "Bitcoin",
        "code": "BTC",
        "precision": 8
      },
      "leg_2_asset": {
        "name": "Euro",
        "code": "EUR",
        "precision": 2
      },
      "maximum_leg_1_quantity": "36.0"
    }
  ]
}

401 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "Unauthorized",
    "error_text": "The JWT token could not be validated"
  }
}

422 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "ValidationError",
    "error_text": "The request is not valid"
  }
}

500 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "InternalServerError",
    "error_text": "Internal Server Error: the server can currently not process the request"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	List of tradeable Instruments	Inline
401	Unauthorized	Unauthorized	internal_error_type
422	Unprocessable Entity	Unprocessable Request	internal_error_type
500	Internal Server Error	Internal Server Error	internal_error_type

Response Schema

Status Code 200

List of tradeable Instruments

Name	Type	Required	Description
» instrument_list	[object]	true	Array of tradeable Instruments
»» instrument	instrument_type	true	Identifier for an instrument. It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]
»» leg_1_asset	asset_type	true	An asset describes a crypto or fiat asset. It consists of a name (readable name of the asset), a code representing the asset and of a precision, which defines the number of digits after the decimal point which can be used for quantities in this asset.
»»» name	asset_name_type	true	Name of a leg of an instrument
»»» code	asset_code_type	true	Identifier of a leg of an instrument
»»» precision	asset_precision_type	true	The number of digits after the decimal point which are allowed for a quantity.
»» leg_2_asset	asset_type	true	An asset describes a crypto or fiat asset. It consists of a name (readable name of the asset), a code representing the asset and of a precision, which defines the number of digits after the decimal point which can be used for quantities in this asset.
»» tenor	asset_tenor_type	false	Identifier of a tenor. The following tenors are supported * SP = Spot
»» maximum_leg_1_quantity	quantity_type	true	The quantity of a leg.

Pricing

This section consists of endpoints returning current prices per instrument and accounting for market depth. The WebSocket endpoint can be configured to allow for custom data load limits. For more details on this, we refer to the ‘Prices’ endpoint.

Price Levels: the price for a given instrument is dependent on the side and the quantity. The expected execution price is the price associated with to the lowest quantity in the price update message larger than order size (i.e. “the price of the next higher quantity”).
Execution: orders are always executed the latest price at the arrival time of the order.

The following endpoint is contained in this section:

Prices (WebSocket)

(Un)Subscribe Price Channel

Code samples

import websockets
import asyncio
import json

MY_TOKEN = "ENTER YOUR TOKEN HERE"
ENVIRONMENT = "preprod"
PROTOCOL = "wss"

URI = f"{PROTOCOL}://ws.{ENVIRONMENT}.tradias.link/ws/prices"

websocket_headers = {
    "Authorization": "Bearer " + MY_TOKEN
}

price_channel_subscription = {
    "subscribe_price_channel": {
        "channel": "prices",
        "heartbeat_interval": 30
    }}

instruments_list = [
    {
        "subscription_id": "XX-4567",
        "instrument": "BTC-EUR/SP",
        "max_frequency": 500
    },
    {
        "subscription_id": "TS-BTC",
        "instrument": "BTC-EUR/SP",
        "mergeable": False,
        "max_pending": 100
    },
    {
        "subscription_id": "XX-4549",
        "instrument": "ETH-EUR/SP",
        "max_frequency": 500
    },
    {
        "subscription_id": "TS-ETH",
        "instrument": "ETH-EUR/SP",
        "mergeable": False
    }
]

async def get_prices(instruments: list[dict]) -> None:
    async with websockets.connect(uri=URI, extra_headers=websocket_headers) as websocket:
        await websocket.send(json.dumps(price_channel_subscription))
        await websocket.send(json.dumps(
            {
                "subscribe_instruments": {
                    "channel": "prices",
                    "subscriptions": instruments_list
                }
            }))
        while True:
            print(await websocket.recv())

asyncio.run(get_prices(instruments=instruments_list))

PUB /ws/prices

With a subscription to this endpoint, you can get the price stream of our trading pairs (instruments), for several quantities (levels). For a given quantity you will be executed at the price of the next higher quantity that is shown in the ticker prices. It is possible to open multiple subscriptions to different price tickers in a single connection.

The prices that we stream differ per side and order quantity. This means that each quantity on each side will have a different price associated to it. On the buy side, the price of the trade increases with the quantity, while on the sell side the price decreases as the quantity increases.

The following logic applies for determining the price at which an order will be executed:

The price update messages contain multiple quantities per side, each linked to a different price. We also refer to these quantities as price levels. To determine the price at which the trade will be executed, the API user should look at the price level with the lowest quantity such that the quantity is still higher than the requested order amount.

For example, if a customer places an order to buy 8 AMP in the instrument AMPEUR, and the price updates are as follows:

Quantity: 1
- Buy price: 0.0018
- Sell price: 0.0016
Quantity: 5
- Buy price: 0.0086
- Sell price: 0.0084
Quantity: 10
- Buy price: 0.0174
- Sell price: 0.0169

In this scenario, the executed price for the trade would be 0.0174, since it is based on the level with a quantity of 10 AMP, as it is the first higher level beyond the customer’s requested quantity.

API users are given some control over the number of updates they receive. This is done via several parameters, the max_frequency, max_pending and the mergeables.

- mergeable: this parameter, when set to true, allows new updates to replace older updates when the API user is not able to read out the messages from the channel fast enough. This is mainly helpful when the price update rate is (too) high, since it will ensure that the latest price data is sent out to the user.

- max_frequency: this parameter can be used in conjunction with the parameter mergeable to specify the update rate that the API user can handle. It sets the time interval between updates for a subscription, if updates are sent faster than the specified max_frequency, the updates are merged. When it is set to 0, all updates are sent.

- max_pending: used to limit the queued updates for a subscription. If the number of queued updates surpasses this number, the newest updates will merge with the older ones until the queue’s size is below the max_pending number.

Note:

The number of price levels in the production environment can differ to that in the testing environment.
It can occur that there is only one-sided quoting available for an instrument (e.g., in case a coin gets delisted). In this case, prices don’t include both the sell_price and buy_price keys. For example: {“quantity”:“0.00002”,“sell_price”:“33698.32”}.

A subscription to the prices channel can be terminated using the message shown on the right.

  # Message to unsubscribe from price channel
  {
    "unsubscribe_channel": {
      "channel": "prices"
    }
  }

Body parameter

{
  "subscribe_price_channel": {
    "channel": "prices",
    "heartbeat_interval": 30
  }
}

Name	In	Type	Required
body	body	SubscribePriceChannel	false
» subscribe_price_channel	body	object	true
»» channel	body	channel_type	true
»» heartbeat_interval	body	heartbeat_interval_type	false

Enumerated Values

Parameter	Value
»» channel	orders
»» channel	prices
»» channel	trades

Example responses

Price Update Response

{
  "price_update": {
    "header": {
      "channel": "prices",
      "timestamp": "1970-01-01T00:08:00.000000Z"
    },
    "update_list": [
      {
        "subscription_id": "TS-BTC",
        "instrument": "BTC-EUR/SP",
        "status": "ACTUAL",
        "update_ts": "1970-01-01T00:07:58.973000Z",
        "levels": [
          {
            "quantity": "1.25867895",
            "buy_price": "23768.69386464",
            "sell_price": "23767.67893759"
          }
        ]
      },
      {
        "subscription_id": "TS-BTC",
        "instrument": "BTC-EUR/SP",
        "status": "ACTUAL",
        "update_ts": "1970-01-01T00:07:59.657000Z",
        "levels": [
          {
            "quantity": "1.25867895",
            "buy_price": "23768.63953056",
            "sell_price": "23767.23953056"
          }
        ]
      },
      {
        "subscription_id": "XX-4567",
        "instrument": "BTC-EUR/SP",
        "status": "ACTUAL",
        "merged": true,
        "first_ts": "1970-01-01T00:07:58.973000Z",
        "update_ts": "1970-01-01T00:07:59.657000Z",
        "levels": [
          {
            "quantity": "1.25867895",
            "buy_price": "23768.63953056",
            "sell_price": "23767.23953056"
          }
        ]
      }
    ]
  }
}

Status	Description
Price Update	Asynchronous price update message send by the server to the API user. A price update is a list of updates for different subscriptions. An update is sent for an subscription for each new status or price.
Heartbeat	Asynchronous heart beat message sent by the server to the subscriber
Subscription Confirmation	Confirmation of a Channel Subscription
Subscription Failed	Channel Subscription has failed, channel can’t be used
Subscription Rejection	Rejection of a Price Subscription
403	Message received when a new_order can not be executed

Response Price Update

Name	Type	Required	Description
» price_update	object	true	none
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» update_list	[object]	true	Array containing a list of updates for a subscription
»»» subscription_id	subscription_id_type	true	This field is set by the API user. It’s serves the purpose of identifying the instrument price subscription, it is not unique.
»»» instrument	instrument_type	true	Identifier for an instrument. It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]
»»» status	price_status_type	false	The status of a price subscription * ACTUAL: There is an actual price * PARTIAL: There is a reduced set of price levels * UNAVAILABLE: There is actually no price * ERROR: No price available. The subscription failed
»»» update_ts	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»»» merged	boolean	false	If true the update contains merged data. If false or not present the update has not been merged
»»» first_ts	timestamp_type	false	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»»» levels	[object]	false	The levels element is only present when the instrument exists and the price source is active. Otherwise the error field will be filled with an error message explaining what is wrong.
»»»» Level	object	false	none
»»»»» quantity	quantity_type	true	The quantity of a leg.
»»»»» buy_price	price_type	false	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
»»»»» sell_price	price_type	false	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades
status	ACTUAL
status	PARTIAL
status	UNAVAILABLE
status	ERROR

Response Heartbeat

Name	Type	Required	Description
» heartbeat	object	true	none
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades

Response Subscription Confirmation

Name	Type	Required	Description
» channel_subscription_confirmation	object	true	Message received when the user is successfully subscribed to a channel.
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» status	channel_status_type	true	Status of the websocket channel
»» heartbeat_interval	heartbeat_interval_type	true	This optional field defines if the tradias server sends heartbeat messages to the channel or not. The value specifies the interval of the heartbeat messages in seconds. The maximum is 600 seconds (10 minutes). A value of 0 switches the heartbeat message generation off. Zero is the default which means by default there are no heartbeat messages.

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades
status	ACTIVE
status	CLOSED

Response Subscription Failed

Name	Type	Required	Description
» channel_subscription_error	object	true	Message received when the subscription to a channel has failed
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» error	error_type	true	All error codes returned by this API have a unique code, classifying the error messages.
»» error_text	error_text_type	false	Text describing the Error

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades
error	Unauthorized
error	InternalServerError
error	Conflict
error	UnprocessableEntity
error	DuplicateReq
error	InvalidOrder
error	MixedOrders
error	InvalidAmount
error	AmountTooLow
error	AmountTooAccurate
error	AmountTooHigh
error	NoPriceStream
error	RiskCheck
error	DuplicateOrderRef
error	NotFound
error	Forbidden
error	ValidationError

Response Subscription Rejection

Name	Type	Required	Description
» price_subscription_error	object	true	Message received when a price subscription failed an is rejected.
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» rejection_list	[object]	true	Array containing a list of rejected subscriptions
»»» subscription_id	subscription_id_type	true	This field is set by the API user. It’s serves the purpose of identifying the instrument price subscription, it is not unique.
»»» instrument	instrument_type	true	Identifier for an instrument. It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]
»»» error	error_text_type	true	Text describing the Error

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades

Response 403

Name	Type	Required	Description
» reject_message	object	true	A message through the WebSocket that gives information on a rejected request and the reason of rejection.
»» rejection_reason	rejection_reason_type	true	Message used to describe the reason that a request gets rejected.
»» rejection_text	rejection_text_type	true	Message used to explain the reason that a request gets rejected.
»» request_ref	request_ref_type	true	Reference used to refer to a request that was done.
»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”

Code samples

import websockets
import asyncio
import json

MY_TOKEN = "ENTER YOUR TOKEN HERE"
ENVIRONMENT = "preprod"
PROTOCOL = "wss"

URI = f"{PROTOCOL}://ws.{ENVIRONMENT}.tradias.link/ws/prices"

websocket_headers = {
    "Authorization": "Bearer " + MY_TOKEN
}

price_channel_subscription = {
    "subscribe_price_channel": {
        "channel": "prices",
        "heartbeat_interval": 30
    }}

instruments_list = [
    {
        "subscription_id": "XX-4567",
        "instrument": "BTC-EUR/SP",
        "max_frequency": 500
    },
    {
        "subscription_id": "TS-BTC",
        "instrument": "BTC-EUR/SP",
        "mergeable": False,
        "max_pending": 100
    },
    {
        "subscription_id": "XX-4549",
        "instrument": "ETH-EUR/SP",
        "max_frequency": 500
    },
    {
        "subscription_id": "TS-ETH",
        "instrument": "ETH-EUR/SP",
        "mergeable": False
    }
]

async def get_prices(instruments: list[dict]) -> None:
    async with websockets.connect(uri=URI, extra_headers=websocket_headers) as websocket:
        await websocket.send(json.dumps(price_channel_subscription))
        await websocket.send(json.dumps(
            {
                "subscribe_instruments": {
                    "channel": "prices",
                    "subscriptions": instruments_list
                }
            }))
        while True:
            print(await websocket.recv())

asyncio.run(get_prices(instruments=instruments_list))

PUB /ws/prices

Quantity: 1
- Buy price: 0.0018
- Sell price: 0.0016
Quantity: 5
- Buy price: 0.0086
- Sell price: 0.0084
Quantity: 10
- Buy price: 0.0174
- Sell price: 0.0169

The number of price levels in the production environment can differ to that in the testing environment.
It can occur that there is only one-sided quoting available for an instrument (e.g., in case a coin gets delisted). In this case, prices don’t include both the sell_price and buy_price keys. For example: {“quantity”:“0.00002”,“sell_price”:“33698.32”}.

A subscription to instrument prices through the price channel can be terminated using the message shown on the right.

  # Message to unsubscribe from instrument prices
  {
    "unsubscribe_instruments": {
      "channel": "prices",
      "subscription_ids": [
        "XX-4567",
        "TS-BTC",
        "XX-4549",
        "TS-ETH"
      ]
    }
  }

Body parameter

{
  "subscribe_instruments": {
    "channel": "prices",
    "subscriptions": [
      {
        "subscription_id": "XX-4567",
        "instrument": "BTC-EUR/SP",
        "max_frequency": 500
      },
      {
        "subscription_id": "TS-BTC",
        "instrument": "BTC-EUR/SP",
        "mergeable": false,
        "max_pending": 100
      },
      {
        "subscription_id": "XX-4549",
        "instrument": "ETH-EUR/SP",
        "max_frequency": 500
      },
      {
        "subscription_id": "TS-ETH",
        "instrument": "ETH-EUR/SP",
        "mergeable": false
      }
    ]
  }
}

Name	In	Type	Required
body	body	SubscribeInstruments	false
» subscribe_instruments	body	object	true
»» channel	body	channel_type	true
»» subscriptions	body	[object]	true
»»» Subscription	body	object	false
»»»» subscription_id	body	subscription_id_type	true
»»»» instrument	body	instrument_type	true
»»»» mergeable	body	boolean	false
»»»» max_frequency	body	integer	false
»»»» max_pending	body	integer	false

Detailed descriptions

»»»» instrument: Identifier for an instrument.
It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]

Enumerated Values

Parameter	Value
»» channel	orders
»» channel	prices
»» channel	trades

Example responses

Price Update Response

{
  "price_update": {
    "header": {
      "channel": "prices",
      "timestamp": "1970-01-01T00:08:00.000000Z"
    },
    "update_list": [
      {
        "subscription_id": "TS-BTC",
        "instrument": "BTC-EUR/SP",
        "status": "ACTUAL",
        "update_ts": "1970-01-01T00:07:58.973000Z",
        "levels": [
          {
            "quantity": "1.25867895",
            "buy_price": "23768.69386464",
            "sell_price": "23767.67893759"
          }
        ]
      },
      {
        "subscription_id": "TS-BTC",
        "instrument": "BTC-EUR/SP",
        "status": "ACTUAL",
        "update_ts": "1970-01-01T00:07:59.657000Z",
        "levels": [
          {
            "quantity": "1.25867895",
            "buy_price": "23768.63953056",
            "sell_price": "23767.23953056"
          }
        ]
      },
      {
        "subscription_id": "XX-4567",
        "instrument": "BTC-EUR/SP",
        "status": "ACTUAL",
        "merged": true,
        "first_ts": "1970-01-01T00:07:58.973000Z",
        "update_ts": "1970-01-01T00:07:59.657000Z",
        "levels": [
          {
            "quantity": "1.25867895",
            "buy_price": "23768.63953056",
            "sell_price": "23767.23953056"
          }
        ]
      }
    ]
  }
}

Status	Description
Price Update	Asynchronous price update message send by the server to the API user. A price update is a list of updates for different subscriptions. An update is sent for an subscription for each new status or price.
Heartbeat	Asynchronous heart beat message sent by the server to the subscriber
Subscription Confirmation	Confirmation of a Channel Subscription
Subscription Failed	Channel Subscription has failed, channel can’t be used
Subscription Rejection	Rejection of a Price Subscription
403	Message received when a new_order can not be executed

Response Price Update

Name	Type	Required	Description
» price_update	object	true	none
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» update_list	[object]	true	Array containing a list of updates for a subscription
»»» subscription_id	subscription_id_type	true	This field is set by the API user. It’s serves the purpose of identifying the instrument price subscription, it is not unique.
»»» instrument	instrument_type	true	Identifier for an instrument. It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]
»»» status	price_status_type	false	The status of a price subscription * ACTUAL: There is an actual price * PARTIAL: There is a reduced set of price levels * UNAVAILABLE: There is actually no price * ERROR: No price available. The subscription failed
»»» update_ts	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»»» merged	boolean	false	If true the update contains merged data. If false or not present the update has not been merged
»»» first_ts	timestamp_type	false	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»»» levels	[object]	false	The levels element is only present when the instrument exists and the price source is active. Otherwise the error field will be filled with an error message explaining what is wrong.
»»»» Level	object	false	none
»»»»» quantity	quantity_type	true	The quantity of a leg.
»»»»» buy_price	price_type	false	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
»»»»» sell_price	price_type	false	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades
status	ACTUAL
status	PARTIAL
status	UNAVAILABLE
status	ERROR

Response Heartbeat

Name	Type	Required	Description
» heartbeat	object	true	none
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades

Response Subscription Confirmation

Name	Type	Required	Description
» channel_subscription_confirmation	object	true	Message received when the user is successfully subscribed to a channel.
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» status	channel_status_type	true	Status of the websocket channel
»» heartbeat_interval	heartbeat_interval_type	true	This optional field defines if the tradias server sends heartbeat messages to the channel or not. The value specifies the interval of the heartbeat messages in seconds. The maximum is 600 seconds (10 minutes). A value of 0 switches the heartbeat message generation off. Zero is the default which means by default there are no heartbeat messages.

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades
status	ACTIVE
status	CLOSED

Response Subscription Failed

Name	Type	Required	Description
» channel_subscription_error	object	true	Message received when the subscription to a channel has failed
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» error	error_type	true	All error codes returned by this API have a unique code, classifying the error messages.
»» error_text	error_text_type	false	Text describing the Error

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades
error	Unauthorized
error	InternalServerError
error	Conflict
error	UnprocessableEntity
error	DuplicateReq
error	InvalidOrder
error	MixedOrders
error	InvalidAmount
error	AmountTooLow
error	AmountTooAccurate
error	AmountTooHigh
error	NoPriceStream
error	RiskCheck
error	DuplicateOrderRef
error	NotFound
error	Forbidden
error	ValidationError

Response Subscription Rejection

Name	Type	Required	Description
» price_subscription_error	object	true	Message received when a price subscription failed an is rejected.
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» rejection_list	[object]	true	Array containing a list of rejected subscriptions
»»» subscription_id	subscription_id_type	true	This field is set by the API user. It’s serves the purpose of identifying the instrument price subscription, it is not unique.
»»» instrument	instrument_type	true	Identifier for an instrument. It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]
»»» error	error_text_type	true	Text describing the Error

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades

Response 403

Name	Type	Required	Description
» reject_message	object	true	A message through the WebSocket that gives information on a rejected request and the reason of rejection.
»» rejection_reason	rejection_reason_type	true	Message used to describe the reason that a request gets rejected.
»» rejection_text	rejection_text_type	true	Message used to explain the reason that a request gets rejected.
»» request_ref	request_ref_type	true	Reference used to refer to a request that was done.
»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”

Trading

This section consists of endpoints that can be used for trading. The trading flow is relatively simple - if you want to trade, you place an order. Orders are either executed in full or rejected entirely, partial fills cannot occur when trading against tradias. o Regularly monitoring the collateral and trading line usage is recommended to avoid trading halts or liquidations (see: Risk Figures).

The endpoints in this section are:

Orders (WebSocket)
Trades (WebSocket)
Bulk Orders (REST)
Risk Figures (REST)

Placing an order can be done in two ways, either through the orders channel (WebSocket) or via a Bulk Order (REST). The method of choice depends on the use-case and desired execution parameters.

An order sent through the WebSocket is most suited for a continuous order flow, where each order is executed individually. In the case orders should be booked as several individual orders but executed as one big order, a bulk order can be used, where the bulk order contains many child orders (e.g. for savings plans, portfolio rebalancing).

Note: all orders are executed as Fill or Kill (FoK) orders, i.e. executed completely immediately or are rejected. Long-lived limit orders are currently not supported. More information on the implementation of limit orders can be found in the Orders endpoint section.

Responses to the order submission contain the relevant information about the execution or rejection thereof. These responses are sent through the same channel as was used to submit the order, both for the WebSocket and REST endpoints. Order rejections contain information about the rejection reasons, whereas order executions contain the information about the associated trade(s), including execution price, first and second leg amounts and timestamp.

Retrospectively, this information can be recovered through the Historic Data endpoints.

(Un)Subscribe Order Channel

Code samples

import asyncio
import json
import websockets

ENVIRONMENT = "preprod"
PROTOCOL = "WSS"
URL = f"{PROTOCOL}://ws.{ENVIRONMENT}.tradias.link/ws/orders"
MY_TOKEN = "ENTER YOUR TOKEN HERE"

ws_headers = {
    "Authorization": "Bearer " + MY_TOKEN
}

my_order = {
    "new_order": {
        "order_ref": "c8d16891-b669-11ed-bc43-f1002b6e6125",
        "req_header": {
            "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
            "user_data": [
                {
                    "tag": "Correlation-Id",
                    "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
                },
                {
                    "tag": "TX-Id",
                    "value": "18955457"
                }
            ]
        },
        "order_type": "LIMIT",
        "time_in_force": "FOK",
        "instrument": "BTC-EUR/SP",
        "side": "BUY",
        "amount": {
            "leg_2_amount": "50000"
        },
        "limit_price": "24570"
    }
}

async def place_order(order):
    async with websockets.connect(uri=URL, extra_headers=ws_headers) as websocket:
        await websocket.send(json.dumps({
            "subscribe_order_channel":
                {
                    "channel": "orders",
                    "heartbeat_interval": 30
                }
        }))
        await websocket.send(json.dumps(order))
        while True:
            message = await websocket.recv()
            print(message)

asyncio.run(place_order(order=my_order))

PUB /ws/orders

It is possible to place both market orders and limit orders via our API. The implementation of limit orders is restricted in the sense that we only allow FOK/IOC (Fill or Kill/Immediate or Cancel) orders.

Types of Orders:

Market Order: in a market order the API user has to specify the instrument, quantity and side (buy or sell). Execution of market orders is done immediately and the execution price is the newest price for the corresponding instrument, quantity and side.
Limit Order: in a limit order the API user additionally specifies a price at which they are willing to buy or sell. Next to this, the user has to specify a parameter in the time_in_force field, which is either "FOK" or "IOC". Our current implementation of limit orders is restricted to FOK/IOC orders. This means that limit orders are not kept in an order book, they are either executed immediately or canceled immediately, depending on the parameters in the order request.
- Immediate or Cancel (IOC) and Fill or Kill (FOK): when placing a limit order, the API user has to enter either "IOC" or "FOK" in the time_in_force field. The order will either be executed or rejected immediately. The order is accepted when:
  - limit_pice >= latest_price, and the order is a buy order;
  - limit_price <= latest_price, and the order is a sell order.

In all other cases the limit order will be rejected immediately. In case of an execution, the limit order is executed at the latest price update, not the limit price. This means that executions are always done at a price that is the same or better than the specified limit_price. Note that there is no difference in how “FOK” or “IOC” limit orders are handled.

A subscription to the orders channel can be terminated using the message shown on the right.

# Message to unsubscribe from orders channel
{
  "unsubscribe_channel": {
    "channel": "orders"
  }
}

Body parameter

{
  "subscribe_order_channel": {
    "channel": "orders",
    "heartbeat_interval": 30
  }
}

Name	In	Type	Required
body	body	SubscribeOrderChannel	false
» subscribe_order_channel	body	object	true
»» channel	body	channel_type	true
»» heartbeat_interval	body	heartbeat_interval_type	false

Enumerated Values

Parameter	Value
»» channel	orders
»» channel	prices
»» channel	trades

Example responses

Order Execution Response

{
  "order_execution": {
    "header": {
      "channel": "orders",
      "timestamp": "1970-01-01T00:00:00.000000Z"
    },
    "order_id": "6aa21c20-ae4b-11ed-b304-81a12bb57b04",
    "order_ref": "c8d16891-b669-11ed-bc43-f1002b6e6125",
    "req_header": {
      "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
      "user_data": [
        {
          "tag": "Correlation-Id",
          "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
        },
        {
          "tag": "TX-Id",
          "value": "18955457"
        }
      ]
    },
    "order_type": "LIMIT",
    "time_in_force": "FOK",
    "instrument": "BTC-EUR/SP",
    "side": "BUY",
    "amount": {
      "leg_2_amount": "50000"
    },
    "limit_price": "24570",
    "order_status": "DONE",
    "leg_1_executed_amount": "2.02814908",
    "leg_2_executed_amount": "50000",
    "execution_price": "24653.020129"
  }
}

Status	Description
Order Execution	Report the execution of an order sent earlier
Heartbeat	Asynchronous heart beat message sent by the server to the subscriber
Subscription Confirmation	Confirmation of a Channel Subscription
Order Rejection	Message received when a new_order can not be executed
Subscription Failed	Channel Subscription has failed, channel can’t be used
403	Message received when a new_order can not be executed

Response Order Execution

Name	Type	Required	Description
» order_execution	object	true	Message received when a new_order sent by the API user gets executed.
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» trade_id	internal_ref_type	false	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»» order_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»» order_ref	external_ref_type	true	This field is used by the API user to pass an reference or ID to the tradias system which is used in the tradias system to to act as an reference or ID to the transaction in the API users system.
»» req_header	req_header_type	false	This request header is part of any request creating or modifying an object (order, bulk-order, settlement, …). It consists of two parts, a request ID which will be checked on the tradias side for uniqueness, and an array of user data (tag value). Both parts are option as the complete request header is. The request ID can be used by the API user to allow, that if a request does not answer properly, to sent the request again. If the first one has been processed, then the second one will be rejected with a 409 error and the API user knows that the first request has been processed. If the first request did not make it the second one will be processed normally. The second part is an array of values tagged by a short tag. This data provided by the API user will be returned with the response of the request and if a possible will be added to the object the request relates to and later returned with all responses relating to the object.
»»» req_id	unique_req_type	false	The unique request ID is generated by the API user, it has to be a UUID. It is used to detect that a request has already been processed. If the unique request ID has already been used then the request will not be executed. Instead an error will be (DuplicateReq) reported.
»»» user_data	[object]	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.
»»»» tag	string	true	none
»»»» value	string	true	none
»» order_type	order_type_type	true	There are different order types. Currently only the following order types are supported * MARKET: This is a order (without limit). * LIMIT: This is a order with a limit. Buy orders are only executed if the execution price is lower or equal than the limit price. Sell orders are only executed if the execution price is higher or equal than the limit price. * BULK_MARKET: This is a list order where multiple orders are entered as a single bulk. The bulk is either executed completely or not at all.
»» time_in_force	time_in_force_type	true	This order attribute defines the duration a order is active. * FOK: Fill Or Kill is an order which is either completely executed immediately or will be canceled/rejected. * IOC: Immediately Or Cancel is an order which is either executed immediately or will be canceled/rejected. The difference to FOK is that IOC allows partial executions. As tradias always executes completely there is no difference in FOK and IOC orders.
»» instrument	instrument_type	true	Identifier for an instrument. It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]
»» side	side_type	true	The side of the order, seen from the perspective of the API user. * BUY The user sending the order is buying assets * SELL The user sending the order is selling his assets
»» amount	order_amount_type	true	You can specify the amount of an instrument to buy or sell either in the leg_1 or in the leg_2 quantity. If you for example want to buy BTC-EUR you can either define the amount to buy in BTC by specifying the leg_1_amount, or you can specify the amount to spend in EUR by defining the leg_2_amount. Only one of the two legs can be used for a single order!
»»» leg_1_amount	quantity_type	false	The quantity of a leg.
»»» leg_2_amount	quantity_type	false	The quantity of a leg.
»» limit_price	price_type	false	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
»» order_status	order_status_type	true	Orders have a live cycle. The state an order is in that live cycle expressed by its state. The above values are states an order can have in its live cycle. Initially the order is RECEIVED. DUPLICATE, REJECTED, EXPIRED, CANCELLED and DONE are terminal states which will not change any more. UNSPECIFIED means the state is unknown.
»» leg_1_executed_amount	quantity_type	true	The quantity of a leg.
»» leg_2_executed_amount	quantity_type	true	The quantity of a leg.
»» execution_price	price_type	true	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
»» counter_leg_precision	counter_leg_precision_type	false	This optional key can be given in a new order request. The value specifies the number of decimals you want the computed amount of the leg that is not yet specified in the order request to be rounded to. For example, if you give the amount you want to buy/sell in the leg 2 asset, the counter_leg_precision specifies the number of decimals you want the leg 1 amount to be rounded to. Vice versa, if you specify the amount to buy/sell in the leg 1 asset, the amount in the leg 2 asset will be rounded to the specified number in the counter_leg_precision field.

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades
order_type	MARKET
order_type	LIMIT
order_type	BULK_MARKET
time_in_force	FOK
time_in_force	IOC
side	BUY
side	SELL
order_status	UNSPECIFIED
order_status	RECEIVED
order_status	CONFIRMED
order_status	DUPLICATE
order_status	REJECTED
order_status	OPEN
order_status	UPDATED
order_status	CANCELLED
order_status	EXPIRED
order_status	DONE

Response Heartbeat

Name	Type	Required	Description
» heartbeat	object	true	none
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades

Response Subscription Confirmation

Name	Type	Required	Description
» channel_subscription_confirmation	object	true	Message received when the user is successfully subscribed to a channel.
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» status	channel_status_type	true	Status of the websocket channel
»» heartbeat_interval	heartbeat_interval_type	true	This optional field defines if the tradias server sends heartbeat messages to the channel or not. The value specifies the interval of the heartbeat messages in seconds. The maximum is 600 seconds (10 minutes). A value of 0 switches the heartbeat message generation off. Zero is the default which means by default there are no heartbeat messages.

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades
status	ACTIVE
status	CLOSED

Response Order Rejection

Name	Type	Required	Description
» order_status	object	true	Message received when a new_order can not be executed
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» order_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»» order_ref	external_ref_type	true	This field is used by the API user to pass an reference or ID to the tradias system which is used in the tradias system to to act as an reference or ID to the transaction in the API users system.
»» req_header	req_header_type	false	This request header is part of any request creating or modifying an object (order, bulk-order, settlement, …). It consists of two parts, a request ID which will be checked on the tradias side for uniqueness, and an array of user data (tag value). Both parts are option as the complete request header is. The request ID can be used by the API user to allow, that if a request does not answer properly, to sent the request again. If the first one has been processed, then the second one will be rejected with a 409 error and the API user knows that the first request has been processed. If the first request did not make it the second one will be processed normally. The second part is an array of values tagged by a short tag. This data provided by the API user will be returned with the response of the request and if a possible will be added to the object the request relates to and later returned with all responses relating to the object.
»»» req_id	unique_req_type	false	The unique request ID is generated by the API user, it has to be a UUID. It is used to detect that a request has already been processed. If the unique request ID has already been used then the request will not be executed. Instead an error will be (DuplicateReq) reported.
»»» user_data	[object]	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.
»»»» tag	string	true	none
»»»» value	string	true	none
»» order_type	order_type_type	true	There are different order types. Currently only the following order types are supported * MARKET: This is a order (without limit). * LIMIT: This is a order with a limit. Buy orders are only executed if the execution price is lower or equal than the limit price. Sell orders are only executed if the execution price is higher or equal than the limit price. * BULK_MARKET: This is a list order where multiple orders are entered as a single bulk. The bulk is either executed completely or not at all.
»» time_in_force	time_in_force_type	false	This order attribute defines the duration a order is active. * FOK: Fill Or Kill is an order which is either completely executed immediately or will be canceled/rejected. * IOC: Immediately Or Cancel is an order which is either executed immediately or will be canceled/rejected. The difference to FOK is that IOC allows partial executions. As tradias always executes completely there is no difference in FOK and IOC orders.
»» instrument	instrument_type	true	Identifier for an instrument. It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]
»» side	side_type	true	The side of the order, seen from the perspective of the API user. * BUY The user sending the order is buying assets * SELL The user sending the order is selling his assets
»» amount	order_amount_type	true	You can specify the amount of an instrument to buy or sell either in the leg_1 or in the leg_2 quantity. If you for example want to buy BTC-EUR you can either define the amount to buy in BTC by specifying the leg_1_amount, or you can specify the amount to spend in EUR by defining the leg_2_amount. Only one of the two legs can be used for a single order!
»»» leg_1_amount	quantity_type	false	The quantity of a leg.
»»» leg_2_amount	quantity_type	false	The quantity of a leg.
»» limit_price	price_type	false	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
»» order_status	order_status_type	true	Orders have a live cycle. The state an order is in that live cycle expressed by its state. The above values are states an order can have in its live cycle. Initially the order is RECEIVED. DUPLICATE, REJECTED, EXPIRED, CANCELLED and DONE are terminal states which will not change any more. UNSPECIFIED means the state is unknown.
»» rejection_reason	rejection_reason_type	true	Message used to describe the reason that a request gets rejected.
»» rejection_text	rejection_text_type	true	Message used to explain the reason that a request gets rejected.

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades
order_type	MARKET
order_type	LIMIT
order_type	BULK_MARKET
time_in_force	FOK
time_in_force	IOC
side	BUY
side	SELL
order_status	UNSPECIFIED
order_status	RECEIVED
order_status	CONFIRMED
order_status	DUPLICATE
order_status	REJECTED
order_status	OPEN
order_status	UPDATED
order_status	CANCELLED
order_status	EXPIRED
order_status	DONE

Response Subscription Failed

Name	Type	Required	Description
» channel_subscription_error	object	true	Message received when the subscription to a channel has failed
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» error	error_type	true	All error codes returned by this API have a unique code, classifying the error messages.
»» error_text	error_text_type	false	Text describing the Error

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades
error	Unauthorized
error	InternalServerError
error	Conflict
error	UnprocessableEntity
error	DuplicateReq
error	InvalidOrder
error	MixedOrders
error	InvalidAmount
error	AmountTooLow
error	AmountTooAccurate
error	AmountTooHigh
error	NoPriceStream
error	RiskCheck
error	DuplicateOrderRef
error	NotFound
error	Forbidden
error	ValidationError

Response 403

Name	Type	Required	Description
» reject_message	object	true	A message through the WebSocket that gives information on a rejected request and the reason of rejection.
»» rejection_reason	rejection_reason_type	true	Message used to describe the reason that a request gets rejected.
»» rejection_text	rejection_text_type	true	Message used to explain the reason that a request gets rejected.
»» request_ref	request_ref_type	true	Reference used to refer to a request that was done.
»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”

New Order through Order Channel

Code samples

import asyncio
import json
import websockets

ENVIRONMENT = "preprod"
PROTOCOL = "WSS"
URL = f"{PROTOCOL}://ws.{ENVIRONMENT}.tradias.link/ws/orders"
MY_TOKEN = "ENTER YOUR TOKEN HERE"

ws_headers = {
    "Authorization": "Bearer " + MY_TOKEN
}

my_order = {
    "new_order": {
        "order_ref": "c8d16891-b669-11ed-bc43-f1002b6e6125",
        "req_header": {
            "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
            "user_data": [
                {
                    "tag": "Correlation-Id",
                    "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
                },
                {
                    "tag": "TX-Id",
                    "value": "18955457"
                }
            ]
        },
        "order_type": "LIMIT",
        "time_in_force": "FOK",
        "instrument": "BTC-EUR/SP",
        "side": "BUY",
        "amount": {
            "leg_2_amount": "50000"
        },
        "limit_price": "24570"
    }
}

async def place_order(order):
    async with websockets.connect(uri=URL, extra_headers=ws_headers) as websocket:
        await websocket.send(json.dumps({
            "subscribe_order_channel":
                {
                    "channel": "orders",
                    "heartbeat_interval": 30
                }
        }))
        await websocket.send(json.dumps(order))
        while True:
            message = await websocket.recv()
            print(message)

asyncio.run(place_order(order=my_order))

PUB /ws/orders

An order is a request for buying or selling a specific asset. Order requests always specify the trading pair, quantity, and side at which the trader is willing to transact. For limit orders, the price should also be given.

It is possible to place both market orders and limit orders via our API. The implementation of limit orders is restricted in the sense that we only allow FOK/IOC (Fill or Kill/Immediate or cancel) orders.

Types of Orders:

Market Order: in a market order the API user at least specifies the instrument, quantity and side (buy or sell). Execution of market orders is done immediately and the execution price is the newest price for the corresponding instrument, quantity and side.
Limit Order: in a limit order the API user additionally specifies a price at which they are willing to buy or sell. Next to this, the user has to specify a parameter in the time_in_force field, which is either “FOK” or “IOC”. Our current implementation of limit orders is restricted to FOK/IOC orders. This means that limit orders are not kept in an order book, they are either executed immediately or canceled immediately, depending on the parameters in the order request.
- Immediate or Cancel (IOC) and Fill or Kill (FOK): when placing a limit order, the API user has to enter either “IOC” or “FOK” in the time_in_force field. The order will either be executed or rejected immediately. The order is accepted when:
  - limit_pice >= latest_price, and the order is a buy order;
  - limit_price <= latest_price, and the order is a sell order.
In all other cases the limit order will be rejected immediately. In case of an execution, the limit order is executed at the latest price update, not the limit price. This means that executions are always done at a price that is the same or better than the specified limit_price. Note that there is no difference in how “FOK” or “IOC” limit orders are handled.

Body parameter

{
  "new_order": {
    "order_ref": "c8d16891-b669-11ed-bc43-f1002b6e6125",
    "req_header": {
      "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
      "user_data": [
        {
          "tag": "Correlation-Id",
          "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
        },
        {
          "tag": "TX-Id",
          "value": "18955457"
        }
      ]
    },
    "order_type": "LIMIT",
    "time_in_force": "FOK",
    "instrument": "BTC-EUR/SP",
    "side": "BUY",
    "amount": {
      "leg_2_amount": "50000"
    },
    "limit_price": "24570"
  }
}

Parameters

Name	In	Type	Required
body	body	NewOrder	false
» new_order	body	object	true
»» order_ref	body	external_ref_type	true
»» req_header	body	req_header_type	false
»»» req_id	body	unique_req_type	false
»»» user_data	body	[object]	false
»»»» tag	body	string	true
»»»» value	body	string	true
»» order_type	body	order_type_type	true
»» time_in_force	body	time_in_force_type	false
»» instrument	body	instrument_type	true
»» side	body	side_type	true
»» amount	body	order_amount_type	true
»»» leg_1_amount	body	quantity_type	false
»»» leg_2_amount	body	quantity_type	false
»» limit_price	body	price_type	false
»» counter_leg_precision	body	counter_leg_precision_type	false

Detailed descriptions

»» order_type: There are different order types. Currently only the following order types are supported

MARKET: This is a order (without limit).
LIMIT: This is a order with a limit. Buy orders are only executed if the execution price is lower or equal than the limit price. Sell orders are only executed if the execution price is higher or equal than the limit price.
BULK_MARKET: This is a list order where multiple orders are entered as a single bulk. The bulk is either executed completely or not at all.

»» time_in_force: This order attribute defines the duration a order is active.

FOK: Fill Or Kill is an order which is either completely executed immediately or will be canceled/rejected.
IOC: Immediately Or Cancel is an order which is either executed immediately or will be canceled/rejected. The difference to FOK is that IOC allows partial executions. As tradias always executes completely there is no difference in FOK and IOC orders.

»» instrument: Identifier for an instrument.
It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]

»» side: The side of the order, seen from the perspective of the API user.

BUY The user sending the order is buying assets
SELL The user sending the order is selling his assets

Enumerated Values

Parameter	Value
»» order_type	MARKET
»» order_type	LIMIT
»» order_type	BULK_MARKET
»» time_in_force	FOK
»» time_in_force	IOC
»» side	BUY
»» side	SELL

Example responses

Order Execution Response

{
  "order_execution": {
    "header": {
      "channel": "orders",
      "timestamp": "1970-01-01T00:00:00.000000Z"
    },
    "order_id": "6aa21c20-ae4b-11ed-b304-81a12bb57b04",
    "order_ref": "c8d16891-b669-11ed-bc43-f1002b6e6125",
    "req_header": {
      "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
      "user_data": [
        {
          "tag": "Correlation-Id",
          "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
        },
        {
          "tag": "TX-Id",
          "value": "18955457"
        }
      ]
    },
    "order_type": "LIMIT",
    "time_in_force": "FOK",
    "instrument": "BTC-EUR/SP",
    "side": "BUY",
    "amount": {
      "leg_2_amount": "50000"
    },
    "limit_price": "24570",
    "order_status": "DONE",
    "leg_1_executed_amount": "2.02814908",
    "leg_2_executed_amount": "50000",
    "execution_price": "24653.020129"
  }
}

Responses

Status	Description
Order Execution	Report the execution of an order sent earlier
Heartbeat	Asynchronous heart beat message sent by the server to the subscriber
Subscription Confirmation	Confirmation of a Channel Subscription
Order Rejection	Message received when a new_order can not be executed
Subscription Failed	Channel Subscription has failed, channel can’t be used
403	Message received when a new_order can not be executed

Response Schema

Response Order Execution

Name	Type	Required	Description
» order_execution	object	true	Message received when a new_order sent by the API user gets executed.
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» trade_id	internal_ref_type	false	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»» order_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»» order_ref	external_ref_type	true	This field is used by the API user to pass an reference or ID to the tradias system which is used in the tradias system to to act as an reference or ID to the transaction in the API users system.
»» req_header	req_header_type	false	This request header is part of any request creating or modifying an object (order, bulk-order, settlement, …). It consists of two parts, a request ID which will be checked on the tradias side for uniqueness, and an array of user data (tag value). Both parts are option as the complete request header is. The request ID can be used by the API user to allow, that if a request does not answer properly, to sent the request again. If the first one has been processed, then the second one will be rejected with a 409 error and the API user knows that the first request has been processed. If the first request did not make it the second one will be processed normally. The second part is an array of values tagged by a short tag. This data provided by the API user will be returned with the response of the request and if a possible will be added to the object the request relates to and later returned with all responses relating to the object.
»»» req_id	unique_req_type	false	The unique request ID is generated by the API user, it has to be a UUID. It is used to detect that a request has already been processed. If the unique request ID has already been used then the request will not be executed. Instead an error will be (DuplicateReq) reported.
»»» user_data	[object]	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.
»»»» tag	string	true	none
»»»» value	string	true	none
»» order_type	order_type_type	true	There are different order types. Currently only the following order types are supported * MARKET: This is a order (without limit). * LIMIT: This is a order with a limit. Buy orders are only executed if the execution price is lower or equal than the limit price. Sell orders are only executed if the execution price is higher or equal than the limit price. * BULK_MARKET: This is a list order where multiple orders are entered as a single bulk. The bulk is either executed completely or not at all.
»» time_in_force	time_in_force_type	true	This order attribute defines the duration a order is active. * FOK: Fill Or Kill is an order which is either completely executed immediately or will be canceled/rejected. * IOC: Immediately Or Cancel is an order which is either executed immediately or will be canceled/rejected. The difference to FOK is that IOC allows partial executions. As tradias always executes completely there is no difference in FOK and IOC orders.
»» instrument	instrument_type	true	Identifier for an instrument. It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]
»» side	side_type	true	The side of the order, seen from the perspective of the API user. * BUY The user sending the order is buying assets * SELL The user sending the order is selling his assets
»» amount	order_amount_type	true	You can specify the amount of an instrument to buy or sell either in the leg_1 or in the leg_2 quantity. If you for example want to buy BTC-EUR you can either define the amount to buy in BTC by specifying the leg_1_amount, or you can specify the amount to spend in EUR by defining the leg_2_amount. Only one of the two legs can be used for a single order!
»»» leg_1_amount	quantity_type	false	The quantity of a leg.
»»» leg_2_amount	quantity_type	false	The quantity of a leg.
»» limit_price	price_type	false	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
»» order_status	order_status_type	true	Orders have a live cycle. The state an order is in that live cycle expressed by its state. The above values are states an order can have in its live cycle. Initially the order is RECEIVED. DUPLICATE, REJECTED, EXPIRED, CANCELLED and DONE are terminal states which will not change any more. UNSPECIFIED means the state is unknown.
»» leg_1_executed_amount	quantity_type	true	The quantity of a leg.
»» leg_2_executed_amount	quantity_type	true	The quantity of a leg.
»» execution_price	price_type	true	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
»» counter_leg_precision	counter_leg_precision_type	false	This optional key can be given in a new order request. The value specifies the number of decimals you want the computed amount of the leg that is not yet specified in the order request to be rounded to. For example, if you give the amount you want to buy/sell in the leg 2 asset, the counter_leg_precision specifies the number of decimals you want the leg 1 amount to be rounded to. Vice versa, if you specify the amount to buy/sell in the leg 1 asset, the amount in the leg 2 asset will be rounded to the specified number in the counter_leg_precision field.

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades
order_type	MARKET
order_type	LIMIT
order_type	BULK_MARKET
time_in_force	FOK
time_in_force	IOC
side	BUY
side	SELL
order_status	UNSPECIFIED
order_status	RECEIVED
order_status	CONFIRMED
order_status	DUPLICATE
order_status	REJECTED
order_status	OPEN
order_status	UPDATED
order_status	CANCELLED
order_status	EXPIRED
order_status	DONE

Response Heartbeat

Name	Type	Required	Description
» heartbeat	object	true	none
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades

Response Subscription Confirmation

Name	Type	Required	Description
» channel_subscription_confirmation	object	true	Message received when the user is successfully subscribed to a channel.
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» status	channel_status_type	true	Status of the websocket channel
»» heartbeat_interval	heartbeat_interval_type	true	This optional field defines if the tradias server sends heartbeat messages to the channel or not. The value specifies the interval of the heartbeat messages in seconds. The maximum is 600 seconds (10 minutes). A value of 0 switches the heartbeat message generation off. Zero is the default which means by default there are no heartbeat messages.

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades
status	ACTIVE
status	CLOSED

Response Order Rejection

Name	Type	Required	Description
» order_status	object	true	Message received when a new_order can not be executed
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» order_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»» order_ref	external_ref_type	true	This field is used by the API user to pass an reference or ID to the tradias system which is used in the tradias system to to act as an reference or ID to the transaction in the API users system.
»» req_header	req_header_type	false	This request header is part of any request creating or modifying an object (order, bulk-order, settlement, …). It consists of two parts, a request ID which will be checked on the tradias side for uniqueness, and an array of user data (tag value). Both parts are option as the complete request header is. The request ID can be used by the API user to allow, that if a request does not answer properly, to sent the request again. If the first one has been processed, then the second one will be rejected with a 409 error and the API user knows that the first request has been processed. If the first request did not make it the second one will be processed normally. The second part is an array of values tagged by a short tag. This data provided by the API user will be returned with the response of the request and if a possible will be added to the object the request relates to and later returned with all responses relating to the object.
»»» req_id	unique_req_type	false	The unique request ID is generated by the API user, it has to be a UUID. It is used to detect that a request has already been processed. If the unique request ID has already been used then the request will not be executed. Instead an error will be (DuplicateReq) reported.
»»» user_data	[object]	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.
»»»» tag	string	true	none
»»»» value	string	true	none
»» order_type	order_type_type	true	There are different order types. Currently only the following order types are supported * MARKET: This is a order (without limit). * LIMIT: This is a order with a limit. Buy orders are only executed if the execution price is lower or equal than the limit price. Sell orders are only executed if the execution price is higher or equal than the limit price. * BULK_MARKET: This is a list order where multiple orders are entered as a single bulk. The bulk is either executed completely or not at all.
»» time_in_force	time_in_force_type	false	This order attribute defines the duration a order is active. * FOK: Fill Or Kill is an order which is either completely executed immediately or will be canceled/rejected. * IOC: Immediately Or Cancel is an order which is either executed immediately or will be canceled/rejected. The difference to FOK is that IOC allows partial executions. As tradias always executes completely there is no difference in FOK and IOC orders.
»» instrument	instrument_type	true	Identifier for an instrument. It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]
»» side	side_type	true	The side of the order, seen from the perspective of the API user. * BUY The user sending the order is buying assets * SELL The user sending the order is selling his assets
»» amount	order_amount_type	true	You can specify the amount of an instrument to buy or sell either in the leg_1 or in the leg_2 quantity. If you for example want to buy BTC-EUR you can either define the amount to buy in BTC by specifying the leg_1_amount, or you can specify the amount to spend in EUR by defining the leg_2_amount. Only one of the two legs can be used for a single order!
»»» leg_1_amount	quantity_type	false	The quantity of a leg.
»»» leg_2_amount	quantity_type	false	The quantity of a leg.
»» limit_price	price_type	false	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
»» order_status	order_status_type	true	Orders have a live cycle. The state an order is in that live cycle expressed by its state. The above values are states an order can have in its live cycle. Initially the order is RECEIVED. DUPLICATE, REJECTED, EXPIRED, CANCELLED and DONE are terminal states which will not change any more. UNSPECIFIED means the state is unknown.
»» rejection_reason	rejection_reason_type	true	Message used to describe the reason that a request gets rejected.
»» rejection_text	rejection_text_type	true	Message used to explain the reason that a request gets rejected.

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades
order_type	MARKET
order_type	LIMIT
order_type	BULK_MARKET
time_in_force	FOK
time_in_force	IOC
side	BUY
side	SELL
order_status	UNSPECIFIED
order_status	RECEIVED
order_status	CONFIRMED
order_status	DUPLICATE
order_status	REJECTED
order_status	OPEN
order_status	UPDATED
order_status	CANCELLED
order_status	EXPIRED
order_status	DONE

Response Subscription Failed

Name	Type	Required	Description
» channel_subscription_error	object	true	Message received when the subscription to a channel has failed
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» error	error_type	true	All error codes returned by this API have a unique code, classifying the error messages.
»» error_text	error_text_type	false	Text describing the Error

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades
error	Unauthorized
error	InternalServerError
error	Conflict
error	UnprocessableEntity
error	DuplicateReq
error	InvalidOrder
error	MixedOrders
error	InvalidAmount
error	AmountTooLow
error	AmountTooAccurate
error	AmountTooHigh
error	NoPriceStream
error	RiskCheck
error	DuplicateOrderRef
error	NotFound
error	Forbidden
error	ValidationError

Response 403

Name	Type	Required	Description
» reject_message	object	true	A message through the WebSocket that gives information on a rejected request and the reason of rejection.
»» rejection_reason	rejection_reason_type	true	Message used to describe the reason that a request gets rejected.
»» rejection_text	rejection_text_type	true	Message used to explain the reason that a request gets rejected.
»» request_ref	request_ref_type	true	Reference used to refer to a request that was done.
»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”

New Bulk Order

Code samples

import requests
import json

PROTOCOL = "https"
ENVIRONMENT = "preprod"
MY_TOKEN = "ENTER YOUR TOKEN HERE"

URL = f"{PROTOCOL}://api.{ENVIRONMENT}.tradias.link/api/orders/bulk"
payload = {
    "req_header": {
        "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
        "user_data": [
            {
                "tag": "Correlation-Id",
                "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
            },
            {
                "tag": "TX-Id",
                "value": "18955457"
            }
        ]
    },
    "order_type": "BULK_MARKET",
    "orders": [
        {
            "order_ref": "18955839",
            "instrument": "BTC-EUR/SP",
            "side": "BUY",
            "amount": {
                "leg_1_amount": "2.5"
            },
            "user_data": [
                {
                    "tag": "Correlation-Id",
                    "value": "7ac33648-ae4b-11ed-b2f9-81a12bb57b04"
                },
                {
                    "tag": "TX-Id",
                    "value": "18955839"
                }
            ]
        },
        {
            "order_ref": "18958204",
            "instrument": "ETH-EUR/SP",
            "side": "BUY",
            "amount": {
                "leg_2_amount": "20000"
            },
            "user_data": [
                {
                    "tag": "Correlation-Id",
                    "value": "888d205a-ae4b-11ed-9362-81a12bb57b04"
                },
                {
                    "tag": "TX-Id",
                    "value": "18958204"
                }
            ]
        }
    ]
}
rest_api_header = {
    "Authorization": "Bearer " + MY_TOKEN
}

bulk_order_request = requests.post(url=URL, headers=rest_api_header, json=payload)

print(json.dumps(bulk_order_request.json(), indent=4))

POST /api/orders/bulk

If you want to place multiple orders at once, you can use the Bulk Order endpoint. In the request to the New Bulk Order endpoints, you can send many orders (up to 9999 orders) at once. The format of the orders in a bulk order, hereafter referred to as ‘child orders’, is the same as the format of an order that is sent to the WebSocket orders endpoint. The child orders of the bulk order will all be visible individually in the Order History. The trades originating from orders in a bulk order are all visible in the Trade History. However, the orders are not communicated as messages on the Orders WebSocket channel nor are the executions of bulk orders communicated over the Trades WebSocket channel. After a new bulk order has been created it can be inquired either by the Get Bulk Order or by the Bulk Order Status endpoints.

For example, bulk orders fit the following applications:

Executions of large amounts of orders for end-customers, where all customers must be executed at the exact same price and timestamp, yet booked individually for each customer
Rebalancing of portfolios, without breaking risk limits when shorting one asset to go long in another.
Executing basket purchases by known percentages of a predetermined investment amount

The working of a bulk order is summarized by the following steps:

The timestamp of receipt is stored along with the prices of all instruments within the bulk order.
The aggregation of all amounts over any particular instrument and side is determined.
The execution price is determined based on the aggregated amounts of the previous step.
The risk check is applied based on the resulting change of exposure.
If the risk check passes, the order is executed. The orders and corresponding executions can be viewed.

More details on the working of bulk orders can be found below:

Price: the price of orders in a bulk order is computed based on the price at the time of receipt. Note that the price is determined on the depth of the aggregated amount per instrument per side, not on the amount per child order in order to ensure that all orders for the same instrument and the same side will be executed on the same price. Also note that opposite sides are not ‘netted’ when the depth of the price is determined.

Example: suppose that up to 15 BTC, the buy price equals 27000 and from 15 to 50 BTC the buy price equals 27100. Suppose the following three orders are sent in one bulk order:
- {“order_ref”: 1, “instrument”: “BTC-EUR”, “side”: “BUY”, “amount”: {“leg_1_amount”: “10”}}
- {“order_ref”: 2, “instrument”: “BTC-EUR”, “side”: “BUY”, “amount”: {“leg_1_amount”: “20”}}
- {“order_ref”: 3, “instrument”: “BTC-EUR”, “side”: “SELL”, “amount”: {“leg_1_amount”: “20”}}
Since the price for the two ‘BUY’ orders is determined based on the aggregated amount of all ‘BUY’ orders for BTC-EUR, the price of the orders with reference 1 and 2 gets executed at a market depth of 20+10=30. Hence the first and second order will be executed at a price of 27100.
Computation of risk limits: unlike the case where all orders are submitted separately through the WebSocket, the risk check in the bulk order is applied on the change in exposure of the entire bulk order, as opposed to the risk check being applied to the change in exposure for each child order individually. This means that per instrument, the resulting exposure change in euro is computed, which is subsequently used for the computation of the risk limits.

Example: suppose that an order of 10 BTC would breach your risk limits. Posting a bulk order with the following child orders, the bulk order would be rejected as its execution would breach the risk limits:
- {“order_ref”: 1, “instrument”: “BTC-EUR”, “side”: “BUY”, “amount”: {“leg_1_amount”: “7”}}
- {“order_ref”: 2, “instrument”: “BTC-EUR”, “side”: “BUY”, “amount”: {“leg_1_amount”: “4”}}
Example: suppose that an order of 10 BTC would breach your risk limits. Posting a bulk order with the following orders, the bulk order would not be rejected since the aggregated amount does not cause a breach of the risk limits:
- {“order_ref”: 1, “instrument”: “BTC-EUR”, “side”: “BUY”, “amount”: {“leg_1_amount”: “12”}}
- {“order_ref”: 2, “instrument”: “BTC-EUR”, “side”: “SELL”, “amount”: {“leg_1_amount”: “4”}}
Valid orders: the child orders in a bulk order do not all need to have the same instruments, same sides and use the same asset for specifying the quantity of the order. However, for any particular combination of side and instrument in a bulk order, only the leg_1_amount or leg_2_amount field can be used.

Example: suppose that you send a bulk order consisting of the following orders:
- {“order_ref”: 1, “instrument”: “ETH-EUR”, “side”: “BUY”, “amount”: {“leg_1_amount”: “101”}}
- {“order_ref”: 2, “instrument”: “ETH-EUR”, “side”: “SELL”, “amount”: {“leg_2_amount”: “9000”}}
- {“order_ref”: 3, “instrument”: “ADA-EUR”, “side”: “SELL”, “amount” {“leg_2_amount”: “1500”}}
This is a valid format and the bulk order will go through.

Example: suppose that you send a bulk order consisting of the following orders:
- {“order_ref”: 1, “instrument”: “ETH-EUR”, “side”: “BUY”, “amount”: {“leg_1_amount”: “101”}}
- {“order_ref”: 2, “instrument”: “ETH-EUR”, “side”: “BUY”, “amount” {“leg_2_amount”: “1500”}}
This is not a valid format since for a specific combination of instrument and side, there is an order containing the “leg_1_amount” key and there is another order with the same instrument and same side that contains the “leg_2_amount” key. The bulk order will not go through.
Other functionalities:
- Bulk orders are designed to be atomic, meaning that either all orders in the bulk orders are executed or none.
- The “req_id” in the “req_header” can be used for its idempotency property, if required.

Body parameter

{
  "new_bulk_order": {
    "req_header": {
      "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
      "user_data": [
        {
          "tag": "Correlation-Id",
          "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
        },
        {
          "tag": "TX-Id",
          "value": "18955457"
        }
      ]
    },
    "order_type": "BULK_MARKET",
    "orders": [
      {
        "order_ref": "18955839",
        "instrument": "BTC-EUR/SP",
        "side": "BUY",
        "amount": {
          "leg_1_amount": "2.5"
        },
        "user_data": [
          {
            "tag": "Correlation-Id",
            "value": "7ac33648-ae4b-11ed-b2f9-81a12bb57b04"
          },
          {
            "tag": "TX-Id",
            "value": "18955839"
          }
        ]
      },
      {
        "order_ref": "18958204",
        "instrument": "ETH-EUR/SP",
        "side": "BUY",
        "amount": {
          "leg_2_amount": "20000"
        },
        "user_data": [
          {
            "tag": "Correlation-Id",
            "value": "888d205a-ae4b-11ed-9362-81a12bb57b04"
          },
          {
            "tag": "TX-Id",
            "value": "18958204"
          }
        ]
      }
    ]
  }
}

Parameters

Name	In	Type	Required
body	body	object	false
» new_bulk_order	body	object	true
»» req_header	body	req_header_type	false
»»» req_id	body	unique_req_type	false
»»» user_data	body	[object]	false
»»»» tag	body	string	true
»»»» value	body	string	true
»» order_type	body	order_type_type	true
»» orders	body	[market_order_type]	true
»»» Market Order Data	body	market_order_type	false
»»»» order_ref	body	external_ref_type	true
»»»» instrument	body	instrument_type	true
»»»» side	body	side_type	true
»»»» amount	body	order_amount_type	true
»»»»» leg_1_amount	body	quantity_type	false
»»»»» leg_2_amount	body	quantity_type	false
»»»» user_data	body	[object]	false
»»»» counter_leg_precision	body	counter_leg_precision_type	false

Detailed descriptions

»» order_type: There are different order types. Currently only the following order types are supported

MARKET: This is a order (without limit).
LIMIT: This is a order with a limit. Buy orders are only executed if the execution price is lower or equal than the limit price. Sell orders are only executed if the execution price is higher or equal than the limit price.
BULK_MARKET: This is a list order where multiple orders are entered as a single bulk. The bulk is either executed completely or not at all.

»»»» instrument: Identifier for an instrument.
It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]

»»»» side: The side of the order, seen from the perspective of the API user.

BUY The user sending the order is buying assets
SELL The user sending the order is selling his assets

Enumerated Values

Parameter	Value
»» order_type	MARKET
»» order_type	LIMIT
»» order_type	BULK_MARKET
»»»» side	BUY
»»»» side	SELL

Example responses

202 Response

{
  "new_bulk_order_response": {
    "bulk_order_id": "6aa21c20-ae4b-11ed-b304-81a12bb57b04",
    "bulk_order_status": "RECEIVED",
    "req_header": {
      "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
      "user_data": [
        {
          "tag": "Correlation-Id",
          "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
        },
        {
          "tag": "TX-Id",
          "value": "18955457"
        }
      ]
    },
    "timestamp": "2023-01-20T14:31:10.012123Z"
  }
}

401 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "Unauthorized",
    "error_text": "The JWT token could not be validated"
  }
}

409 Response

{
  "error_req_header": {
    "req_header": {
      "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
      "user_data": [
        {
          "tag": "Correlation-Id",
          "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
        },
        {
          "tag": "TX-Id",
          "value": "18955457"
        }
      ]
    },
    "tradias_id": "75ccdf76-ae4b-11ed-85ee-81a12bb57b04",
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "DuplicateReq",
    "error_text": "The req_id has been already processed"
  }
}

422 Response

{
  "new_bulk_order_error_response": {
    "bulk_order_id": "6c51119a-ae4b-11ed-b75a-81a12bb57b04",
    "bulk_order_status": "REJECTED",
    "req_header": {
      "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
      "user_data": [
        {
          "tag": "Correlation-Id",
          "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
        },
        {
          "tag": "TX-Id",
          "value": "18955457"
        }
      ]
    },
    "bulk_order_submitted_at": "2023-01-20T14:31:09.012123Z",
    "rejected_order": {
      "order_ref": "18955839",
      "instrument": "BTC-EUR/SP",
      "side": "BUY",
      "amount": {
        "leg_1_amount": "2.5"
      },
      "user_data": [
        {
          "tag": "Correlation-Id",
          "value": "7ac33648-ae4b-11ed-b2f9-81a12bb57b04"
        },
        {
          "tag": "TX-Id",
          "value": "18955839"
        }
      ]
    },
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "RiskCheck",
    "error_text": "The bulk order could not be executed because the resulting margin usage would be too high."
  }
}

500 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "InternalServerError",
    "error_text": "Internal Server Error: the server can currently not process the request"
  }
}

Responses

Status	Meaning	Description	Schema
202	Accepted	Accepted	Inline
401	Unauthorized	Unauthorized	internal_error_type
409	Conflict	Duplicate Request	internal_req_error_type
422	Unprocessable Entity	Bulk Order Error	Inline
500	Internal Server Error	Internal Server Error	internal_error_type

Response Schema

Status Code 202

Name	Type	Required	Description
» new_bulk_order_response	object	true	none
»» bulk_order_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»» bulk_order_status	bulk_order_status_type	true	The status of a new bulk order is RECEIVED. BULK_MARKET orders will be executed immediately an becomes then either REJECTED if it could not be executed or DONE if it got executed.
»» req_header	req_header_type	false	This request header is part of any request creating or modifying an object (order, bulk-order, settlement, …). It consists of two parts, a request ID which will be checked on the tradias side for uniqueness, and an array of user data (tag value). Both parts are option as the complete request header is. The request ID can be used by the API user to allow, that if a request does not answer properly, to sent the request again. If the first one has been processed, then the second one will be rejected with a 409 error and the API user knows that the first request has been processed. If the first request did not make it the second one will be processed normally. The second part is an array of values tagged by a short tag. This data provided by the API user will be returned with the response of the request and if a possible will be added to the object the request relates to and later returned with all responses relating to the object.
»»» req_id	unique_req_type	false	The unique request ID is generated by the API user, it has to be a UUID. It is used to detect that a request has already been processed. If the unique request ID has already been used then the request will not be executed. Instead an error will be (DuplicateReq) reported.
»»» user_data	[object]	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.
»»»» tag	string	true	none
»»»» value	string	true	none
»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”

Enumerated Values

Property	Value
bulk_order_status	RECEIVED
bulk_order_status	REJECTED
bulk_order_status	DONE

Status Code 422

Name	Type	Required	Description
» new_bulk_order_error_response	object	true	none
»» bulk_order_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»» bulk_order_status	bulk_order_status_type	true	The status of a new bulk order is RECEIVED. BULK_MARKET orders will be executed immediately an becomes then either REJECTED if it could not be executed or DONE if it got executed.
»» req_header	req_header_type	false	This request header is part of any request creating or modifying an object (order, bulk-order, settlement, …). It consists of two parts, a request ID which will be checked on the tradias side for uniqueness, and an array of user data (tag value). Both parts are option as the complete request header is. The request ID can be used by the API user to allow, that if a request does not answer properly, to sent the request again. If the first one has been processed, then the second one will be rejected with a 409 error and the API user knows that the first request has been processed. If the first request did not make it the second one will be processed normally. The second part is an array of values tagged by a short tag. This data provided by the API user will be returned with the response of the request and if a possible will be added to the object the request relates to and later returned with all responses relating to the object.
»»» req_id	unique_req_type	false	The unique request ID is generated by the API user, it has to be a UUID. It is used to detect that a request has already been processed. If the unique request ID has already been used then the request will not be executed. Instead an error will be (DuplicateReq) reported.
»»» user_data	[object]	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.
»»»» tag	string	true	none
»»»» value	string	true	none
»» bulk_order_submitted_at	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» rejected_order	market_order_type	true	This schema represents all information needed for an MARKET order
»»» order_ref	external_ref_type	true	This field is used by the API user to pass an reference or ID to the tradias system which is used in the tradias system to to act as an reference or ID to the transaction in the API users system.
»»» instrument	instrument_type	true	Identifier for an instrument. It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]
»»» side	side_type	true	The side of the order, seen from the perspective of the API user. * BUY The user sending the order is buying assets * SELL The user sending the order is selling his assets
»»» amount	order_amount_type	true	You can specify the amount of an instrument to buy or sell either in the leg_1 or in the leg_2 quantity. If you for example want to buy BTC-EUR you can either define the amount to buy in BTC by specifying the leg_1_amount, or you can specify the amount to spend in EUR by defining the leg_2_amount. Only one of the two legs can be used for a single order!
»»»» leg_1_amount	quantity_type	false	The quantity of a leg.
»»»» leg_2_amount	quantity_type	false	The quantity of a leg.
»»» user_data	[object]	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.
»»» counter_leg_precision	counter_leg_precision_type	false	This optional key can be given in a new order request. The value specifies the number of decimals you want the computed amount of the leg that is not yet specified in the order request to be rounded to. For example, if you give the amount you want to buy/sell in the leg 2 asset, the counter_leg_precision specifies the number of decimals you want the leg 1 amount to be rounded to. Vice versa, if you specify the amount to buy/sell in the leg 1 asset, the amount in the leg 2 asset will be rounded to the specified number in the counter_leg_precision field.
»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» error	error_type	true	All error codes returned by this API have a unique code, classifying the error messages.
»» error_text	error_text_type	true	Text describing the Error

Enumerated Values

Property	Value
bulk_order_status	RECEIVED
bulk_order_status	REJECTED
bulk_order_status	DONE
side	BUY
side	SELL
error	Unauthorized
error	InternalServerError
error	Conflict
error	UnprocessableEntity
error	DuplicateReq
error	InvalidOrder
error	MixedOrders
error	InvalidAmount
error	AmountTooLow
error	AmountTooAccurate
error	AmountTooHigh
error	NoPriceStream
error	RiskCheck
error	DuplicateOrderRef
error	NotFound
error	Forbidden
error	ValidationError

Get Bulk Order

Code samples

import requests
import json

PROTOCOL = "https"
ENVIRONMENT = "preprod"
MY_TOKEN = "ENTER YOUR TOKEN HERE"

URL = f"{PROTOCOL}://api.{ENVIRONMENT}.tradias.link/api/orders/bulk/6aa21c20-ae4b-11ed-b304-81a12bb57b04"

rest_api_header = {
  "Authorization": "Bearer " + MY_TOKEN
}

bulk_order_request = requests.get(url=URL, headers=rest_api_header)

print(json.dumps(bulk_order_request.json(), indent=4))

GET /api/orders/bulk/{bulk_order_id}

The Get Bulk Order endpoint allows the retrieval of all details regarding a specific bulk order. This includes the order status, timestamp as well as the details on the execution for all child orders and associated trades, if applicable.

As bulk orders are processed asynchronously, the information on a specific bulk order is only accessible after the processing is complete. In order to determine the status of the completion of the bulk order processing as well as the success of its execution, the Get Bulk Order Status endpoint can be used.

Parameters

Name	In	Type	Required
bulk_order_id	path	internal_ref_type	true

Example responses

200 Response

{
  "get_bulk_order_response": {
    "bulk_order_id": "6aa21c20-ae4b-11ed-b304-81a12bb57b04",
    "bulk_order_status": "RECEIVED",
    "req_header": {
      "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
      "user_data": [
        {
          "tag": "Correlation-Id",
          "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
        },
        {
          "tag": "TX-Id",
          "value": "18955457"
        }
      ]
    },
    "bulk_order_submitted_at": "1970-01-01T00:00:00.000000Z",
    "timestamp": "1970-01-01T00:00:00.000000Z",
    "error": "NotFound",
    "error_text": "The bulk order with the given ID could not be found.",
    "executions": [
      {
        "order": {
          "order_ref": "18955839",
          "instrument": "BTC-EUR/SP",
          "side": "BUY",
          "amount": {
            "leg_1_amount": "2.5"
          },
          "user_data": [
            {
              "tag": "Correlation-Id",
              "value": "7ac33648-ae4b-11ed-b2f9-81a12bb57b04"
            },
            {
              "tag": "TX-Id",
              "value": "18955839"
            }
          ]
        },
        "order_type": "BULK_MARKET",
        "time_in_force": "FOK",
        "order_status": "DONE",
        "leg_1_executed_amount": "1.25867895",
        "leg_2_executed_amount": "1.25867895",
        "execution_price": "23768.63953056",
        "trade_ids": [
          "6aa21c20-ae4b-11ed-b304-81a12bb57b04"
        ],
        "executed_at": "1970-01-01T00:00:00.000000Z"
      }
    ]
  }
}

401 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "Unauthorized",
    "error_text": "The JWT token could not be validated"
  }
}

404 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "NotFound",
    "error_text": "The given object (Order, Trade, ...) could not be found."
  }
}

422 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "ValidationError",
    "error_text": "The request is not valid"
  }
}

500 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "InternalServerError",
    "error_text": "Internal Server Error: the server can currently not process the request"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Get Bulk Order	Inline
401	Unauthorized	Unauthorized	internal_error_type
404	Not Found	Not Found	internal_error_type
422	Unprocessable Entity	Unprocessable Request	internal_error_type
500	Internal Server Error	Internal Server Error	internal_error_type

Response Schema

Status Code 200

Name	Type	Required	Description
» get_bulk_order_response	object	true	none
»» bulk_order_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»» bulk_order_status	bulk_order_status_type	true	The status of a new bulk order is RECEIVED. BULK_MARKET orders will be executed immediately an becomes then either REJECTED if it could not be executed or DONE if it got executed.
»» req_header	req_header_type	false	This request header is part of any request creating or modifying an object (order, bulk-order, settlement, …). It consists of two parts, a request ID which will be checked on the tradias side for uniqueness, and an array of user data (tag value). Both parts are option as the complete request header is. The request ID can be used by the API user to allow, that if a request does not answer properly, to sent the request again. If the first one has been processed, then the second one will be rejected with a 409 error and the API user knows that the first request has been processed. If the first request did not make it the second one will be processed normally. The second part is an array of values tagged by a short tag. This data provided by the API user will be returned with the response of the request and if a possible will be added to the object the request relates to and later returned with all responses relating to the object.
»»» req_id	unique_req_type	false	The unique request ID is generated by the API user, it has to be a UUID. It is used to detect that a request has already been processed. If the unique request ID has already been used then the request will not be executed. Instead an error will be (DuplicateReq) reported.
»»» user_data	[object]	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.
»»»» tag	string	true	none
»»»» value	string	true	none
»» bulk_order_submitted_at	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» error	error_type	false	All error codes returned by this API have a unique code, classifying the error messages.
»» error_text	error_text_type	false	Text describing the Error
»» executions	[bulk_execution_type]	true	none
»»» Bulk Order Execution	bulk_execution_type	false	none
»»»» order	market_order_type	true	This schema represents all information needed for an MARKET order
»»»»» order_ref	external_ref_type	true	This field is used by the API user to pass an reference or ID to the tradias system which is used in the tradias system to to act as an reference or ID to the transaction in the API users system.
»»»»» instrument	instrument_type	true	Identifier for an instrument. It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]
»»»»» side	side_type	true	The side of the order, seen from the perspective of the API user. * BUY The user sending the order is buying assets * SELL The user sending the order is selling his assets
»»»»» amount	order_amount_type	true	You can specify the amount of an instrument to buy or sell either in the leg_1 or in the leg_2 quantity. If you for example want to buy BTC-EUR you can either define the amount to buy in BTC by specifying the leg_1_amount, or you can specify the amount to spend in EUR by defining the leg_2_amount. Only one of the two legs can be used for a single order!
»»»»»» leg_1_amount	quantity_type	false	The quantity of a leg.
»»»»»» leg_2_amount	quantity_type	false	The quantity of a leg.
»»»»» user_data	[object]	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.
»»»»» counter_leg_precision	counter_leg_precision_type	false	This optional key can be given in a new order request. The value specifies the number of decimals you want the computed amount of the leg that is not yet specified in the order request to be rounded to. For example, if you give the amount you want to buy/sell in the leg 2 asset, the counter_leg_precision specifies the number of decimals you want the leg 1 amount to be rounded to. Vice versa, if you specify the amount to buy/sell in the leg 1 asset, the amount in the leg 2 asset will be rounded to the specified number in the counter_leg_precision field.
»»»» order_type	order_type_type	true	There are different order types. Currently only the following order types are supported * MARKET: This is a order (without limit). * LIMIT: This is a order with a limit. Buy orders are only executed if the execution price is lower or equal than the limit price. Sell orders are only executed if the execution price is higher or equal than the limit price. * BULK_MARKET: This is a list order where multiple orders are entered as a single bulk. The bulk is either executed completely or not at all.
»»»» time_in_force	time_in_force_type	true	This order attribute defines the duration a order is active. * FOK: Fill Or Kill is an order which is either completely executed immediately or will be canceled/rejected. * IOC: Immediately Or Cancel is an order which is either executed immediately or will be canceled/rejected. The difference to FOK is that IOC allows partial executions. As tradias always executes completely there is no difference in FOK and IOC orders.
»»»» order_status	order_status_type	true	Orders have a live cycle. The state an order is in that live cycle expressed by its state. The above values are states an order can have in its live cycle. Initially the order is RECEIVED. DUPLICATE, REJECTED, EXPIRED, CANCELLED and DONE are terminal states which will not change any more. UNSPECIFIED means the state is unknown.
»»»» leg_1_executed_amount	quantity_type	true	The quantity of a leg.
»»»» leg_2_executed_amount	quantity_type	true	The quantity of a leg.
»»»» execution_price	price_type	true	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
»»»» trade_ids	[internal_ref_type]	false	[This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).]
»»»»» Internal Reference or Id	internal_ref_type	false	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»»»» executed_at	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”

Enumerated Values

Property	Value
bulk_order_status	RECEIVED
bulk_order_status	REJECTED
bulk_order_status	DONE
error	Unauthorized
error	InternalServerError
error	Conflict
error	UnprocessableEntity
error	DuplicateReq
error	InvalidOrder
error	MixedOrders
error	InvalidAmount
error	AmountTooLow
error	AmountTooAccurate
error	AmountTooHigh
error	NoPriceStream
error	RiskCheck
error	DuplicateOrderRef
error	NotFound
error	Forbidden
error	ValidationError
side	BUY
side	SELL
order_type	MARKET
order_type	LIMIT
order_type	BULK_MARKET
time_in_force	FOK
time_in_force	IOC
order_status	UNSPECIFIED
order_status	RECEIVED
order_status	CONFIRMED
order_status	DUPLICATE
order_status	REJECTED
order_status	OPEN
order_status	UPDATED
order_status	CANCELLED
order_status	EXPIRED
order_status	DONE

Bulk Order Status

Code samples

import requests
import json

PROTOCOL = "https"
ENVIRONMENT = "preprod"
MY_TOKEN = "ENTER YOUR TOKEN HERE"

URL = f"{PROTOCOL}://api.{ENVIRONMENT}.tradias.link/api/orders/bulk/6aa21c20-ae4b-11ed-b304-81a12bb57b04/status"

rest_api_header = {
  "Authorization": "Bearer " + MY_TOKEN
}

bulk_order_status_request = requests.get(url=URL, headers=rest_api_header)

print(json.dumps(bulk_order_status_request.json(), indent=4))

GET /api/orders/bulk/{bulk_order_id}/status

The Bulk Order Status endpoint can be queried using the bulk_order_id as returned in the response of the New Bulk Order endpoint. The endpoint serves as a shorter version of the Get Bulk Order endpoint allows checking on the processing state of a bulk order.

In particular, the endpoint returns the status of the bulk order, which is either ‘DONE’, meaning it was executed, ‘REJECTED’, meaning that it cannot be processed and executed due to an error, or ‘RECEIVED’, which means that it is being processed. Additionally, the endpoint returns the request ID and the user data as passed in the request to the New Bulk Order endpoint.

Both the Get Bulk Order and Get Bulk Order Status endpoints return information on the bulk orders that were posted. Generally, the Get Bulk Order Status endpoint is more useful when you are polling the state of a bulk order, as its response is more compact compared to the Get Bulk Order endpoint response. In contrast, the Get Bulk Order endpoint returns detailed information about the bulk order and its associated child orders.

Parameters

Name	In	Type	Required
bulk_order_id	path	internal_ref_type	true

Example responses

200 Response

{
  "bulk_order_status_response": {
    "bulk_order_id": "6aa21c20-ae4b-11ed-b304-81a12bb57b04",
    "bulk_order_status": "RECEIVED",
    "req_header": {
      "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
      "user_data": [
        {
          "tag": "Correlation-Id",
          "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
        },
        {
          "tag": "TX-Id",
          "value": "18955457"
        }
      ]
    },
    "timestamp": "2023-01-20T14:31:10.012123Z"
  }
}

401 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "Unauthorized",
    "error_text": "The JWT token could not be validated"
  }
}

404 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "NotFound",
    "error_text": "The given object (Order, Trade, ...) could not be found."
  }
}

422 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "ValidationError",
    "error_text": "The request is not valid"
  }
}

500 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "InternalServerError",
    "error_text": "Internal Server Error: the server can currently not process the request"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Bulk Order Status	Inline
401	Unauthorized	Unauthorized	internal_error_type
404	Not Found	Not Found	internal_error_type
422	Unprocessable Entity	Unprocessable Request	internal_error_type
500	Internal Server Error	Internal Server Error	internal_error_type

Response Schema

Status Code 200

Name	Type	Required	Description
» bulk_order_status_response	object	true	none
»» bulk_order_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»» bulk_order_status	bulk_order_status_type	true	The status of a new bulk order is RECEIVED. BULK_MARKET orders will be executed immediately an becomes then either REJECTED if it could not be executed or DONE if it got executed.
»» req_header	req_header_type	false	This request header is part of any request creating or modifying an object (order, bulk-order, settlement, …). It consists of two parts, a request ID which will be checked on the tradias side for uniqueness, and an array of user data (tag value). Both parts are option as the complete request header is. The request ID can be used by the API user to allow, that if a request does not answer properly, to sent the request again. If the first one has been processed, then the second one will be rejected with a 409 error and the API user knows that the first request has been processed. If the first request did not make it the second one will be processed normally. The second part is an array of values tagged by a short tag. This data provided by the API user will be returned with the response of the request and if a possible will be added to the object the request relates to and later returned with all responses relating to the object.
»»» req_id	unique_req_type	false	The unique request ID is generated by the API user, it has to be a UUID. It is used to detect that a request has already been processed. If the unique request ID has already been used then the request will not be executed. Instead an error will be (DuplicateReq) reported.
»»» user_data	[object]	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.
»»»» tag	string	true	none
»»»» value	string	true	none
»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”

Enumerated Values

Property	Value
bulk_order_status	RECEIVED
bulk_order_status	REJECTED
bulk_order_status	DONE

Trade Channel (Coming Soon)

Code samples

import asyncio
import json
import websockets

ENVIRONMENT = "preprod"
PROTOCOL = "wss"
ws_url = f"{PROTOCOL}://ws.{ENVIRONMENT}.tradias.link/ws/trades"
MY_TOKEN = "ENTER YOUR TOKEN HERE"

ws_headers = {
    "Authorization": "Bearer " + MY_TOKEN
}

async def trades():
    async with websockets.connect(uri=ws_url, extra_headers=ws_headers) as websocket:
        await websocket.send(json.dumps({
            "subscribe_trade_channel": {
                "channel": "trades",
                "heartbeat_interval": 30,
                "seq_number": 47110815
            }
        }))
        while True:
            message = await websocket.recv()
            print(message)

asyncio.run(trades())

PUB /ws/trades

A trade is an execution of a market or limit order. The trade channel is a WebSocket channel via which an API user can listen to executions or other updates on orders. Whenever an order is executed or cancelled, this is reflected via an update in the trade channel.

This subscription is used to receive trades executed by the API user. In the subscription to the channel, the user can specify sequence numbers or a time stamp which filter which trades will be shown in the channel. If both are not given, the trades that are shown will be all trades starting at the current day. Each trade is reported as a separate message. The last trade from the history is marked with a flag and from then on all trades executed are delivered in real-time.

A subscription to the trades channel can be terminated using the message shown on the right.

  # Message to unsubscribe from trades channel
  {
    "unsubscribe_channel": {
      "channel": "trades"
    }
  }

Body parameter

{
  "subscribe_trade_channel": {
    "channel": "trades",
    "heartbeat_interval": 30,
    "seq_number": 47110815
  }
}

Parameters

Name	In	Type	Required
body	body	SubscribeTradeChannel	false
» subscribe_trade_channel	body	object	true
»» channel	body	channel_type	true
»» heartbeat_interval	body	heartbeat_interval_type	false
»» seq_number	body	sequence_type	false
»» execution_time	body	timestamp_type	false

Enumerated Values

Parameter	Value
»» channel	orders
»» channel	prices
»» channel	trades

Example responses

Subscription Confirmation Response

{
  "channel_subscription_confirmation": {
    "header": {
      "channel": "prices",
      "timestamp": "1970-01-01T00:00:00.000000Z"
    },
    "status": "ACTIVE",
    "heartbeat_interval": 30
  }
}

Responses

Status	Description
Subscription Confirmation	Confirmation of a Channel Subscription
Heartbeat	Asynchronous heart beat message sent by the server to the subscriber
Execution	Message received when a execution happens
Subscription Confirmation	Channel Subscription has failed, channel can’t be used
403	Message received when a new_order can not be executed

Response Schema

Response Subscription Confirmation

Name	Type	Required	Description
» channel_subscription_confirmation	object	true	Message received when the user is successfully subscribed to a channel.
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» status	channel_status_type	true	Status of the websocket channel
»» heartbeat_interval	heartbeat_interval_type	true	This optional field defines if the tradias server sends heartbeat messages to the channel or not. The value specifies the interval of the heartbeat messages in seconds. The maximum is 600 seconds (10 minutes). A value of 0 switches the heartbeat message generation off. Zero is the default which means by default there are no heartbeat messages.

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades
status	ACTIVE
status	CLOSED

Response Heartbeat

Name	Type	Required	Description
» heartbeat	object	true	none
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades

Response Execution

Name	Type	Required	Description
» trade	object	true	none
»» trade_id	internal_ref_type	false	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»» seq_number	sequence_type	false	Sequence number of an order, trade or any other event. A sequence number is assigned to the object (e.g. order) when it is received. All sequence number are unique and increasing. There may be gaps in the sequence numbers assigned! The sequence number can ba used sort objects in the way they have been received/happened. If the maximum is reached the sequence numbers continue with 0.
»» order_id	internal_ref_type	false	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»» order_ref	external_ref_type	false	This field is used by the API user to pass an reference or ID to the tradias system which is used in the tradias system to to act as an reference or ID to the transaction in the API users system.
»» req_header	req_header_type	false	This request header is part of any request creating or modifying an object (order, bulk-order, settlement, …). It consists of two parts, a request ID which will be checked on the tradias side for uniqueness, and an array of user data (tag value). Both parts are option as the complete request header is. The request ID can be used by the API user to allow, that if a request does not answer properly, to sent the request again. If the first one has been processed, then the second one will be rejected with a 409 error and the API user knows that the first request has been processed. If the first request did not make it the second one will be processed normally. The second part is an array of values tagged by a short tag. This data provided by the API user will be returned with the response of the request and if a possible will be added to the object the request relates to and later returned with all responses relating to the object.
»»» req_id	unique_req_type	false	The unique request ID is generated by the API user, it has to be a UUID. It is used to detect that a request has already been processed. If the unique request ID has already been used then the request will not be executed. Instead an error will be (DuplicateReq) reported.
»»» user_data	[object]	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.
»»»» tag	string	true	none
»»»» value	string	true	none
»» order	order_data_type	false	This schema represents all information of an order
»»» instrument	instrument_type	true	Identifier for an instrument. It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]
»»» order_type	order_type_type	true	There are different order types. Currently only the following order types are supported * MARKET: This is a order (without limit). * LIMIT: This is a order with a limit. Buy orders are only executed if the execution price is lower or equal than the limit price. Sell orders are only executed if the execution price is higher or equal than the limit price. * BULK_MARKET: This is a list order where multiple orders are entered as a single bulk. The bulk is either executed completely or not at all.
»»» time_in_force	time_in_force_type	false	This order attribute defines the duration a order is active. * FOK: Fill Or Kill is an order which is either completely executed immediately or will be canceled/rejected. * IOC: Immediately Or Cancel is an order which is either executed immediately or will be canceled/rejected. The difference to FOK is that IOC allows partial executions. As tradias always executes completely there is no difference in FOK and IOC orders.
»»» side	side_type	true	The side of the order, seen from the perspective of the API user. * BUY The user sending the order is buying assets * SELL The user sending the order is selling his assets
»»» amount	order_amount_type	true	You can specify the amount of an instrument to buy or sell either in the leg_1 or in the leg_2 quantity. If you for example want to buy BTC-EUR you can either define the amount to buy in BTC by specifying the leg_1_amount, or you can specify the amount to spend in EUR by defining the leg_2_amount. Only one of the two legs can be used for a single order!
»»»» leg_1_amount	quantity_type	false	The quantity of a leg.
»»»» leg_2_amount	quantity_type	false	The quantity of a leg.
»»» arrived_at	timestamp_type	false	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»»» limit_price	price_type	false	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
»»» order_status	order_status_type	false	Orders have a live cycle. The state an order is in that live cycle expressed by its state. The above values are states an order can have in its live cycle. Initially the order is RECEIVED. DUPLICATE, REJECTED, EXPIRED, CANCELLED and DONE are terminal states which will not change any more. UNSPECIFIED means the state is unknown.
»» trade	trade_type	false	none
»»» leg_1_executed_amount	quantity_type	true	The quantity of a leg.
»»» leg_2_executed_amount	quantity_type	true	The quantity of a leg.
»»» execution_price	price_type	true	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
»»» executed_at	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»»» leg_1_status	trade_leg_status_type	false	none
»»» leg_2_status	trade_leg_status_type	false	none
»» history_done	boolean	false	none
»» counter_leg_precision	counter_leg_precision_type	false	This optional key can be given in a new order request. The value specifies the number of decimals you want the computed amount of the leg that is not yet specified in the order request to be rounded to. For example, if you give the amount you want to buy/sell in the leg 2 asset, the counter_leg_precision specifies the number of decimals you want the leg 1 amount to be rounded to. Vice versa, if you specify the amount to buy/sell in the leg 1 asset, the amount in the leg 2 asset will be rounded to the specified number in the counter_leg_precision field.

Enumerated Values

Property	Value
order_type	MARKET
order_type	LIMIT
order_type	BULK_MARKET
time_in_force	FOK
time_in_force	IOC
side	BUY
side	SELL
order_status	UNSPECIFIED
order_status	RECEIVED
order_status	CONFIRMED
order_status	DUPLICATE
order_status	REJECTED
order_status	OPEN
order_status	UPDATED
order_status	CANCELLED
order_status	EXPIRED
order_status	DONE
leg_1_status	UNSPECIFIED
leg_1_status	PENDING
leg_1_status	SETTLED
leg_2_status	UNSPECIFIED
leg_2_status	PENDING
leg_2_status	SETTLED

Response Subscription Confirmation

Name	Type	Required	Description
» channel_subscription_error	object	true	Message received when the subscription to a channel has failed
»» header	header_type	true	Header used for all websocket messages
»»» channel	channel_type	true	Name of the websocket channel
»»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» error	error_type	true	All error codes returned by this API have a unique code, classifying the error messages.
»» error_text	error_text_type	false	Text describing the Error

Enumerated Values

Property	Value
channel	orders
channel	prices
channel	trades
error	Unauthorized
error	InternalServerError
error	Conflict
error	UnprocessableEntity
error	DuplicateReq
error	InvalidOrder
error	MixedOrders
error	InvalidAmount
error	AmountTooLow
error	AmountTooAccurate
error	AmountTooHigh
error	NoPriceStream
error	RiskCheck
error	DuplicateOrderRef
error	NotFound
error	Forbidden
error	ValidationError

Response 403

Name	Type	Required	Description
» reject_message	object	true	A message through the WebSocket that gives information on a rejected request and the reason of rejection.
»» rejection_reason	rejection_reason_type	true	Message used to describe the reason that a request gets rejected.
»» rejection_text	rejection_text_type	true	Message used to explain the reason that a request gets rejected.
»» request_ref	request_ref_type	true	Reference used to refer to a request that was done.
»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”

Get Risk Figures

Code samples

import requests
import json

PROTOCOL = "https"
ENVIRONMENT = "preprod"
MY_TOKEN = "ENTER YOUR TOKEN HERE"

URL = f"{PROTOCOL}://api.{ENVIRONMENT}.tradias.link/api/v1/riskfigures/report"
rest_api_header = {
  "Authorization": "Bearer " + MY_TOKEN
}

bulk_order_request = requests.get(url=URL, headers=rest_api_header)

print(json.dumps(bulk_order_request.json(), indent=4))

GET /api/v1/riskfigures/report

Trading is facilitated according to risk limits, where a collateral agreement (=margin parameter) is contractually specified. To enable trading, collateral has to be placed with Bankhaus Scheich & tradias, which defines the trading line. Whenever an order execution causes a breach of the risk limits, the order is rejected with a message asking for a collateral increase. In order to avoid such situations, it is recommended to closely monitor the collateral and trading line. This functionality is provided through the Get Risk Figures endpoint.

This exposure is always measured in euro. The field exposure_in_eur contains the exposure of the current unsettled position.

The maximum_allowed_exposure is the highest exposure in euro the trading line allows. The maximum_allowed_exposure is computed using your current collateral and the “margin parameter”.

The margin_usage represents the current utilization of the collateral and trading line (margin_usage = exposure_in_eur / maximum_allowed_exposure). The closer it gets to 1, the closer you are to reaching your risk limits.

The field margin_requirement equals the exposure_in_eur in relation to collateral and trading line, and expresses the amount of collateral currently in use to secure the position (measured in euro).

In order to assure the possibility to keep trading, verify that your trades do not cause the margin_usage to get too close to 1! Trading is halted when the margin_usage > 1.

Example responses

200 Response

{
  "risk_figures_response": {
    "exposure_in_eur": 123456.78,
    "maximum_allowed_exposure": 1000000,
    "margin_requirement": 12345.68,
    "margin_usage": 0.123456
  }
}

401 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "Unauthorized",
    "error_text": "The JWT token could not be validated"
  }
}

422 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "ValidationError",
    "error_text": "The request is not valid"
  }
}

500 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "InternalServerError",
    "error_text": "Internal Server Error: the server can currently not process the request"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Risk Figures Response	Inline
401	Unauthorized	Unauthorized	internal_error_type
422	Unprocessable Entity	Unprocessable Request	internal_error_type
500	Internal Server Error	Internal Server Error	internal_error_type

Response Schema

Status Code 200

Risk Figures Response

Name	Type	Required	Description
» risk_figures_response	object	true	none
»» exposure_in_eur	fiat_amount_type	true	A positive Fiat Currency amount with 15 digits number and 3 digits decimal fraction. It does not allow negative values.
»» maximum_allowed_exposure	fiat_amount_type	true	A positive Fiat Currency amount with 15 digits number and 3 digits decimal fraction. It does not allow negative values.
»» margin_requirement	number	true	The collateral currently in use to secure your exposure.
»» margin_usage	number	true	The usage of your margin as a fraction.

Historic Data

In order to read out the history of your orders and trades, you can call the endpoints in the ‘Historic Data’ section. The section consists of the following endpoints:

Order History
Get Orders By Sequence ID
Trade History
Get Trades By Sequence ID

There are various ways to filter orders and trades, which can be applied in combination. The explanation on how to use the filters is given in the sections describing the endpoints.

Both historic orders and historic trades each have an endpoint for multifunctional filtering as well as an endpoint supporting a sequence ID filtering. You can either find orders or trades. While the multifunctional filtering can be applied when searching specific entries, the filtering by sequence ID’s allows the building (or rebuilding) or the order and trade histories (e.g. for balance computation or reconciliation purposes).

Get Orders

Code samples

import requests
import json

PROTOCOL = "https"
ENVIRONMENT = "preprod"
MY_TOKEN = "ENTER YOUR TOKEN HERE"

URL = f"{PROTOCOL}://api.{ENVIRONMENT}.tradias.link/api/orders

rest_api_header = {
    "Authorization": "Bearer " + MY_TOKEN
}

filter_params = {
    "from_datetime": "2023-10-20T11:20:21.000000Z",
    "to_datetime": "2023-10-20T15:20:21.000000Z",
    "side": "BUY",
    "type": "MARKET"
}

get_orders_request = requests.get(url=URL, headers=rest_api_header, params=filter_params)

print(json.dumps(get_orders_request.json(), indent=4))

GET /api/orders

This endpoint enables highly customizable queries on historic order data. The response from this endpoint is a list of orders that fit the criteria given by the filters that were passed in the request. It is possible to filter for specific values of keys that were passed in the order request, it is also possible to filter by timestamp and to set a limit on the amount of orders returned by the endpoint.

If some orders are not shown due to the limit, the key ‘more’ will take the value true, if not, it will take the value false.

If a complete timeseries of orders is the desired outcome, is is recommended to query not by timestamp, but by sequence number using another endpoint: Get Orders By Sequence ID. The child orders of a bulk order are also visible in from the response of the Get Orders and Get Orders By Sequence ID endpoint.

Parameters

Name	In	Type	Required
from_datetime	query	timestamp_type	true
to_datetime	query	timestamp_type	true
side	query	side_type	false
type	query	order_type_type	false
status	query	order_status_type	false
order_id	query	internal_ref_type	false
order_ref	query	external_ref_type	false
req_id	query	unique_req_type	false
instrument	query	instrument_type	false
limit	query	integer	false
skip	query	integer	false

Enumerated Values

Parameter	Value
side	BUY
side	SELL
type	MARKET
type	LIMIT
type	BULK_MARKET
status	UNSPECIFIED
status	RECEIVED
status	CONFIRMED
status	DUPLICATE
status	REJECTED
status	OPEN
status	UPDATED
status	CANCELLED
status	EXPIRED
status	DONE

Example responses

200 Response

{
  "get_orders_response": {
    "orders": [
      {
        "order_id": "6aa21c20-ae4b-11ed-b304-81a12bb57b04",
        "seq_number": 47110815,
        "order_ref": "18955839",
        "req_header": {
          "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
          "user_data": [
            {
              "tag": "Correlation-Id",
              "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
            },
            {
              "tag": "TX-Id",
              "value": "18955457"
            }
          ]
        },
        "arrived_at": "1970-01-01T00:00:00.000000Z",
        "order": {
          "instrument": "BTC-EUR/SP",
          "order_type": "LIMIT",
          "time_in_force": "FOK",
          "side": "BUY",
          "amount": {
            "leg_1_amount": "2.5"
          },
          "limit_price": "24650",
          "order_status": "DONE"
        },
        "executions": [
          {
            "trade_id": "6aa21c20-ae4b-11ed-b304-81a12bb57b04",
            "leg_1_executed_amount": "1.25867895",
            "leg_2_executed_amount": "1.25867895",
            "execution_price": "23768.63953056",
            "executed_at": "1970-01-01T00:00:00.000000Z",
            "leg_1_status": "PENDING",
            "leg_2_status": "SETTLED"
          }
        ]
      }
    ],
    "more": false
  }
}

401 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "Unauthorized",
    "error_text": "The JWT token could not be validated"
  }
}

404 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "NotFound",
    "error_text": "The given object (Order, Trade, ...) could not be found."
  }
}

422 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "ValidationError",
    "error_text": "The request is not valid"
  }
}

500 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "InternalServerError",
    "error_text": "Internal Server Error: the server can currently not process the request"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Get Orders	Inline
401	Unauthorized	Unauthorized	internal_error_type
404	Not Found	Not Found	internal_error_type
422	Unprocessable Entity	Unprocessable Request	internal_error_type
500	Internal Server Error	Internal Server Error	internal_error_type

Response Schema

Status Code 200

Get Orders Response

Name	Type	Required	Description
» get_orders_response	object	true	none
»» orders	[object]	true	none
»»» Order Details	object	false	none
»»»» order_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»»»» seq_number	sequence_type	true	Sequence number of an order, trade or any other event. A sequence number is assigned to the object (e.g. order) when it is received. All sequence number are unique and increasing. There may be gaps in the sequence numbers assigned! The sequence number can ba used sort objects in the way they have been received/happened. If the maximum is reached the sequence numbers continue with 0.
»»»» order_ref	external_ref_type	false	This field is used by the API user to pass an reference or ID to the tradias system which is used in the tradias system to to act as an reference or ID to the transaction in the API users system.
»»»» req_header	req_header_type	false	This request header is part of any request creating or modifying an object (order, bulk-order, settlement, …). It consists of two parts, a request ID which will be checked on the tradias side for uniqueness, and an array of user data (tag value). Both parts are option as the complete request header is. The request ID can be used by the API user to allow, that if a request does not answer properly, to sent the request again. If the first one has been processed, then the second one will be rejected with a 409 error and the API user knows that the first request has been processed. If the first request did not make it the second one will be processed normally. The second part is an array of values tagged by a short tag. This data provided by the API user will be returned with the response of the request and if a possible will be added to the object the request relates to and later returned with all responses relating to the object.
»»»»» req_id	unique_req_type	false	The unique request ID is generated by the API user, it has to be a UUID. It is used to detect that a request has already been processed. If the unique request ID has already been used then the request will not be executed. Instead an error will be (DuplicateReq) reported.
»»»»» user_data	[object]	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.
»»»»»» tag	string	true	none
»»»»»» value	string	true	none
»»»» arrived_at	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»»»» order	order_data_type	true	This schema represents all information of an order
»»»»» instrument	instrument_type	true	Identifier for an instrument. It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]
»»»»» order_type	order_type_type	true	There are different order types. Currently only the following order types are supported * MARKET: This is a order (without limit). * LIMIT: This is a order with a limit. Buy orders are only executed if the execution price is lower or equal than the limit price. Sell orders are only executed if the execution price is higher or equal than the limit price. * BULK_MARKET: This is a list order where multiple orders are entered as a single bulk. The bulk is either executed completely or not at all.
»»»»» time_in_force	time_in_force_type	false	This order attribute defines the duration a order is active. * FOK: Fill Or Kill is an order which is either completely executed immediately or will be canceled/rejected. * IOC: Immediately Or Cancel is an order which is either executed immediately or will be canceled/rejected. The difference to FOK is that IOC allows partial executions. As tradias always executes completely there is no difference in FOK and IOC orders.
»»»»» side	side_type	true	The side of the order, seen from the perspective of the API user. * BUY The user sending the order is buying assets * SELL The user sending the order is selling his assets
»»»»» amount	order_amount_type	true	You can specify the amount of an instrument to buy or sell either in the leg_1 or in the leg_2 quantity. If you for example want to buy BTC-EUR you can either define the amount to buy in BTC by specifying the leg_1_amount, or you can specify the amount to spend in EUR by defining the leg_2_amount. Only one of the two legs can be used for a single order!
»»»»»» leg_1_amount	quantity_type	false	The quantity of a leg.
»»»»»» leg_2_amount	quantity_type	false	The quantity of a leg.
»»»»» arrived_at	timestamp_type	false	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»»»»» limit_price	price_type	false	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
»»»»» order_status	order_status_type	false	Orders have a live cycle. The state an order is in that live cycle expressed by its state. The above values are states an order can have in its live cycle. Initially the order is RECEIVED. DUPLICATE, REJECTED, EXPIRED, CANCELLED and DONE are terminal states which will not change any more. UNSPECIFIED means the state is unknown.
»»»» executions	[execution_type]	true	none
»»»»» Order Execution	execution_type	false	none
»»»»»» trade_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»»»»»» leg_1_executed_amount	quantity_type	true	The quantity of a leg.
»»»»»» leg_2_executed_amount	quantity_type	true	The quantity of a leg.
»»»»»» execution_price	price_type	true	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
»»»»»» executed_at	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»»»»»» leg_1_status	trade_leg_status_type	false	none
»»»»»» leg_2_status	trade_leg_status_type	false	none
»» more	boolean	false	none

Enumerated Values

Property	Value
order_type	MARKET
order_type	LIMIT
order_type	BULK_MARKET
time_in_force	FOK
time_in_force	IOC
side	BUY
side	SELL
order_status	UNSPECIFIED
order_status	RECEIVED
order_status	CONFIRMED
order_status	DUPLICATE
order_status	REJECTED
order_status	OPEN
order_status	UPDATED
order_status	CANCELLED
order_status	EXPIRED
order_status	DONE
leg_1_status	UNSPECIFIED
leg_1_status	PENDING
leg_1_status	SETTLED
leg_2_status	UNSPECIFIED
leg_2_status	PENDING
leg_2_status	SETTLED

Get Orders By Sequence Id

Code samples

import requests
import json

PROTOCOL = "https"
ENVIRONMENT = "preprod"
MY_TOKEN = "ENTER YOUR TOKEN HERE"

URL = f"{PROTOCOL}://api.{ENVIRONMENT}.tradias.link/api/orders/sequence"

rest_api_header = {
  "Authorization": "Bearer " + MY_TOKEN
}

params = {"seq_number": 47110815}

get_order_by_sequence_id_request = requests.get(url=URL, headers=rest_api_header, params=params)

print(json.dumps(get_order_by_sequence_id_request.json(), indent=4))

GET /api/orders/sequence

This endpoint can be used to query historic orders by the sequence numbers that are given to the orders. The response from this endpoint is a list of orders that have a sequence number in the interval passed in the request to the endpoint. Sequence numbers strictly increase (although not necessarily by 1) and are most useful when (re-)building a timeseries of the historic orders placed.

It is possible to set a limit on the amount of orders you want to have returned by the endpoint. If some orders are not shown due to the limit, the key ‘more’ will take the value true, if not, it will take the value false.

It is also possible to obtain orders via properties of the orders, however, this is done via another endpoint: Get Orders. The child orders of a bulk order are also visible in the response of the Get Orders and Get Orders By Sequence ID endpoint.

Parameters

Name	In	Type	Required
seq_number	query	sequence_type	true
limit	query	integer	false

Example responses

200 Response

{
  "get_orders_response": {
    "orders": [
      {
        "order_id": "6aa21c20-ae4b-11ed-b304-81a12bb57b04",
        "seq_number": 47110815,
        "order_ref": "18955839",
        "req_header": {
          "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
          "user_data": [
            {
              "tag": "Correlation-Id",
              "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
            },
            {
              "tag": "TX-Id",
              "value": "18955457"
            }
          ]
        },
        "arrived_at": "1970-01-01T00:00:00.000000Z",
        "order": {
          "instrument": "BTC-EUR/SP",
          "order_type": "LIMIT",
          "time_in_force": "FOK",
          "side": "BUY",
          "amount": {
            "leg_1_amount": "2.5"
          },
          "limit_price": "24650",
          "order_status": "DONE"
        },
        "executions": [
          {
            "trade_id": "6aa21c20-ae4b-11ed-b304-81a12bb57b04",
            "leg_1_executed_amount": "1.25867895",
            "leg_2_executed_amount": "1.25867895",
            "execution_price": "23768.63953056",
            "executed_at": "1970-01-01T00:00:00.000000Z",
            "leg_1_status": "PENDING",
            "leg_2_status": "SETTLED"
          }
        ]
      }
    ],
    "more": false
  }
}

401 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "Unauthorized",
    "error_text": "The JWT token could not be validated"
  }
}

404 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "NotFound",
    "error_text": "The given object (Order, Trade, ...) could not be found."
  }
}

422 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "ValidationError",
    "error_text": "The request is not valid"
  }
}

500 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "InternalServerError",
    "error_text": "Internal Server Error: the server can currently not process the request"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Get Orders	Inline
401	Unauthorized	Unauthorized	internal_error_type
404	Not Found	Not Found	internal_error_type
422	Unprocessable Entity	Unprocessable Request	internal_error_type
500	Internal Server Error	Internal Server Error	internal_error_type

Response Schema

Status Code 200

Get Orders Response

Name	Type	Required	Description
» get_orders_response	object	true	none
»» orders	[object]	true	none
»»» Order Details	object	false	none
»»»» order_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»»»» seq_number	sequence_type	true	Sequence number of an order, trade or any other event. A sequence number is assigned to the object (e.g. order) when it is received. All sequence number are unique and increasing. There may be gaps in the sequence numbers assigned! The sequence number can ba used sort objects in the way they have been received/happened. If the maximum is reached the sequence numbers continue with 0.
»»»» order_ref	external_ref_type	false	This field is used by the API user to pass an reference or ID to the tradias system which is used in the tradias system to to act as an reference or ID to the transaction in the API users system.
»»»» req_header	req_header_type	false	This request header is part of any request creating or modifying an object (order, bulk-order, settlement, …). It consists of two parts, a request ID which will be checked on the tradias side for uniqueness, and an array of user data (tag value). Both parts are option as the complete request header is. The request ID can be used by the API user to allow, that if a request does not answer properly, to sent the request again. If the first one has been processed, then the second one will be rejected with a 409 error and the API user knows that the first request has been processed. If the first request did not make it the second one will be processed normally. The second part is an array of values tagged by a short tag. This data provided by the API user will be returned with the response of the request and if a possible will be added to the object the request relates to and later returned with all responses relating to the object.
»»»»» req_id	unique_req_type	false	The unique request ID is generated by the API user, it has to be a UUID. It is used to detect that a request has already been processed. If the unique request ID has already been used then the request will not be executed. Instead an error will be (DuplicateReq) reported.
»»»»» user_data	[object]	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.
»»»»»» tag	string	true	none
»»»»»» value	string	true	none
»»»» arrived_at	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»»»» order	order_data_type	true	This schema represents all information of an order
»»»»» instrument	instrument_type	true	Identifier for an instrument. It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]
»»»»» order_type	order_type_type	true	There are different order types. Currently only the following order types are supported * MARKET: This is a order (without limit). * LIMIT: This is a order with a limit. Buy orders are only executed if the execution price is lower or equal than the limit price. Sell orders are only executed if the execution price is higher or equal than the limit price. * BULK_MARKET: This is a list order where multiple orders are entered as a single bulk. The bulk is either executed completely or not at all.
»»»»» time_in_force	time_in_force_type	false	This order attribute defines the duration a order is active. * FOK: Fill Or Kill is an order which is either completely executed immediately or will be canceled/rejected. * IOC: Immediately Or Cancel is an order which is either executed immediately or will be canceled/rejected. The difference to FOK is that IOC allows partial executions. As tradias always executes completely there is no difference in FOK and IOC orders.
»»»»» side	side_type	true	The side of the order, seen from the perspective of the API user. * BUY The user sending the order is buying assets * SELL The user sending the order is selling his assets
»»»»» amount	order_amount_type	true	You can specify the amount of an instrument to buy or sell either in the leg_1 or in the leg_2 quantity. If you for example want to buy BTC-EUR you can either define the amount to buy in BTC by specifying the leg_1_amount, or you can specify the amount to spend in EUR by defining the leg_2_amount. Only one of the two legs can be used for a single order!
»»»»»» leg_1_amount	quantity_type	false	The quantity of a leg.
»»»»»» leg_2_amount	quantity_type	false	The quantity of a leg.
»»»»» arrived_at	timestamp_type	false	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»»»»» limit_price	price_type	false	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
»»»»» order_status	order_status_type	false	Orders have a live cycle. The state an order is in that live cycle expressed by its state. The above values are states an order can have in its live cycle. Initially the order is RECEIVED. DUPLICATE, REJECTED, EXPIRED, CANCELLED and DONE are terminal states which will not change any more. UNSPECIFIED means the state is unknown.
»»»» executions	[execution_type]	true	none
»»»»» Order Execution	execution_type	false	none
»»»»»» trade_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»»»»»» leg_1_executed_amount	quantity_type	true	The quantity of a leg.
»»»»»» leg_2_executed_amount	quantity_type	true	The quantity of a leg.
»»»»»» execution_price	price_type	true	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
»»»»»» executed_at	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»»»»»» leg_1_status	trade_leg_status_type	false	none
»»»»»» leg_2_status	trade_leg_status_type	false	none
»» more	boolean	false	none

Enumerated Values

Property	Value
order_type	MARKET
order_type	LIMIT
order_type	BULK_MARKET
time_in_force	FOK
time_in_force	IOC
side	BUY
side	SELL
order_status	UNSPECIFIED
order_status	RECEIVED
order_status	CONFIRMED
order_status	DUPLICATE
order_status	REJECTED
order_status	OPEN
order_status	UPDATED
order_status	CANCELLED
order_status	EXPIRED
order_status	DONE
leg_1_status	UNSPECIFIED
leg_1_status	PENDING
leg_1_status	SETTLED
leg_2_status	UNSPECIFIED
leg_2_status	PENDING
leg_2_status	SETTLED

Get Trades

Code samples

import requests
import json

PROTOCOL = "https"
ENVIRONMENT = "preprod"
MY_TOKEN = "ENTER YOUR TOKEN HERE"

URL = f"{PROTOCOL}://api.{ENVIRONMENT}.tradias.link/api/trades

rest_api_header = {
    "Authorization": "Bearer " + MY_TOKEN
}

filter_params = {
    "from_datetime": "2023-10-20T11:20:21.000000Z",
    "to_datetime": "2023-10-20T15:20:21.000000Z",
    "side": "SELL",
    "type": "MARKET",
    "instrument": "BTC-EUR/SP",
    "price_from": "24000"
}

get_trades_request = requests.get(url=URL, headers=rest_api_header, params=filter_params)

print(json.dumps(get_trades_request.json(), indent=4))

GET /api/trades

This endpoint enables highly customizable queries on historic trade data. The response from this endpoint is a list of trades that fit the criteria given by the filters that were passed in the request.

Additionally, it is possible to filter by a price (range) and the trade ID’s. It is also possible to filter by timestamp and to set a limit on the amount of trades returned by the endpoint. If some trades are not shown due to the limit, the key ‘more’ will take the value true, otherwise it will take the value false.

It is also possible to obtain trades via the sequence number, however, this is done via another endpoint: Get Trades By Sequence ID. The trades originating from a bulk order are also visible in from the response of the Get Trades and Get Trades By Sequence ID endpoint.

Parameters

Name	In	Type	Required
from_datetime	query	timestamp_type	true
to_datetime	query	timestamp_type	true
instrument	query	instrument_type	false
side	query	side_type	false
trade_id	query	internal_ref_type	false
order_id	query	internal_ref_type	false
order_ref	query	external_ref_type	false
leg_1_status	query	trade_leg_status_type	false
leg_2_status	query	trade_leg_status_type	false
price_from	query	price_type	false
price_to	query	price_type	false
leg_1_from	query	quantity_type	false
leg_1_to	query	quantity_type	false
leg_2_from	query	quantity_type	false
leg_2_to	query	quantity_type	false
limit	query	integer	false
skip	query	integer	false

Enumerated Values

Parameter	Value
side	BUY
side	SELL
leg_1_status	UNSPECIFIED
leg_1_status	PENDING
leg_1_status	SETTLED
leg_2_status	UNSPECIFIED
leg_2_status	PENDING
leg_2_status	SETTLED

Example responses

200 Response

{
  "get_trades_response": {
    "trades": [
      {
        "trade_id": "6aa21c20-ae4b-11ed-b304-81a12bb57b04",
        "seq_number": 47110815,
        "order_id": "73f2e419-e4ac-4db2-84ab-81a12ad43d54",
        "order_ref": "18955839",
        "req_header": {
          "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
          "user_data": [
            {
              "tag": "Correlation-Id",
              "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
            },
            {
              "tag": "TX-Id",
              "value": "18955457"
            }
          ]
        },
        "order": {
          "instrument": "BTC-EUR/SP",
          "order_type": "LIMIT",
          "time_in_force": "FOK",
          "side": "BUY",
          "amount": {
            "leg_1_amount": "2.5"
          },
          "limit_price": "24650",
          "arrived_at": "1970-01-01T00:00:00.000000Z",
          "order_status": "DONE"
        },
        "execution": {
          "leg_1_executed_amount": "1.25867895",
          "leg_2_executed_amount": "1.25867895",
          "execution_price": "23768.63953056",
          "executed_at": "1970-01-01T00:00:00.000000Z",
          "leg_1_status": "PENDING",
          "leg_2_status": "SETTLED"
        }
      }
    ],
    "more": false
  }
}

401 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "Unauthorized",
    "error_text": "The JWT token could not be validated"
  }
}

404 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "NotFound",
    "error_text": "The given object (Order, Trade, ...) could not be found."
  }
}

422 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "ValidationError",
    "error_text": "The request is not valid"
  }
}

500 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "InternalServerError",
    "error_text": "Internal Server Error: the server can currently not process the request"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Get Trades	Inline
401	Unauthorized	Unauthorized	internal_error_type
404	Not Found	Not Found	internal_error_type
422	Unprocessable Entity	Unprocessable Request	internal_error_type
500	Internal Server Error	Internal Server Error	internal_error_type

Response Schema

Status Code 200

Get Trades Response

Name	Type	Required	Description
» get_trades_response	object	true	none
»» trades	[object]	true	none
»»» Trade Details	object	false	none
»»»» trade_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»»»» seq_number	sequence_type	true	Sequence number of an order, trade or any other event. A sequence number is assigned to the object (e.g. order) when it is received. All sequence number are unique and increasing. There may be gaps in the sequence numbers assigned! The sequence number can ba used sort objects in the way they have been received/happened. If the maximum is reached the sequence numbers continue with 0.
»»»» order_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»»»» order_ref	external_ref_type	false	This field is used by the API user to pass an reference or ID to the tradias system which is used in the tradias system to to act as an reference or ID to the transaction in the API users system.
»»»» req_header	req_header_type	false	This request header is part of any request creating or modifying an object (order, bulk-order, settlement, …). It consists of two parts, a request ID which will be checked on the tradias side for uniqueness, and an array of user data (tag value). Both parts are option as the complete request header is. The request ID can be used by the API user to allow, that if a request does not answer properly, to sent the request again. If the first one has been processed, then the second one will be rejected with a 409 error and the API user knows that the first request has been processed. If the first request did not make it the second one will be processed normally. The second part is an array of values tagged by a short tag. This data provided by the API user will be returned with the response of the request and if a possible will be added to the object the request relates to and later returned with all responses relating to the object.
»»»»» req_id	unique_req_type	false	The unique request ID is generated by the API user, it has to be a UUID. It is used to detect that a request has already been processed. If the unique request ID has already been used then the request will not be executed. Instead an error will be (DuplicateReq) reported.
»»»»» user_data	[object]	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.
»»»»»» tag	string	true	none
»»»»»» value	string	true	none
»»»» order	order_data_type	true	This schema represents all information of an order
»»»»» instrument	instrument_type	true	Identifier for an instrument. It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]
»»»»» order_type	order_type_type	true	There are different order types. Currently only the following order types are supported * MARKET: This is a order (without limit). * LIMIT: This is a order with a limit. Buy orders are only executed if the execution price is lower or equal than the limit price. Sell orders are only executed if the execution price is higher or equal than the limit price. * BULK_MARKET: This is a list order where multiple orders are entered as a single bulk. The bulk is either executed completely or not at all.
»»»»» time_in_force	time_in_force_type	false	This order attribute defines the duration a order is active. * FOK: Fill Or Kill is an order which is either completely executed immediately or will be canceled/rejected. * IOC: Immediately Or Cancel is an order which is either executed immediately or will be canceled/rejected. The difference to FOK is that IOC allows partial executions. As tradias always executes completely there is no difference in FOK and IOC orders.
»»»»» side	side_type	true	The side of the order, seen from the perspective of the API user. * BUY The user sending the order is buying assets * SELL The user sending the order is selling his assets
»»»»» amount	order_amount_type	true	You can specify the amount of an instrument to buy or sell either in the leg_1 or in the leg_2 quantity. If you for example want to buy BTC-EUR you can either define the amount to buy in BTC by specifying the leg_1_amount, or you can specify the amount to spend in EUR by defining the leg_2_amount. Only one of the two legs can be used for a single order!
»»»»»» leg_1_amount	quantity_type	false	The quantity of a leg.
»»»»»» leg_2_amount	quantity_type	false	The quantity of a leg.
»»»»» arrived_at	timestamp_type	false	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»»»»» limit_price	price_type	false	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
»»»»» order_status	order_status_type	false	Orders have a live cycle. The state an order is in that live cycle expressed by its state. The above values are states an order can have in its live cycle. Initially the order is RECEIVED. DUPLICATE, REJECTED, EXPIRED, CANCELLED and DONE are terminal states which will not change any more. UNSPECIFIED means the state is unknown.
»»»» trade	trade_type	true	none
»»»»» leg_1_executed_amount	quantity_type	true	The quantity of a leg.
»»»»» leg_2_executed_amount	quantity_type	true	The quantity of a leg.
»»»»» execution_price	price_type	true	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
»»»»» executed_at	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»»»»» leg_1_status	trade_leg_status_type	false	none
»»»»» leg_2_status	trade_leg_status_type	false	none
»»»» execution	execution_type	false	none
»»»»» trade_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»»»»» leg_1_executed_amount	quantity_type	true	The quantity of a leg.
»»»»» leg_2_executed_amount	quantity_type	true	The quantity of a leg.
»»»»» execution_price	price_type	true	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
»»»»» executed_at	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»»»»» leg_1_status	trade_leg_status_type	false	none
»»»»» leg_2_status	trade_leg_status_type	false	none
»» more	boolean	false	none

Enumerated Values

Property	Value
order_type	MARKET
order_type	LIMIT
order_type	BULK_MARKET
time_in_force	FOK
time_in_force	IOC
side	BUY
side	SELL
order_status	UNSPECIFIED
order_status	RECEIVED
order_status	CONFIRMED
order_status	DUPLICATE
order_status	REJECTED
order_status	OPEN
order_status	UPDATED
order_status	CANCELLED
order_status	EXPIRED
order_status	DONE
leg_1_status	UNSPECIFIED
leg_1_status	PENDING
leg_1_status	SETTLED
leg_2_status	UNSPECIFIED
leg_2_status	PENDING
leg_2_status	SETTLED
leg_1_status	UNSPECIFIED
leg_1_status	PENDING
leg_1_status	SETTLED
leg_2_status	UNSPECIFIED
leg_2_status	PENDING
leg_2_status	SETTLED

Get Trades By Sequence ID

Code samples

import requests
import json

PROTOCOL = "https"
ENVIRONMENT = "preprod"
MY_TOKEN = "ENTER YOUR TOKEN HERE"

URL = f"{PROTOCOL}://api.{ENVIRONMENT}.tradias.link/api/trades/sequence"

rest_api_header = {
    "Authorization": "Bearer " + MY_TOKEN
}

params = {"seq_number": 47110815}

get_trade_by_sequence_id_request = requests.get(url=URL, headers=rest_api_header)

print(json.dumps(get_trade_by_sequence_id_request.json(), indent=4))

GET /api/trades/sequence

This endpoint enables queries on historic trade data by sequence id. The response from this endpoint is a list of trades that have a sequence number in the interval passed in the request to the endpoint. Sequence numbers strictly increase (although not necessarily by 1) and are most useful when (re-)building a timeseries of the historic trades.

It is possible to set a limit on the amount of trades returned by the endpoint.

If some trades are not shown due to the limit, the key ‘more’ will take the value true, if not, it will take the value false. It is also possible to obtain trades via properties of the trades/orders, however, this is done via another endpoint: Get Trades. The trades originating from a bulk order are also visible in from the response of the Get Trades and Get Trades By Sequence ID endpoint.

Parameters

Name	In	Type	Required
seq_number	query	sequence_type	true
limit	query	integer	false

Example responses

200 Response

{
  "get_trades_response": {
    "trades": [
      {
        "trade_id": "6aa21c20-ae4b-11ed-b304-81a12bb57b04",
        "seq_number": 47110815,
        "order_id": "73f2e419-e4ac-4db2-84ab-81a12ad43d54",
        "order_ref": "18955839",
        "req_header": {
          "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
          "user_data": [
            {
              "tag": "Correlation-Id",
              "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
            },
            {
              "tag": "TX-Id",
              "value": "18955457"
            }
          ]
        },
        "order": {
          "instrument": "BTC-EUR/SP",
          "order_type": "LIMIT",
          "time_in_force": "FOK",
          "side": "BUY",
          "amount": {
            "leg_1_amount": "2.5"
          },
          "limit_price": "24650",
          "arrived_at": "1970-01-01T00:00:00.000000Z",
          "order_status": "DONE"
        },
        "execution": {
          "leg_1_executed_amount": "1.25867895",
          "leg_2_executed_amount": "1.25867895",
          "execution_price": "23768.63953056",
          "executed_at": "1970-01-01T00:00:00.000000Z",
          "leg_1_status": "PENDING",
          "leg_2_status": "SETTLED"
        }
      }
    ],
    "more": false
  }
}

401 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "Unauthorized",
    "error_text": "The JWT token could not be validated"
  }
}

404 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "NotFound",
    "error_text": "The given object (Order, Trade, ...) could not be found."
  }
}

422 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "ValidationError",
    "error_text": "The request is not valid"
  }
}

500 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "InternalServerError",
    "error_text": "Internal Server Error: the server can currently not process the request"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Get Trades	Inline
401	Unauthorized	Unauthorized	internal_error_type
404	Not Found	Not Found	internal_error_type
422	Unprocessable Entity	Unprocessable Request	internal_error_type
500	Internal Server Error	Internal Server Error	internal_error_type

Response Schema

Status Code 200

Get Trades Response

Name	Type	Required	Description
» get_trades_response	object	true	none
»» trades	[object]	true	none
»»» Trade Details	object	false	none
»»»» trade_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»»»» seq_number	sequence_type	true	Sequence number of an order, trade or any other event. A sequence number is assigned to the object (e.g. order) when it is received. All sequence number are unique and increasing. There may be gaps in the sequence numbers assigned! The sequence number can ba used sort objects in the way they have been received/happened. If the maximum is reached the sequence numbers continue with 0.
»»»» order_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»»»» order_ref	external_ref_type	false	This field is used by the API user to pass an reference or ID to the tradias system which is used in the tradias system to to act as an reference or ID to the transaction in the API users system.
»»»» req_header	req_header_type	false	This request header is part of any request creating or modifying an object (order, bulk-order, settlement, …). It consists of two parts, a request ID which will be checked on the tradias side for uniqueness, and an array of user data (tag value). Both parts are option as the complete request header is. The request ID can be used by the API user to allow, that if a request does not answer properly, to sent the request again. If the first one has been processed, then the second one will be rejected with a 409 error and the API user knows that the first request has been processed. If the first request did not make it the second one will be processed normally. The second part is an array of values tagged by a short tag. This data provided by the API user will be returned with the response of the request and if a possible will be added to the object the request relates to and later returned with all responses relating to the object.
»»»»» req_id	unique_req_type	false	The unique request ID is generated by the API user, it has to be a UUID. It is used to detect that a request has already been processed. If the unique request ID has already been used then the request will not be executed. Instead an error will be (DuplicateReq) reported.
»»»»» user_data	[object]	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.
»»»»»» tag	string	true	none
»»»»»» value	string	true	none
»»»» order	order_data_type	true	This schema represents all information of an order
»»»»» instrument	instrument_type	true	Identifier for an instrument. It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]
»»»»» order_type	order_type_type	true	There are different order types. Currently only the following order types are supported * MARKET: This is a order (without limit). * LIMIT: This is a order with a limit. Buy orders are only executed if the execution price is lower or equal than the limit price. Sell orders are only executed if the execution price is higher or equal than the limit price. * BULK_MARKET: This is a list order where multiple orders are entered as a single bulk. The bulk is either executed completely or not at all.
»»»»» time_in_force	time_in_force_type	false	This order attribute defines the duration a order is active. * FOK: Fill Or Kill is an order which is either completely executed immediately or will be canceled/rejected. * IOC: Immediately Or Cancel is an order which is either executed immediately or will be canceled/rejected. The difference to FOK is that IOC allows partial executions. As tradias always executes completely there is no difference in FOK and IOC orders.
»»»»» side	side_type	true	The side of the order, seen from the perspective of the API user. * BUY The user sending the order is buying assets * SELL The user sending the order is selling his assets
»»»»» amount	order_amount_type	true	You can specify the amount of an instrument to buy or sell either in the leg_1 or in the leg_2 quantity. If you for example want to buy BTC-EUR you can either define the amount to buy in BTC by specifying the leg_1_amount, or you can specify the amount to spend in EUR by defining the leg_2_amount. Only one of the two legs can be used for a single order!
»»»»»» leg_1_amount	quantity_type	false	The quantity of a leg.
»»»»»» leg_2_amount	quantity_type	false	The quantity of a leg.
»»»»» arrived_at	timestamp_type	false	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»»»»» limit_price	price_type	false	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
»»»»» order_status	order_status_type	false	Orders have a live cycle. The state an order is in that live cycle expressed by its state. The above values are states an order can have in its live cycle. Initially the order is RECEIVED. DUPLICATE, REJECTED, EXPIRED, CANCELLED and DONE are terminal states which will not change any more. UNSPECIFIED means the state is unknown.
»»»» trade	trade_type	true	none
»»»»» leg_1_executed_amount	quantity_type	true	The quantity of a leg.
»»»»» leg_2_executed_amount	quantity_type	true	The quantity of a leg.
»»»»» execution_price	price_type	true	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
»»»»» executed_at	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»»»»» leg_1_status	trade_leg_status_type	false	none
»»»»» leg_2_status	trade_leg_status_type	false	none
»»»» execution	execution_type	false	none
»»»»» trade_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»»»»» leg_1_executed_amount	quantity_type	true	The quantity of a leg.
»»»»» leg_2_executed_amount	quantity_type	true	The quantity of a leg.
»»»»» execution_price	price_type	true	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
»»»»» executed_at	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»»»»» leg_1_status	trade_leg_status_type	false	none
»»»»» leg_2_status	trade_leg_status_type	false	none
»» more	boolean	false	none

Enumerated Values

Property	Value
order_type	MARKET
order_type	LIMIT
order_type	BULK_MARKET
time_in_force	FOK
time_in_force	IOC
side	BUY
side	SELL
order_status	UNSPECIFIED
order_status	RECEIVED
order_status	CONFIRMED
order_status	DUPLICATE
order_status	REJECTED
order_status	OPEN
order_status	UPDATED
order_status	CANCELLED
order_status	EXPIRED
order_status	DONE
leg_1_status	UNSPECIFIED
leg_1_status	PENDING
leg_1_status	SETTLED
leg_2_status	UNSPECIFIED
leg_2_status	PENDING
leg_2_status	SETTLED
leg_1_status	UNSPECIFIED
leg_1_status	PENDING
leg_1_status	SETTLED
leg_2_status	UNSPECIFIED
leg_2_status	PENDING
leg_2_status	SETTLED

Settlement Procedure

The Settlement Request and Transactions endpoints serve to automate settlement and simplify the reconciliation. Before using the endpoints, make sure that the addresses (SSIs) for the currencies (fiat and crypto) in use for settlement are shared with tradias and whitelisted. Please inform with your contact at tradias how to share the addresses. In general, the user flow for the settlement and transactions API looks as follows:

Send one or more order(s) through the WebSocket or to the bulk order endpoint.
Collect the trade_id(s), leg_1_amount(s) and leg_2_amount(s) for each trade as well as the corresponding leg_1_asset(s) and leg_2_asset(s).
Post a settlement request via the Settlement Request endpoint: In the req_header, optionally pass a value for the req_id (this has to be a UUID), this will have an idempotency property. From the response, obtain the settlement_request_id, which is needed to use the Get Settlement Request and Map Transaction With Settlement Request Amount endpoints.
Get the status of the settlement request using the Get Settlement Request Status endpoint. As the settlement requests are processed asynchronously, this endpoint serves as a check on the completion of the processing of the settlement request. The response of such a call is either ‘CONFIRMED’, ‘PARTIALLY’, ‘SETTLED’ or ‘REJECTED’.
Get the settlement request by passing the settlement_request_id in the Get Settlement Request endpoint call. The response contains all information on the settlement request, such as which amounts are settled or why a settlement request was rejected.
The confirmation of a settlement request implies the intention to settle each settlement_request_amount in the settlement request to and from the respective senders and receivers. For settlement to be completed, each settlement_request_amount needs to be associated with one or more transactions.
Initiate your settlement transactions through your bank and/or custodian. Save the reference used to identify the transaction uniquely on the channel used (e.g. SEPA reference, On-Chain Transaction IDs).
Get the transactions: using the Get Settlement Transactions endpoint, all transactions arrived at or sent from tradias & Bankhaus Scheich to you and corresponding transaction_id’s can be viewed.
Patch transactions with settlement request amount: using the endpoint Map Transaction With Settlement Request Amount, an amount from a transaction can be mapped to a settlement request. This amount does not have to be precisely the amount in the transaction, nor does it have to be exactly the amount in the settlement request. However, the amount can not exceed the outstanding amount in the transaction, nor the amount in the settlement request. This only applies to transactions from you to Bankhaus Scheich/tradias, transactions to you will be mapped automatically.

In the case the the netted settlement amount for a specific asset traded adds to 0, a settlement request amount with the amount set to 0 should be included in the corresponding settlement request. Such a settlement request amount would take the following format: { “currency”: “The asset code for which the amount to be settled is 0”, “from_address”: “BHS”, “to_address”: “Your address”, “amount”: “0” }

Whenever there is a rejection of a settlement request, you will be able to see this when querying the Get Settlement Request endpoint. If there are unknown trades, already settled trades or trades that are already in another uncompleted settlement request, you will be able to see this in the response. Also, you are able to see the validity of addresses and computed amounts in the response. These fields can be used to understand the reasons behind the failure of the confirmation of the settlement request.

Settlement Request

Code samples

import requests
import json

PROTOCOL = "https"
ENVIRONMENT = "preprod"
MY_TOKEN = "ENTER YOUR TOKEN HERE"

URL = f"{PROTOCOL}://api.{ENVIRONMENT}.tradias.link/api/settlement-requests"

rest_api_header = {
    "Authorization": "Bearer " + MY_TOKEN
}

payload = {
    "req_header": {
        "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
        "user_data": [
            {
                "tag": "Correlation-Id",
                "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
            },
            {
                "tag": "TX-Id",
                "value": "18955457"
            }
        ]
    },
    "settlement_request_ref": "6aa21c20-ae4b-11ed-b304-81a12bb57b04",
    "trade_ids": [
        "2987a674-fa91-4bcb-b480-24934bc4166c",
        "a83ceb8f-a7cd-46c6-8322-826a21f56511",
        "94f7b459-ae19-4600-8d72-9a21c78b86f4"
    ],
    "request_amounts": [
        {
            "currency": "EUR",
            "from_address": "BHS",
            "to_address": "DE89370400440532013000",
            "amount": "12766.04"
        },
        {
            "currency": "LTC",
            "from_address": "BHS",
            "to_address": "MGxNPPB7eBoWPUaprtX9v9CXJZoD2465zN",
            "amount": "207.606"
        },
        {
            "currency": "BTC",
            "from_address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
            "to_address": "BHS",
            "amount": "1.23"
        }
    ]
}

post_settlement_request = requests.post(url=URL, json=payload, headers=rest_api_header)
print(json.dumps(post_settlement_request.json(), indent=4))

POST /api/settlement-requests

Tradias offers post-trade settlement. The settlement process with tradias is completely automatable. Depending on the setup, settlement is typically done T+1 or T+2. The settlement procedure consists of the following steps:

Post a settlement request which includes all trades that you want to/have to settle and the corresponding amounts and addresses per currency/asset.
When the system agrees on the amounts (this is checked based on the trades included in the request) and the addresses and there are no unknown or conflicting trades, the settlement request is accepted.
Both you and tradias do the necessary settlement transactions.
You map the transactions to the settlement request of your choice.
Once all amounts in the settlement request have a transaction and amount mapped to it that covers the amount to be settled, the settlement request status changes to ‘settled’ and the settlement is complete.

It is possible to include several settlement request amounts with the same currency but difference from and to addresses. In such a case the reconciliation is based on the sum of these amounts.

As is the case for other REST requests, you can use the “req_id” as an idempotency key and “user_data” to pass any additional information of your choice.

In case a settlement request is rejected, a new settlement request has to be created. There can be several reasons for a rejection. If a settlement request is rejected due to one of the following reasons, it will be visible in the response of the Get Settlement Request endpoint:

Unknown trades: you have included a trade_id that is not known to our system.
Conflicting trades: you have included a trade_id that is also included in a settlement request that is already pending.
Already settled trades: you have included a trade_id that is also included in a settlement request that is already settled.
Invalid address: you have included an address that is not in our system.
Incorrect amounts: you have included an amount to be settled that is different than the amount that we computed. The amounts are computed solely based on the trades that you passed in the settlement request.

Note that it is not required to settle in the order in which the trading occurred, however, it is not possible to leave trades unsettled for more than 5 business days.

Body parameter

{
  "settlement_request": {
    "req_header": {
      "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
      "user_data": [
        {
          "tag": "Correlation-Id",
          "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
        },
        {
          "tag": "TX-Id",
          "value": "18955457"
        }
      ]
    },
    "settlement_request_ref": "6aa21c20-ae4b-11ed-b304-81a12bb57b04",
    "trade_ids": [
      "2987a674-fa91-4bcb-b480-24934bc4166c",
      "a83ceb8f-a7cd-46c6-8322-826a21f56511",
      "94f7b459-ae19-4600-8d72-9a21c78b86f4"
    ],
    "settlement_amounts": [
      {
        "currency": "EUR",
        "from_address": "BHS",
        "to_address": "DE89370400440532013000",
        "amount": "12766.04"
      },
      {
        "currency": "LTC",
        "from_address": "BHS",
        "to_address": "MGxNPPB7eBoWPUaprtX9v9CXJZoD2465zN",
        "amount": "207.606"
      },
      {
        "currency": "BTC",
        "from_address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
        "to_address": "BHS",
        "amount": "1.23"
      }
    ]
  }
}

Parameters

Name	In	Type	Required
body	body	object	true
» settlement_request	body	object	true
»» req_header	body	req_header_type	false
»»» req_id	body	unique_req_type	false
»»» user_data	body	[object]	false
»»»» tag	body	string	true
»»»» value	body	string	true
»» settlement_request_ref	body	external_ref_type	true
»» trade_ids	body	[internal_ref_type]	true
»»» Internal Reference or Id	body	internal_ref_type	false
»» settlement_amounts	body	[object]	true
»»» Settlement Amount	body	object	false
»»»» currency	body	asset_code_type	true
»»»» from_address	body	address_type	true
»»»» to_address	body	address_type	true
»»»» amount	body	quantity_type	true

Detailed descriptions

»» trade_ids: List of all trade_ids which net to the settlement amounts contained in the request_amounts field.

Example responses

202 Response

{
  "settlement_request_response": {
    "settlement_request_id": "6aa21c20-ae4b-11ed-b304-81a12bb57b04",
    "settlement_request_ref": "c8d16891-b669-11ed-bc43-f1002b6e6125",
    "req_header": {
      "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
      "user_data": [
        {
          "tag": "Correlation-Id",
          "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
        },
        {
          "tag": "TX-Id",
          "value": "18955457"
        }
      ]
    },
    "timestamp": "1970-01-01T00:00:00.000000Z",
    "settlement_status": "RECEIVED"
  }
}

401 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "Unauthorized",
    "error_text": "The JWT token could not be validated"
  }
}

409 Response

{
  "error_req_header": {
    "req_header": {
      "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
      "user_data": [
        {
          "tag": "Correlation-Id",
          "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
        },
        {
          "tag": "TX-Id",
          "value": "18955457"
        }
      ]
    },
    "tradias_id": "75ccdf76-ae4b-11ed-85ee-81a12bb57b04",
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "DuplicateReq",
    "error_text": "The req_id has been already processed"
  }
}

422 Response

{
  "error_req_header": {
    "req_header": {
      "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
      "user_data": [
        {
          "tag": "Correlation-Id",
          "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
        },
        {
          "tag": "TX-Id",
          "value": "18955457"
        }
      ]
    },
    "tradias_id": "75ccdf76-ae4b-11ed-85ee-81a12bb57b04",
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "UnprocessableEntity",
    "error_text": "The request is not processable"
  }
}

500 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "InternalServerError",
    "error_text": "Internal Server Error: the server can currently not process the request"
  }
}

Responses

Status	Meaning	Description	Schema
202	Accepted	Settlement Status Response - Short Version	Inline
401	Unauthorized	Unauthorized	internal_error_type
409	Conflict	Duplicate Request	internal_req_error_type
422	Unprocessable Entity	Unprocessable Entity	internal_req_error_type
500	Internal Server Error	Internal Server Error	internal_error_type

Response Schema

Status Code 202

Settlement Request Response

Name	Type	Required	Description
» settlement_request_response	object	true	none
»» settlement_request_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»» settlement_request_ref	external_ref_type	false	This field is used by the API user to pass an reference or ID to the tradias system which is used in the tradias system to to act as an reference or ID to the transaction in the API users system.
»» req_header	req_header_type	false	This request header is part of any request creating or modifying an object (order, bulk-order, settlement, …). It consists of two parts, a request ID which will be checked on the tradias side for uniqueness, and an array of user data (tag value). Both parts are option as the complete request header is. The request ID can be used by the API user to allow, that if a request does not answer properly, to sent the request again. If the first one has been processed, then the second one will be rejected with a 409 error and the API user knows that the first request has been processed. If the first request did not make it the second one will be processed normally. The second part is an array of values tagged by a short tag. This data provided by the API user will be returned with the response of the request and if a possible will be added to the object the request relates to and later returned with all responses relating to the object.
»»» req_id	unique_req_type	false	The unique request ID is generated by the API user, it has to be a UUID. It is used to detect that a request has already been processed. If the unique request ID has already been used then the request will not be executed. Instead an error will be (DuplicateReq) reported.
»»» user_data	[object]	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.
»»»» tag	string	true	none
»»»» value	string	true	none
»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» settlement_status	settlement_status_type	true	Status of a settlement. In case the trades in the settlement request are ok and result in the correct amounts, the value will be CONFIRMED. The value switches to “PARTIALLY”, once the transaction has been made and to SETTLED if all transactions have been successfully executed. In case if there is a problem with the settlement its status will be REJECTED. When the settlement request has just been sent the status will be RECEIVED. This status is also been used to reflect the status of each amount (transaction) of a settlement. In this case the state PARTIALLY will not been used.

Enumerated Values

Property	Value
settlement_status	RECEIVED
settlement_status	REJECTED
settlement_status	CONFIRMED
settlement_status	PARTIALLY
settlement_status	SETTLED

Get Settlement Request Status

Code samples

import requests
import json

PROTOCOL = "https"
ENVIRONMENT = "PREPROD"
MY_TOKEN = "ENTER YOUR TOKEN HERE"

settlement_request_id = "13bd7e32-4a43-4112-9002-38c402a2fb11"

URL = f"{PROTOCOL}://api.{ENVIRONMENT}.tradias.link/api/settlement-requests/{settlement_request_id}/status"

rest_api_header = {
    "Authorization": "Bearer " + MY_TOKEN
}

settlement_request_status = requests.get(url=URL, headers=rest_api_header)
print(json.dumps(setllement_request_status.json(), indent=4))

GET /api/settlement-requests/{settlement_request_id}/status

This endpoint can be used to query the status of a settlement request after posting it to the Settlement Request endpoint. Both the Get Settlement Request and Get Settlement Request Status endpoints can be used to query information on a posted settlement request. The difference between the endpoints is that the Get Settlement Request Status returns a more compact response than the Get Settlement Request endpoint. In particular, the Get Settlement Request Status returns some basic information on the settlement request together with the status. The Get Settlement Request endpoint returns all information on the settlement request, including linked transactions. The Get Settlement Request Status is therefore more useful when polling the endpoint to check for completion of the settlement.

The possible status that can be returned are the following:

CONFIRMED: the settlement request is received and the trades, amounts and addresses are correct.
PARTIALLY SETTLED: the settlement request is accepted and some (but not all) of the amounts to be settled have been settled.
SETTLED: the settlement request is accepted and all amounts to be settled are settled.
REJECTED: the status will change to this when there is a problem with the request.

Parameters

Name	In	Type	Required
settlement_request_id	path	internal_ref_type	true

Example responses

200 Response

{
  "settlement_request_response": {
    "settlement_request_id": "6aa21c20-ae4b-11ed-b304-81a12bb57b04",
    "settlement_request_ref": "c8d16891-b669-11ed-bc43-f1002b6e6125",
    "req_header": {
      "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
      "user_data": [
        {
          "tag": "Correlation-Id",
          "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
        },
        {
          "tag": "TX-Id",
          "value": "18955457"
        }
      ]
    },
    "timestamp": "1970-01-01T00:00:00.000000Z",
    "settlement_status": "PARTIALLY",
    "settlement_amounts": [
      {
        "settlement_request_amount_id": "6aa21c20-ae4b-11ed-b304-81a12bb57b04",
        "currency": "BTC",
        "from_address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
        "to_address": "BHS",
        "amount": "1.23",
        "expected_amount": "1.23",
        "status": "PARTIALLY",
        "transactions": [
          {
            "tx_id": "265a2482-bf2f-11ed-8f96-eac8fe84d40c",
            "reference_type": "ON_CHAIN_TX_ID",
            "reference": "1b82e950aebfd74ab6508538f2138cf4ab0b904a9a3c93ad2df209e5f78d1ea9",
            "amount": "1.00"
          }
        ]
      },
      {
        "settlement_request_amount_id": "6aa21c20-ae4b-11ed-b304-81a12bb57b04",
        "currency": "EUR",
        "from_address": "BHS",
        "to_address": "DE89370400440532013000",
        "amount": "18453.45",
        "expected_amount": "18453.45",
        "status": "SETTLED",
        "transactions": [
          {
            "tx_id": "0d87d88e-b17a-11ed-9c9d-cc17d418c9e0",
            "reference_type": "SEPA_REFERENCE",
            "reference": "44053201300089370400440532013",
            "amount": "18453.45"
          }
        ]
      }
    ]
  }
}

401 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "Unauthorized",
    "error_text": "The JWT token could not be validated"
  }
}

404 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "NotFound",
    "error_text": "The given object (Order, Trade, ...) could not be found."
  }
}

422 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "ValidationError",
    "error_text": "The request is not valid"
  }
}

500 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "InternalServerError",
    "error_text": "Internal Server Error: the server can currently not process the request"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Settlement Status Response	Inline
401	Unauthorized	Unauthorized	internal_error_type
404	Not Found	Not Found	internal_error_type
422	Unprocessable Entity	Unprocessable Request	internal_error_type
500	Internal Server Error	Internal Server Error	internal_error_type

Response Schema

Status Code 200

Settlement Request Response

Name	Type	Required	Description
» settlement_request_response	object	true	none
»» settlement_request_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»» settlement_request_ref	external_ref_type	false	This field is used by the API user to pass an reference or ID to the tradias system which is used in the tradias system to to act as an reference or ID to the transaction in the API users system.
»» req_header	req_header_type	false	This request header is part of any request creating or modifying an object (order, bulk-order, settlement, …). It consists of two parts, a request ID which will be checked on the tradias side for uniqueness, and an array of user data (tag value). Both parts are option as the complete request header is. The request ID can be used by the API user to allow, that if a request does not answer properly, to sent the request again. If the first one has been processed, then the second one will be rejected with a 409 error and the API user knows that the first request has been processed. If the first request did not make it the second one will be processed normally. The second part is an array of values tagged by a short tag. This data provided by the API user will be returned with the response of the request and if a possible will be added to the object the request relates to and later returned with all responses relating to the object.
»»» req_id	unique_req_type	false	The unique request ID is generated by the API user, it has to be a UUID. It is used to detect that a request has already been processed. If the unique request ID has already been used then the request will not be executed. Instead an error will be (DuplicateReq) reported.
»»» user_data	[object]	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.
»»»» tag	string	true	none
»»»» value	string	true	none
»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» settlement_status	settlement_status_type	true	Status of a settlement. In case the trades in the settlement request are ok and result in the correct amounts, the value will be CONFIRMED. The value switches to “PARTIALLY”, once the transaction has been made and to SETTLED if all transactions have been successfully executed. In case if there is a problem with the settlement its status will be REJECTED. When the settlement request has just been sent the status will be RECEIVED. This status is also been used to reflect the status of each amount (transaction) of a settlement. In this case the state PARTIALLY will not been used.
»» settlement_amounts	[settlement_amount_type]	true	Array containing the individual net amounts of the settlement
»»» Settlement Amount	settlement_amount_type	false	none
»»»» settlement_request_amount_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»»»» currency	asset_code_type	true	Identifier of a leg of an instrument
»»»» from_address	address_type	true	An address to transfer either Fiat money or crypto assets to or from. It is either (for Fiat money) an account number (IBAN) or (for crypto assets) an wallet key. In the case of tradias as recipient or sender the value “BHS” will be used.
»»»» to_address	address_type	true	An address to transfer either Fiat money or crypto assets to or from. It is either (for Fiat money) an account number (IBAN) or (for crypto assets) an wallet key. In the case of tradias as recipient or sender the value “BHS” will be used.
»»»» amount	quantity_type	true	The quantity of a leg.
»»»» expected_amount	quantity_type	true	The quantity of a leg.
»»»» status	settlement_status_type	true	Status of a settlement. In case the trades in the settlement request are ok and result in the correct amounts, the value will be CONFIRMED. The value switches to “PARTIALLY”, once the transaction has been made and to SETTLED if all transactions have been successfully executed. In case if there is a problem with the settlement its status will be REJECTED. When the settlement request has just been sent the status will be RECEIVED. This status is also been used to reflect the status of each amount (transaction) of a settlement. In this case the state PARTIALLY will not been used.
»»»» transactions	[transaction_type]	false	A list of transactions that have been made and associated with this settlement request amount
»»»»» Transaction Data	transaction_type	false	none
»»»»»» tx_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»»»»»» reference_type	transaction_ref_type_type	true	Type of the reference of a transaction
»»»»»» reference	transaction_ref_type	true	This field is used by the API user to pass an reference or ID of a Transaction. It is either the reference field of an FIAT money transaction or in case of a crypto asset transfer the hash or ID of the blockchain transaction.
»»»»»» amount	quantity_type	true	The quantity of a leg.

Enumerated Values

Property	Value
settlement_status	RECEIVED
settlement_status	REJECTED
settlement_status	CONFIRMED
settlement_status	PARTIALLY
settlement_status	SETTLED
status	RECEIVED
status	REJECTED
status	CONFIRMED
status	PARTIALLY
status	SETTLED
reference_type	ON_CHAIN_TX_ID
reference_type	SEPA_REFERENCE
reference_type	SEPA_DESCRIPTION
reference_type	SEPA_END_TO_END_ID

Get Settlement Request

Code samples

import requests
import json

PROTOCOL = "https"
ENVIRONMENT = "preprod"
MY_TOKEN = "ENTER YOUR TOKEN HERE"

settlement_request_id = "13bd7e32-4a43-4112-9002-38c402a2fb11"

URL = f"{PROTOCOL}://api.{ENVIRONMENT}.tradias.link/api/settlement-requests/{settlement_request_id}/status"

rest_api_header = {
    "Authorization": "Bearer " + MY_TOKEN
}

settlement_request_status = requests.get(url=URL, headers=rest_api_header)
print(json.dumps(settlement_request_status.json(), indent=4))

GET /api/settlement-requests/{settlement_request_id}

This endpoint can be used to query information on a settlement request after posting it to the Settlement Request endpoint. Both the Get Settlement Request and Get Settlement Request Status endpoints can be used to query information on a posted settlement request. The difference between the endpoints is that the Get Settlement Request Status returns a more compact response than the Get Settlement Request endpoint. In particular, the Get Settlement Request Status returns some basic information on the settlement request together with the status. The Get Settlement Request endpoint returns all information on the settlement request, including linked transactions. The Get Settlement Request Status is therefore more useful when polling the endpoint to check the processing status or completion of the settlement request.

Parameters

Name	In	Type	Required
settlement_request_id	path	internal_ref_type	true

Example responses

200 Response

{
  "get_settlement_request": {
    "settlement_request_id": "92ec4900-8da5-4700-a28c-2c1f2b32b914",
    "settlement_request_ref": "6aa21c20-ae4b-11ed-b304-81a12bb57b04",
    "req_header": {
      "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
      "user_data": [
        {
          "tag": "Correlation-Id",
          "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
        },
        {
          "tag": "TX-Id",
          "value": "18955457"
        }
      ]
    },
    "timestamp": "1970-01-01T00:00:00.000000Z",
    "settlement_status": "PARTIALLY",
    "trades_ok": [
      "2987a674-fa91-4bcb-b480-24934bc4166c",
      "a83ceb8f-a7cd-46c6-8322-826a21f56511",
      "94f7b459-ae19-4600-8d72-9a21c78b86f4"
    ],
    "settlement_amounts": [
      {
        "settlement_request_amount_id": "99859305-be58-11ed-99a9-ba16c3846fc3",
        "currency": "LTC",
        "from_address": "BHS",
        "to_address": "MGxNPPB7eBoWPUaprtX9v9CXJZoD2465zN",
        "amount": "207.606",
        "expected_amount": "207.606",
        "status": "SETTLED",
        "transactions": [
          {
            "tx_id": "73b0b7f2-bd94-11ed-bef0-ba16c3846fc3",
            "reference": "d8a8b5c19200417cfad98b30423737cad7a27b40bd19bdec89620e953748f189",
            "amount": "207.606"
          }
        ]
      },
      {
        "settlement_request_amount_id": "81a108fc-3181-4e29-a2aa-9464cd77f0fe",
        "currency": "EUR",
        "from_address": "BHS",
        "to_address": "DE89370400440532013000",
        "amount": "12766.04",
        "expected_amount": "12766.04",
        "status": "CONFIRMED"
      },
      {
        "settlement_request_amount_id": "febf879f-11e8-41e1-a909-6438593b154a",
        "currency": "BTC",
        "from_address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
        "to_address": "BHS",
        "amount": "1.23",
        "expected_amount": "1.23",
        "status": "PARTIALLY",
        "transactions": [
          {
            "tx_id": "265a2482-bf2f-11ed-8f96-eac8fe84d40c",
            "reference": "1b82e950aebfd74ab6508538f2138cf4ab0b904a9a3c93ad2df209e5f78d1ea9",
            "amount": "0.6"
          },
          {
            "tx_id": "0d87d88e-b17a-11ed-9c9d-cc17d418c9e0",
            "reference": "2de370af4083d27328ff0036af8b3e577c71cce5eae9e597d3106c2fa54d0b97",
            "amount": "0.5"
          }
        ]
      }
    ]
  }
}

401 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "Unauthorized",
    "error_text": "The JWT token could not be validated"
  }
}

404 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "NotFound",
    "error_text": "The given object (Order, Trade, ...) could not be found."
  }
}

422 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "ValidationError",
    "error_text": "The request is not valid"
  }
}

500 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "InternalServerError",
    "error_text": "Internal Server Error: the server can currently not process the request"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Get Settlement Request	Inline
401	Unauthorized	Unauthorized	internal_error_type
404	Not Found	Not Found	internal_error_type
422	Unprocessable Entity	Unprocessable Request	internal_error_type
500	Internal Server Error	Internal Server Error	internal_error_type

Response Schema

Status Code 200

Get Settlement Request

Name	Type	Required	Description
» get_settlement_request	object	true	none
»» settlement_request_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»» settlement_request_ref	external_ref_type	false	This field is used by the API user to pass an reference or ID to the tradias system which is used in the tradias system to to act as an reference or ID to the transaction in the API users system.
»» req_header	req_header_type	false	This request header is part of any request creating or modifying an object (order, bulk-order, settlement, …). It consists of two parts, a request ID which will be checked on the tradias side for uniqueness, and an array of user data (tag value). Both parts are option as the complete request header is. The request ID can be used by the API user to allow, that if a request does not answer properly, to sent the request again. If the first one has been processed, then the second one will be rejected with a 409 error and the API user knows that the first request has been processed. If the first request did not make it the second one will be processed normally. The second part is an array of values tagged by a short tag. This data provided by the API user will be returned with the response of the request and if a possible will be added to the object the request relates to and later returned with all responses relating to the object.
»»» req_id	unique_req_type	false	The unique request ID is generated by the API user, it has to be a UUID. It is used to detect that a request has already been processed. If the unique request ID has already been used then the request will not be executed. Instead an error will be (DuplicateReq) reported.
»»» user_data	[object]	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.
»»»» tag	string	true	none
»»»» value	string	true	none
»» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
»» settlement_status	settlement_status_type	true	Status of a settlement. In case the trades in the settlement request are ok and result in the correct amounts, the value will be CONFIRMED. The value switches to “PARTIALLY”, once the transaction has been made and to SETTLED if all transactions have been successfully executed. In case if there is a problem with the settlement its status will be REJECTED. When the settlement request has just been sent the status will be RECEIVED. This status is also been used to reflect the status of each amount (transaction) of a settlement. In this case the state PARTIALLY will not been used.
»» trades_unknown	[internal_ref_type]	false	List of all trade_ids from the settlement request which are not known by tradias
»»» Internal Reference or Id	internal_ref_type	false	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»» trades_conflicting	[internal_ref_type]	false	List of all trade_ids from the settlement request which are in a conflicting state with another settlement request, i.e. in a pending settlement state
»»» Internal Reference or Id	internal_ref_type	false	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»» trades_already_settled	[internal_ref_type]	false	List of all trade_ids from the settlement request which have already been settled previously
»»» Internal Reference or Id	internal_ref_type	false	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»» trades_ok	[internal_ref_type]	false	List of all trade_ids from the settlement request which are OK
»»» Internal Reference or Id	internal_ref_type	false	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»» settlement_amounts	[object]	true	Array containing the individual net amounts of the settlement
»»» Settlement Amount	object	false	none
»»»» settlement_request_amount_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»»»» currency	asset_code_type	true	Identifier of a leg of an instrument
»»»» from_address	address_type	true	An address to transfer either Fiat money or crypto assets to or from. It is either (for Fiat money) an account number (IBAN) or (for crypto assets) an wallet key. In the case of tradias as recipient or sender the value “BHS” will be used.
»»»» to_address	address_type	true	An address to transfer either Fiat money or crypto assets to or from. It is either (for Fiat money) an account number (IBAN) or (for crypto assets) an wallet key. In the case of tradias as recipient or sender the value “BHS” will be used.
»»»» amount	quantity_type	true	The quantity of a leg.
»»»» expected_amount	quantity_type	true	The quantity of a leg.
»»»» status	settlement_status_type	true	Status of a settlement. In case the trades in the settlement request are ok and result in the correct amounts, the value will be CONFIRMED. The value switches to “PARTIALLY”, once the transaction has been made and to SETTLED if all transactions have been successfully executed. In case if there is a problem with the settlement its status will be REJECTED. When the settlement request has just been sent the status will be RECEIVED. This status is also been used to reflect the status of each amount (transaction) of a settlement. In this case the state PARTIALLY will not been used.
»»»» transactions	[object]	false	A list of transactions that have been made and associated with this settlement request amount
»»»»» List of Transactions	object	false	none
»»»»»» tx_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»»»»»» reference	transaction_ref_type	true	This field is used by the API user to pass an reference or ID of a Transaction. It is either the reference field of an FIAT money transaction or in case of a crypto asset transfer the hash or ID of the blockchain transaction.
»»»»»» amount	quantity_type	true	The quantity of a leg.

Enumerated Values

Property	Value
settlement_status	RECEIVED
settlement_status	REJECTED
settlement_status	CONFIRMED
settlement_status	PARTIALLY
settlement_status	SETTLED
status	RECEIVED
status	REJECTED
status	CONFIRMED
status	PARTIALLY
status	SETTLED

Get Settlement Transactions

Code samples

import requests
import json

PROTOCOL = "https"
ENVIRONMENT = "preprod"
MY_TOKEN = "ENTER YOUR TOKEN HERE"

URL = f"{PROTOCOL}://api.{ENVIRONMENT}.tradias.link/api/transactions

rest_api_header = {
    "Authorization": "Bearer " + MY_TOKEN
}

params = {
    "from_datetime": "2023-10-20T11:20:21.000000Z",
    "to_datetime": "2023-10-20T15:20:21.000000Z"
}

settlement_request_transactions = requests.get(url=URL, headers=rest_api_header, params=params)
print(json.dumps(settlement_request_transactions.json(), indent=4))

GET /api/transactions

There are two endpoints concerning transactions. The Get Settlement Transactions endpoint can be used to see the transactions and information on the transactions known to the tradias system and belong to the user that queries the endpoint. The Map Transaction With Settlement Request Amount endpoint can be used to map (part of) the amount belonging to the transaction to an existing settlement_request_amount which is in the settlement request.

There are several parameters that can be used for filtering the transactions. The from_datetime and to_datetime are required parameters, the other ones are optional.

Parameters

Name	In	Type	Required
from_datetime	query	timestamp_type	true
to_datetime	query	timestamp_type	true
amount_from	query	quantity_type	false
amount_to	query	quantity_type	false
transaction_id	query	internal_ref_type	false
currency	query	asset_code_type	false
settlement_id	query	internal_ref_type	false
settlement_ref	query	external_ref_type	false
direction	query	direction_type	false
limit	query	integer	false
skip	query	integer	false

Enumerated Values

Parameter	Value
direction	SEND
direction	RECEIVE

Example responses

200 Response

{
  "get_transaction_list": {
    "transactions": [
      {
        "transaction_id": "6aa21c20-ae4b-11ed-b304-81a12bb57b04",
        "transaction_ref": "c8d16891-b669-11ed-bc43-f1002b6e6125",
        "req_header": {
          "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
          "user_data": [
            {
              "tag": "Correlation-Id",
              "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
            },
            {
              "tag": "TX-Id",
              "value": "18955457"
            }
          ]
        },
        "amount": "1.25867895",
        "reference": "a38ca981-b669-11ed-bc43-cb132b8d1265",
        "reference_type": "ON_CHAIN_TX_ID",
        "timestamp": "2019-08-24T14:15:22Z",
        "from_address": "string",
        "to_address": "string",
        "currency": "BTC",
        "settlement_requests": [
          {
            "settlement_request_id": "6aa21c20-ae4b-11ed-b304-81a12bb57b04",
            "settlement_request_amount_id": "6aa21c20-ae4b-11ed-b304-81a12bb57b04",
            "amount": "1.25867895"
          }
        ]
      }
    ],
    "more": true
  }
}

401 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "Unauthorized",
    "error_text": "The JWT token could not be validated"
  }
}

404 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "NotFound",
    "error_text": "The given object (Order, Trade, ...) could not be found."
  }
}

422 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "ValidationError",
    "error_text": "The request is not valid"
  }
}

500 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "InternalServerError",
    "error_text": "Internal Server Error: the server can currently not process the request"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	Inline
401	Unauthorized	Unauthorized	internal_error_type
404	Not Found	Not Found	internal_error_type
422	Unprocessable Entity	Unprocessable Request	internal_error_type
500	Internal Server Error	Internal Server Error	internal_error_type

Response Schema

Status Code 200

Get List of Transactions

Name	Type	Required	Description
» get_transaction_list	object	true	none
»» transactions	[complete_transaction_type]	true	none
»»» Complete Transaction Data	complete_transaction_type	false	none
»»»» transaction_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»»»» transaction_ref	external_ref_type	false	This field is used by the API user to pass an reference or ID to the tradias system which is used in the tradias system to to act as an reference or ID to the transaction in the API users system.
»»»» req_header	req_header_type	false	This request header is part of any request creating or modifying an object (order, bulk-order, settlement, …). It consists of two parts, a request ID which will be checked on the tradias side for uniqueness, and an array of user data (tag value). Both parts are option as the complete request header is. The request ID can be used by the API user to allow, that if a request does not answer properly, to sent the request again. If the first one has been processed, then the second one will be rejected with a 409 error and the API user knows that the first request has been processed. If the first request did not make it the second one will be processed normally. The second part is an array of values tagged by a short tag. This data provided by the API user will be returned with the response of the request and if a possible will be added to the object the request relates to and later returned with all responses relating to the object.
»»»»» req_id	unique_req_type	false	The unique request ID is generated by the API user, it has to be a UUID. It is used to detect that a request has already been processed. If the unique request ID has already been used then the request will not be executed. Instead an error will be (DuplicateReq) reported.
»»»»» user_data	[object]	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.
»»»»»» tag	string	true	none
»»»»»» value	string	true	none
»»»» amount	quantity_type	true	The quantity of a leg.
»»»» reference	transaction_ref_type	true	This field is used by the API user to pass an reference or ID of a Transaction. It is either the reference field of an FIAT money transaction or in case of a crypto asset transfer the hash or ID of the blockchain transaction.
»»»» reference_type	transaction_ref_type_type	true	Type of the reference of a transaction
»»»» timestamp	string(date-time)	true	none
»»»» from_address	address_type	true	An address to transfer either Fiat money or crypto assets to or from. It is either (for Fiat money) an account number (IBAN) or (for crypto assets) an wallet key. In the case of tradias as recipient or sender the value “BHS” will be used.
»»»» to_address	address_type	true	An address to transfer either Fiat money or crypto assets to or from. It is either (for Fiat money) an account number (IBAN) or (for crypto assets) an wallet key. In the case of tradias as recipient or sender the value “BHS” will be used.
»»»» currency	asset_code_type	true	Identifier of a leg of an instrument
»»»» settlement_requests	[object]	true	List of references to settlement requests in which this transaction is used for settlement
»»»»» Settlement Request	object	false	Reference to an amount in a settlement request
»»»»»» settlement_request_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»»»»»» settlement_request_amount_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
»»»»»» amount	quantity_type	true	The quantity of a leg.
»» more	boolean	false	none

Enumerated Values

Property	Value
reference_type	ON_CHAIN_TX_ID
reference_type	SEPA_REFERENCE
reference_type	SEPA_DESCRIPTION
reference_type	SEPA_END_TO_END_ID

Map Transaction With Settlement Request Amount

Code samples

import requests
import json

PROTOCOL = "https"
ENVIRONMENT = "preprod"
MY_TOKEN = "ENTER YOUR TOKEN HERE"

settlement_request_id = "514704a5-848e-4211-a7ce-ec388e122882"

URL = f"{PROTOCOL}://api.{ENVIRONMENT}.tradias.link/api/transactions/{settlement_request_id}"

rest_api_header = {
    "Authorization": "Bearer " + MY_TOKEN
}

settlement_request_transactions = requests.patch(url=URL, headers=rest_api_header, json={
    "settlement_request_amount_id": "76b8c625-d540-42cc-96e4-ee97658d918b",
    "amount": "1151.01"
})

print(json.dumps(settlement_request_transactions.json(), indent=4))

PATCH /api/transaction/{transaction_id}

This endpoint is used to map a transaction to a settlement request amount. Once you have the desired transaction_id, settlement_request_amount_id and the amount from the transaction that you want to map to the settlement request amount, you can combine this information to a request to this endpoint. As a result of this, the transaction is mapped to the settlement request. This will also be visible when querying the Get Settlement Request endpoint.

Body parameter

{
  "settlement_request_amount_id": "dc1be491-9492-46bf-a40b-51e5e69e1473",
  "amount": "51"
}

Parameters

Name	In	Type	Required
transaction_id	path	internal_ref_type	true
body	body	object	true
» settlement_request_amount_id	body	string	true
» amount	body	string	false

Example responses

200 Response

null

401 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "Unauthorized",
    "error_text": "The JWT token could not be validated"
  }
}

403 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "Forbidden",
    "error_text": "Action is forbidden."
  }
}

404 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "NotFound",
    "error_text": "The given object (Order, Trade, ...) could not be found."
  }
}

422 Response

{
  "error_req_header": {
    "req_header": {
      "req_id": "ca57eead-b699-11ed-b3ff-cc17d418c9e0",
      "user_data": [
        {
          "tag": "Correlation-Id",
          "value": "c8d16891-b669-11ed-bc43-f1002b6e6125"
        },
        {
          "tag": "TX-Id",
          "value": "18955457"
        }
      ]
    },
    "tradias_id": "75ccdf76-ae4b-11ed-85ee-81a12bb57b04",
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "UnprocessableEntity",
    "error_text": "The request is not processable"
  }
}

500 Response

{
  "error": {
    "timestamp": "2023-01-20T14:31:10.012123Z",
    "error": "InternalServerError",
    "error_text": "Internal Server Error: the server can currently not process the request"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful Response	Inline
401	Unauthorized	Unauthorized	internal_error_type
403	Forbidden	Forbidden	internal_error_type
404	Not Found	Not Found	internal_error_type
422	Unprocessable Entity	Unprocessable Entity	internal_req_error_type
500	Internal Server Error	Internal Server Error	internal_error_type

Response Schema

Schemas

instrument_type

BTC-EUR/SP

Identifier for an instrument.
It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]

Properties

Name	Type	Required	Description
anonymous	string	false	Identifier for an instrument. It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]

rejection_reason_type

INVALID REQUEST

Rejection Reason

Properties

Name	Type	Required	Description
Rejection Reason	string	false	Message used to describe the reason that a request gets rejected.

rejection_text_type

The format of the request sent is not parseable

Rejection Text

Properties

Name	Type	Required	Description
Rejection Text	string	false	Message used to explain the reason that a request gets rejected.

request_ref_type

TX-1001

Reference to a request

Properties

None

asset_code_type

BTC

Identifier of a leg of an instrument

Properties

Name	Type	Required	Description
anonymous	string	false	Identifier of a leg of an instrument

asset_tenor_type

SP

Identifier of a tenor.
The following tenors are supported * SP = Spot

Properties

Name	Type	Required	Description
anonymous	string	false	Identifier of a tenor. The following tenors are supported * SP = Spot

asset_name_type

Bitcoin

Name of a leg of an instrument

Properties

Name	Type	Required	Description
anonymous	string	false	Name of a leg of an instrument

asset_precision_type

The number of digits after the decimal point which are allowed for a quantity.

Properties

Name	Type	Required	Description
anonymous	integer	false	The number of digits after the decimal point which are allowed for a quantity.

asset_type

name: Bitcoin
code: BTC
precision: 8

Asset

Properties

Name	Type	Required	Description
name	asset_name_type	true	Name of a leg of an instrument
code	asset_code_type	true	Identifier of a leg of an instrument
precision	asset_precision_type	true	The number of digits after the decimal point which are allowed for a quantity.

address_type

string

Fiat Account Number or Crypto Wallet Key

Properties

Name	Type	Required	Description
Fiat Account Number or Crypto Wallet Key	string	false	An address to transfer either Fiat money or crypto assets to or from. It is either (for Fiat money) an account number (IBAN) or (for crypto assets) an wallet key. In the case of tradias as recipient or sender the value “BHS” will be used.

quantity_type

"1.25867895"

Quantity

Properties

Name	Type	Required	Description
Quantity	string	false	The quantity of a leg.

price_type

"23768.63953056"

Price

Properties

Name	Type	Required	Description
Price	string	false	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.

counter_leg_precision_type

999999999999999

Counter leg precision

Properties

Name	Type	Required	Description
Counter leg precision	number	false	This optional key can be given in a new order request. The value specifies the number of decimals you want the computed amount of the leg that is not yet specified in the order request to be rounded to. For example, if you give the amount you want to buy/sell in the leg 2 asset, the counter_leg_precision specifies the number of decimals you want the leg 1 amount to be rounded to. Vice versa, if you specify the amount to buy/sell in the leg 1 asset, the amount in the leg 2 asset will be rounded to the specified number in the counter_leg_precision field.

fiat_amount_type

47118.15

Amount of a Fiat Currency

Properties

Name	Type	Required	Description
Amount of a Fiat Currency	number	false	A positive Fiat Currency amount with 15 digits number and 3 digits decimal fraction. It does not allow negative values.

timestamp_type

1970-01-01T00:00:00.000000Z

Timestamp

Properties

Name	Type	Required	Description
Timestamp	string	false	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”

side_type

BUY

Side (Buy / Sell)

Properties

Name	Type	Required	Description
Side (Buy / Sell)	string	false	The side of the order, seen from the perspective of the API user. * BUY The user sending the order is buying assets * SELL The user sending the order is selling his assets

Enumerated Values

Property	Value
Side (Buy / Sell)	BUY
Side (Buy / Sell)	SELL

unique_req_type

7ac33648-ae4b-11ed-b2f9-81a12bb57b04

Unique Request Id

Properties

Name	Type	Required	Description
Unique Request Id	string	false	The unique request ID is generated by the API user, it has to be a UUID. It is used to detect that a request has already been processed. If the unique request ID has already been used then the request will not be executed. Instead an error will be (DuplicateReq) reported.

external_ref_type

c8d16891-b669-11ed-bc43-f1002b6e6125

External Reference or Id

Properties

Name	Type	Required	Description
External Reference or Id	string	false	This field is used by the API user to pass an reference or ID to the tradias system which is used in the tradias system to to act as an reference or ID to the transaction in the API users system.

internal_ref_type

6aa21c20-ae4b-11ed-b304-81a12bb57b04

Internal Reference or Id

Properties

Name	Type	Required	Description
Internal Reference or Id	string	false	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).

user_data_type

- tag: Correlation-Id
  value: 7ac33648-ae4b-11ed-b2f9-81a12bb57b04
- tag: TX-Id
  value: "18955839"

User Data Array

Properties

Name	Type	Required	Description
User Data Array	[object]	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.
tag	string	true	none
value	string	true	none

req_header_type

req_id: ca57eead-b699-11ed-b3ff-cc17d418c9e0
user_data:
  - tag: Correlation-Id
    value: c8d16891-b669-11ed-bc43-f1002b6e6125
  - tag: TX-Id
    value: "18955457"

Request Header

Properties

Name	Type	Required	Description
req_id	unique_req_type	false	The unique request ID is generated by the API user, it has to be a UUID. It is used to detect that a request has already been processed. If the unique request ID has already been used then the request will not be executed. Instead an error will be (DuplicateReq) reported.
user_data	user_data_type	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.

sequence_type

47110815

Sequence Number

Properties

Name	Type	Required	Description
Sequence Number	integer	false	Sequence number of an order, trade or any other event. A sequence number is assigned to the object (e.g. order) when it is received. All sequence number are unique and increasing. There may be gaps in the sequence numbers assigned! The sequence number can ba used sort objects in the way they have been received/happened. If the maximum is reached the sequence numbers continue with 0.

transaction_ref_type

a38ca981-b669-11ed-bc43-cb132b8d1265

Transaction Reference or Id

Properties

Name	Type	Required	Description
Transaction Reference or Id	string	false	This field is used by the API user to pass an reference or ID of a Transaction. It is either the reference field of an FIAT money transaction or in case of a crypto asset transfer the hash or ID of the blockchain transaction.

transaction_ref_type_type

ON_CHAIN_TX_ID

Transaction Reference Type

Properties

Name	Type	Required	Description
Transaction Reference Type	string	false	Type of the reference of a transaction

Enumerated Values

Property	Value
Transaction Reference Type	ON_CHAIN_TX_ID
Transaction Reference Type	SEPA_REFERENCE
Transaction Reference Type	SEPA_DESCRIPTION
Transaction Reference Type	SEPA_END_TO_END_ID

channel_type

orders

Channel

Properties

Name	Type	Required	Description
Channel	string	false	Name of the websocket channel

Enumerated Values

Property	Value
Channel	orders
Channel	prices
Channel	trades

channel_status_type

ACTIVE

Channel Status

Properties

Name	Type	Required	Description
Channel Status	string	false	Status of the websocket channel

Enumerated Values

Property	Value
Channel Status	ACTIVE
Channel Status	CLOSED

heartbeat_interval_type

Heartbeat Interval (Seconds)

Properties

Name	Type	Required	Description
Heartbeat Interval (Seconds)	integer	false	This optional field defines if the tradias server sends heartbeat messages to the channel or not. The value specifies the interval of the heartbeat messages in seconds. The maximum is 600 seconds (10 minutes). A value of 0 switches the heartbeat message generation off. Zero is the default which means by default there are no heartbeat messages.

subscription_id_type

a38ca981-b669-11ed-bc43-cb132b8d1265

Subscription Id

Properties

Name	Type	Required	Description
Subscription Id	string	false	This field is set by the API user. It’s serves the purpose of identifying the instrument price subscription, it is not unique.

header_type

channel: orders
timestamp: 1970-01-01T00:00:00.000000Z

Message Header

Properties

Name	Type	Required	Description
channel	channel_type	true	Name of the websocket channel
timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”

price_status_type

ACTUAL

Price Status

Properties

Name	Type	Required	Description
Price Status	string	false	The status of a price subscription * ACTUAL: There is an actual price * PARTIAL: There is a reduced set of price levels * UNAVAILABLE: There is actually no price * ERROR: No price available. The subscription failed

Enumerated Values

Property	Value
Price Status	ACTUAL
Price Status	PARTIAL
Price Status	UNAVAILABLE
Price Status	ERROR

order_type_type

MARKET

Order Type

Properties

Name	Type	Required	Description
Order Type	string	false	There are different order types. Currently only the following order types are supported * MARKET: This is a order (without limit). * LIMIT: This is a order with a limit. Buy orders are only executed if the execution price is lower or equal than the limit price. Sell orders are only executed if the execution price is higher or equal than the limit price. * BULK_MARKET: This is a list order where multiple orders are entered as a single bulk. The bulk is either executed completely or not at all.

Enumerated Values

Property	Value
Order Type	MARKET
Order Type	LIMIT
Order Type	BULK_MARKET

time_in_force_type

FOK

Time In Force

Properties

Name	Type	Required	Description
Time In Force	string	false	This order attribute defines the duration a order is active. * FOK: Fill Or Kill is an order which is either completely executed immediately or will be canceled/rejected. * IOC: Immediately Or Cancel is an order which is either executed immediately or will be canceled/rejected. The difference to FOK is that IOC allows partial executions. As tradias always executes completely there is no difference in FOK and IOC orders.

Enumerated Values

Property	Value
Time In Force	FOK
Time In Force	IOC

bulk_order_status_type

RECEIVED

Bulk Order Status

Properties

Name	Type	Required	Description
Bulk Order Status	string	false	The status of a new bulk order is RECEIVED. BULK_MARKET orders will be executed immediately an becomes then either REJECTED if it could not be executed or DONE if it got executed.

Enumerated Values

Property	Value
Bulk Order Status	RECEIVED
Bulk Order Status	REJECTED
Bulk Order Status	DONE

order_status_type

DONE

Order Status

Properties

Name	Type	Required	Description
Order Status	string	false	Orders have a live cycle. The state an order is in that live cycle expressed by its state. The above values are states an order can have in its live cycle. Initially the order is RECEIVED. DUPLICATE, REJECTED, EXPIRED, CANCELLED and DONE are terminal states which will not change any more. UNSPECIFIED means the state is unknown.

Enumerated Values

Property	Value
Order Status	UNSPECIFIED
Order Status	RECEIVED
Order Status	CONFIRMED
Order Status	DUPLICATE
Order Status	REJECTED
Order Status	OPEN
Order Status	UPDATED
Order Status	CANCELLED
Order Status	EXPIRED
Order Status	DONE

trade_leg_status_type

UNSPECIFIED

Trade Leg Status

Properties

Name	Type	Required	Description
Trade Leg Status	string	false	none

Enumerated Values

Property	Value
Trade Leg Status	UNSPECIFIED
Trade Leg Status	PENDING
Trade Leg Status	SETTLED

order_amount_type

leg_1_amount: "1.25"

Order Amount

Properties

Name	Type	Required	Description
leg_1_amount	quantity_type	false	The quantity of a leg.
leg_2_amount	quantity_type	false	The quantity of a leg.

market_order_type

order_ref: "18955839"
instrument: BTC-EUR/SP
side: BUY
amount:
  leg_1_amount: "2.5"
user_data:
  - tag: Correlation-Id
    value: 7ac33648-ae4b-11ed-b2f9-81a12bb57b04
  - tag: TX-Id
    value: "18955839"

Market Order Data

Properties

Name	Type	Required	Description
order_ref	external_ref_type	true	This field is used by the API user to pass an reference or ID to the tradias system which is used in the tradias system to to act as an reference or ID to the transaction in the API users system.
instrument	instrument_type	true	Identifier for an instrument. It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]
side	side_type	true	The side of the order, seen from the perspective of the API user. * BUY The user sending the order is buying assets * SELL The user sending the order is selling his assets
amount	order_amount_type	true	You can specify the amount of an instrument to buy or sell either in the leg_1 or in the leg_2 quantity. If you for example want to buy BTC-EUR you can either define the amount to buy in BTC by specifying the leg_1_amount, or you can specify the amount to spend in EUR by defining the leg_2_amount. Only one of the two legs can be used for a single order!
user_data	user_data_type	false	This object is an array used by the API user to pass data to the tradias system which will be returned back to the API user together with the responses related to the transaction. It can be used by the API user to identify an transaction in a later response.
counter_leg_precision	counter_leg_precision_type	false	This optional key can be given in a new order request. The value specifies the number of decimals you want the computed amount of the leg that is not yet specified in the order request to be rounded to. For example, if you give the amount you want to buy/sell in the leg 2 asset, the counter_leg_precision specifies the number of decimals you want the leg 1 amount to be rounded to. Vice versa, if you specify the amount to buy/sell in the leg 1 asset, the amount in the leg 2 asset will be rounded to the specified number in the counter_leg_precision field.

order_data_type

instrument: BTC-EUR/SP
order_type: LIMIT
time_in_force: FOK
side: BUY
amount:
  leg_1_amount: "2.5"
limit_price: "24650"
arrived_at: 1970-01-01T00:00:00.000000Z
order_status: DONE

Order Data

Properties

Name	Type	Required	Description
instrument	instrument_type	true	Identifier for an instrument. It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]
order_type	order_type_type	true	There are different order types. Currently only the following order types are supported * MARKET: This is a order (without limit). * LIMIT: This is a order with a limit. Buy orders are only executed if the execution price is lower or equal than the limit price. Sell orders are only executed if the execution price is higher or equal than the limit price. * BULK_MARKET: This is a list order where multiple orders are entered as a single bulk. The bulk is either executed completely or not at all.
time_in_force	time_in_force_type	false	This order attribute defines the duration a order is active. * FOK: Fill Or Kill is an order which is either completely executed immediately or will be canceled/rejected. * IOC: Immediately Or Cancel is an order which is either executed immediately or will be canceled/rejected. The difference to FOK is that IOC allows partial executions. As tradias always executes completely there is no difference in FOK and IOC orders.
side	side_type	true	The side of the order, seen from the perspective of the API user. * BUY The user sending the order is buying assets * SELL The user sending the order is selling his assets
amount	order_amount_type	true	You can specify the amount of an instrument to buy or sell either in the leg_1 or in the leg_2 quantity. If you for example want to buy BTC-EUR you can either define the amount to buy in BTC by specifying the leg_1_amount, or you can specify the amount to spend in EUR by defining the leg_2_amount. Only one of the two legs can be used for a single order!
arrived_at	timestamp_type	false	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
limit_price	price_type	false	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
order_status	order_status_type	false	Orders have a live cycle. The state an order is in that live cycle expressed by its state. The above values are states an order can have in its live cycle. Initially the order is RECEIVED. DUPLICATE, REJECTED, EXPIRED, CANCELLED and DONE are terminal states which will not change any more. UNSPECIFIED means the state is unknown.

bulk_execution_type

order:
  order_ref: "18955839"
  instrument: BTC-EUR/SP
  side: BUY
  amount:
    leg_1_amount: "2.5"
  user_data:
    - tag: Correlation-Id
      value: 7ac33648-ae4b-11ed-b2f9-81a12bb57b04
    - tag: TX-Id
      value: "18955839"
order_type: MARKET
time_in_force: FOK
order_status: DONE
leg_1_executed_amount: "1.25867895"
leg_2_executed_amount: "1.25867895"
execution_price: "23768.63953056"
trade_ids:
  - 6aa21c20-ae4b-11ed-b304-81a12bb57b04
executed_at: 1970-01-01T00:00:00.000000Z

Bulk Order Execution

Properties

Name	Type	Required	Description
order	market_order_type	true	This schema represents all information needed for an MARKET order
order_type	order_type_type	true	There are different order types. Currently only the following order types are supported * MARKET: This is a order (without limit). * LIMIT: This is a order with a limit. Buy orders are only executed if the execution price is lower or equal than the limit price. Sell orders are only executed if the execution price is higher or equal than the limit price. * BULK_MARKET: This is a list order where multiple orders are entered as a single bulk. The bulk is either executed completely or not at all.
time_in_force	time_in_force_type	true	This order attribute defines the duration a order is active. * FOK: Fill Or Kill is an order which is either completely executed immediately or will be canceled/rejected. * IOC: Immediately Or Cancel is an order which is either executed immediately or will be canceled/rejected. The difference to FOK is that IOC allows partial executions. As tradias always executes completely there is no difference in FOK and IOC orders.
order_status	order_status_type	true	Orders have a live cycle. The state an order is in that live cycle expressed by its state. The above values are states an order can have in its live cycle. Initially the order is RECEIVED. DUPLICATE, REJECTED, EXPIRED, CANCELLED and DONE are terminal states which will not change any more. UNSPECIFIED means the state is unknown.
leg_1_executed_amount	quantity_type	true	The quantity of a leg.
leg_2_executed_amount	quantity_type	true	The quantity of a leg.
execution_price	price_type	true	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
trade_ids	[internal_ref_type]	false	[This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).]
executed_at	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”

execution_type

trade_id: 6aa21c20-ae4b-11ed-b304-81a12bb57b04
leg_1_executed_amount: "1.25867895"
leg_2_executed_amount: "1.25867895"
execution_price: "23768.63953056"
executed_at: 1970-01-01T00:00:00.000000Z
leg_1_status: UNSPECIFIED
leg_2_status: UNSPECIFIED

Order Execution

Properties

Name	Type	Required	Description
trade_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
leg_1_executed_amount	quantity_type	true	The quantity of a leg.
leg_2_executed_amount	quantity_type	true	The quantity of a leg.
execution_price	price_type	true	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
executed_at	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
leg_1_status	trade_leg_status_type	false	none
leg_2_status	trade_leg_status_type	false	none

trade_type

leg_1_executed_amount: "1.25867895"
leg_2_executed_amount: "1.25867895"
execution_price: "23768.63953056"
executed_at: 1970-01-01T00:00:00.000000Z
leg_1_status: UNSPECIFIED
leg_2_status: UNSPECIFIED

Trade Data

Properties

Name	Type	Required	Description
leg_1_executed_amount	quantity_type	true	The quantity of a leg.
leg_2_executed_amount	quantity_type	true	The quantity of a leg.
execution_price	price_type	true	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
executed_at	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
leg_1_status	trade_leg_status_type	false	none
leg_2_status	trade_leg_status_type	false	none

settlement_status_type

RECEIVED

Settlement Status

Properties

Name	Type	Required	Description
Settlement Status	string	false	Status of a settlement. In case the trades in the settlement request are ok and result in the correct amounts, the value will be CONFIRMED. The value switches to “PARTIALLY”, once the transaction has been made and to SETTLED if all transactions have been successfully executed. In case if there is a problem with the settlement its status will be REJECTED. When the settlement request has just been sent the status will be RECEIVED. This status is also been used to reflect the status of each amount (transaction) of a settlement. In this case the state PARTIALLY will not been used.

Enumerated Values

Property	Value
Settlement Status	RECEIVED
Settlement Status	REJECTED
Settlement Status	CONFIRMED
Settlement Status	PARTIALLY
Settlement Status	SETTLED

direction_type

SEND

Direction (SEND / RECEIVE)

Properties

Name	Type	Required	Description
Direction (SEND / RECEIVE)	string	false	The direction of a transaction, seen from the perspective of the API user. * SEND The user sending money or assets to tradias * RECEIVE The user receiving money or assets from tradias

Enumerated Values

Property	Value
Direction (SEND / RECEIVE)	SEND
Direction (SEND / RECEIVE)	RECEIVE

transaction_type

tx_id: 265a2482-bf2f-11ed-8f96-eac8fe84d40c
reference_type: ON_CHAIN_TX_ID
reference: 1b82e950aebfd74ab6508538f2138cf4ab0b904a9a3c93ad2df209e5f78d1ea9
amount: "1.76"

Transaction Data

Properties

Name	Type	Required	Description
tx_id	internal_ref_type	true	A tradias ID of the transaction
reference_type	transaction_ref_type_type	true	Type of the reference of a transaction
reference	transaction_ref_type	true	This field is used by the API user to pass an reference or ID of a Transaction. It is either the reference field of an FIAT money transaction or in case of a crypto asset transfer the hash or ID of the blockchain transaction.
amount	quantity_type	true	The quantity of a leg.

settlement_amount_type

settlement_request_amount_id: 6aa21c20-ae4b-11ed-b304-81a12bb57b04
currency: BTC
from_address: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq
to_address: BHS
amount: "1.23"
expected_amount: "1.23"
status: PARTIALLY
transactions:
  - tx_id: 265a2482-bf2f-11ed-8f96-eac8fe84d40c
    reference_type: ON_CHAIN_TX_ID
    reference: 1b82e950aebfd74ab6508538f2138cf4ab0b904a9a3c93ad2df209e5f78d1ea9
    amount: "1.00"

Settlement Amount

Properties

Name	Type	Required	Description
settlement_request_amount_id	internal_ref_type	true	Server-side generated unique identifier of the settlement request amount
currency	asset_code_type	true	The currency to which the request amount applies
from_address	address_type	true	An address to transfer either Fiat money or crypto assets to or from. It is either (for Fiat money) an account number (IBAN) or (for crypto assets) an wallet key. In the case of tradias as recipient or sender the value “BHS” will be used.
to_address	address_type	true	An address to transfer either Fiat money or crypto assets to or from. It is either (for Fiat money) an account number (IBAN) or (for crypto assets) an wallet key. In the case of tradias as recipient or sender the value “BHS” will be used.
amount	quantity_type	true	The quantity of a leg.
expected_amount	quantity_type	true	The amount expected by tradias as a result of the trades passed in the corresponding trade list. In order for settlement to go forward, this expected_amount has to agree with the amount field.
status	settlement_status_type	true	Settlement status of the respective settlement request amount. In case amount of the settlement request matches with the amount tradias has calculated the value will be “CONFIRMED” and the value switches to “SETTLED”, once the transaction has been done. In case tradias receives the amount, the status change will happen upon receipt of the amount, in the case tradias sends the amount, the status change happens upon the sending of the amount.
transactions	[transaction_type]	false	A list of transactions that have been made and associated with this settlement request amount

complete_transaction_type

transaction_id: 6aa21c20-ae4b-11ed-b304-81a12bb57b04
transaction_ref: c8d16891-b669-11ed-bc43-f1002b6e6125
req_header:
  req_id: ca57eead-b699-11ed-b3ff-cc17d418c9e0
  user_data:
    - tag: Correlation-Id
      value: c8d16891-b669-11ed-bc43-f1002b6e6125
    - tag: TX-Id
      value: "18955457"
amount: "1.25867895"
reference: a38ca981-b669-11ed-bc43-cb132b8d1265
reference_type: ON_CHAIN_TX_ID
timestamp: 2019-08-24T14:15:22Z
from_address: string
to_address: string
currency: BTC
settlement_requests:
  - settlement_request_id: 6aa21c20-ae4b-11ed-b304-81a12bb57b04
    settlement_request_amount_id: 6aa21c20-ae4b-11ed-b304-81a12bb57b04
    amount: "1.25867895"

Complete Transaction Data

Properties

Name	Type	Required	Description
transaction_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
transaction_ref	external_ref_type	false	This field is used by the API user to pass an reference or ID to the tradias system which is used in the tradias system to to act as an reference or ID to the transaction in the API users system.
req_header	req_header_type	false	This request header is part of any request creating or modifying an object (order, bulk-order, settlement, …). It consists of two parts, a request ID which will be checked on the tradias side for uniqueness, and an array of user data (tag value). Both parts are option as the complete request header is. The request ID can be used by the API user to allow, that if a request does not answer properly, to sent the request again. If the first one has been processed, then the second one will be rejected with a 409 error and the API user knows that the first request has been processed. If the first request did not make it the second one will be processed normally. The second part is an array of values tagged by a short tag. This data provided by the API user will be returned with the response of the request and if a possible will be added to the object the request relates to and later returned with all responses relating to the object.
amount	quantity_type	true	The quantity of a leg.
reference	transaction_ref_type	true	External reference to the transaction. For example an on-chain txid or a reference value in the SEPA reference field.
reference_type	transaction_ref_type_type	true	Reference type of the transaction, specifying the place in which the reference field was passed on some external record (e.g. SEPA transaction)
timestamp	string(date-time)	true	none
from_address	address_type	true	Address from which the amount was sent
to_address	address_type	true	Address on which the amount was received
currency	asset_code_type	true	Identifier of a leg of an instrument
settlement_requests	[object]	true	List of references to settlement requests in which this transaction is used for settlement
» Settlement Request	object	false	Reference to an amount in a settlement request
»» settlement_request_id	internal_ref_type	true	Unique identifier of the settlement request
»» settlement_request_amount_id	internal_ref_type	true	List of settlement request amounts relevant for the settlement mapping of this transaction
»» amount	quantity_type	true	Numerical value used from this transaction to settle the respective settlement request amount.

error_type

NotFound

Error Code

Properties

Name	Type	Required	Description
Error Code	string	false	All error codes returned by this API have a unique code, classifying the error messages.

Enumerated Values

Property	Value
Error Code	Unauthorized
Error Code	InternalServerError
Error Code	Conflict
Error Code	UnprocessableEntity
Error Code	DuplicateReq
Error Code	InvalidOrder
Error Code	MixedOrders
Error Code	InvalidAmount
Error Code	AmountTooLow
Error Code	AmountTooAccurate
Error Code	AmountTooHigh
Error Code	NoPriceStream
Error Code	RiskCheck
Error Code	DuplicateOrderRef
Error Code	NotFound
Error Code	Forbidden
Error Code	ValidationError

error_text_type

The bulk order with the given ID could not be found.

Error Text

Properties

Name	Type	Required	Description
Error Text	string	false	Text describing the Error

internal_error_type

error:
  timestamp: 2023-01-20T14:31:10.012123Z
  error: InternalServerError
  error_text: "Internal Server Error: the server can currently not process the request"

Internal Error Type (for 4xx Results)

Properties

Name	Type	Required	Description
error	object	true	none
» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
» error	error_type	true	All error codes returned by this API have a unique code, classifying the error messages.
» error_text	error_text_type	true	Text describing the Error

internal_req_error_type

error_req_header:
  req_header:
    req_id: ca57eead-b699-11ed-b3ff-cc17d418c9e0
    user_data:
      - tag: Correlation-Id
        value: c8d16891-b669-11ed-bc43-f1002b6e6125
      - tag: TX-Id
        value: "18955457"
  tradias_id: 6aa21c20-ae4b-11ed-b304-81a12bb57b04
  timestamp: 1970-01-01T00:00:00.000000Z
  error: NotFound
  error_text: The bulk order with the given ID could not be found.

Internal Req Error Type (for 4xx Results)

Properties

Name	Type	Required	Description
error_req_header	object	true	none
» req_header	req_header_type	false	This request header is part of any request creating or modifying an object (order, bulk-order, settlement, …). It consists of two parts, a request ID which will be checked on the tradias side for uniqueness, and an array of user data (tag value). Both parts are option as the complete request header is. The request ID can be used by the API user to allow, that if a request does not answer properly, to sent the request again. If the first one has been processed, then the second one will be rejected with a 409 error and the API user knows that the first request has been processed. If the first request did not make it the second one will be processed normally. The second part is an array of values tagged by a short tag. This data provided by the API user will be returned with the response of the request and if a possible will be added to the object the request relates to and later returned with all responses relating to the object.
» tradias_id	internal_ref_type	true	This field is used by tradias to pass an reference or ID to the API User. It is used in the tradias system to to act as an reference or ID to an object (Order, Trade, …).
» timestamp	timestamp_type	true	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”
» error	error_type	true	All error codes returned by this API have a unique code, classifying the error messages.
» error_text	error_text_type	true	Text describing the Error

SubscribePriceChannel

subscribe_price_channel:
  channel: prices
  heartbeat_interval: 30

Subscribe to a Channel

Properties

Name	Type	Required	Description
subscribe_price_channel	object	true	none
» channel	channel_type	true	Name of the websocket channel
» heartbeat_interval	heartbeat_interval_type	false	This optional field defines if the tradias server sends heartbeat messages to the channel or not. The value specifies the interval of the heartbeat messages in seconds. The maximum is 600 seconds (10 minutes). A value of 0 switches the heartbeat message generation off. Zero is the default which means by default there are no heartbeat messages.

UnSubscribeChannel

unsubscribe_channel:
  channel: prices

End the Subscription of a Channel

Properties

Name	Type	Required	Description
unsubscribe_channel	object	true	none
» channel	channel_type	true	Name of the websocket channel

SubscribeInstruments

subscribe_instruments:
  channel: prices
  subscriptions:
    - subscription_id: XX-4567
      instrument: BTC-EUR/SP
      max_frequency: 500
    - subscription_id: TS-BTC
      instrument: BTC-EUR/SP
      mergeable: false
      max_pending: 100
    - subscription_id: XX-4549
      instrument: ETH-EUR/SP
      max_frequency: 500
    - subscription_id: TS-ETH
      instrument: ETH-EUR/SP
      mergeable: false

Subscribe to Instrument Prices

Properties

Name	Type	Required	Description
subscribe_instruments	object	true	none
» channel	channel_type	true	Name of the websocket channel
» subscriptions	[object]	true	Array containing a list of subscriptions
»» Subscription	object	false	none
»»» subscription_id	subscription_id_type	true	This field is set by the API user. It’s serves the purpose of identifying the instrument price subscription, it is not unique.
»»» instrument	instrument_type	true	Identifier for an instrument. It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]
»»» mergeable	boolean	false	none
»»» max_frequency	integer	false	none
»»» max_pending	integer	false	none

UnSubscribeInstruments

unsubscribe_instruments:
  channel: prices
  subscription_ids:
    - XX-4567
    - TS-BTC
    - XX-4549
    - TS-ETH

Un-Subscribe from a Subscription

Properties

Name	Type	Required	Description
unsubscribe_instruments	object	true	none
» channel	channel_type	true	Name of the websocket channel
» subscriptions_ids	[subscription_id_type]	false	Array containing a list of subscriptions to unsubscribe from

SubscribeOrderChannel

subscribe_order_channel:
  channel: orders
  heartbeat_interval: 30

Subscribe to a Order Channel

Properties

Name	Type	Required	Description
subscribe_order_channel	object	true	none
» channel	channel_type	true	Name of the websocket channel
» heartbeat_interval	heartbeat_interval_type	false	This optional field defines if the tradias server sends heartbeat messages to the channel or not. The value specifies the interval of the heartbeat messages in seconds. The maximum is 600 seconds (10 minutes). A value of 0 switches the heartbeat message generation off. Zero is the default which means by default there are no heartbeat messages.

SubscribeTradeChannel

subscribe_trade_channel:
  channel: trades
  heartbeat_interval: 30
  seq_number: 47110815

Subscribe to a Trade Channel

Properties

Name	Type	Required	Description
subscribe_trade_channel	object	true	none
» channel	channel_type	true	Name of the websocket channel
» heartbeat_interval	heartbeat_interval_type	false	This optional field defines if the tradias server sends heartbeat messages to the channel or not. The value specifies the interval of the heartbeat messages in seconds. The maximum is 600 seconds (10 minutes). A value of 0 switches the heartbeat message generation off. Zero is the default which means by default there are no heartbeat messages.
» seq_number	sequence_type	false	Sequence number of an order, trade or any other event. A sequence number is assigned to the object (e.g. order) when it is received. All sequence number are unique and increasing. There may be gaps in the sequence numbers assigned! The sequence number can ba used sort objects in the way they have been received/happened. If the maximum is reached the sequence numbers continue with 0.
» execution_time	timestamp_type	false	Timestamp in UTC Timezone using the following format “%Y-%m-%dT%H:%M:%S.%fZ”

NewOrder

new_order:
  order_ref: c8d16891-b669-11ed-bc43-f1002b6e6125
  req_header:
    req_id: ca57eead-b699-11ed-b3ff-cc17d418c9e0
    user_data:
      - tag: Correlation-Id
        value: c8d16891-b669-11ed-bc43-f1002b6e6125
      - tag: TX-Id
        value: "18955457"
  order_type: LIMIT
  time_in_force: FOK
  instrument: BTC-EUR/SP
  side: BUY
  amount:
    leg_2_amount: "50000"
  limit_price: "24570"

New Order

Properties

Name	Type	Required	Description
new_order	object	true	none
» order_ref	external_ref_type	true	This field is used by the API user to pass an reference or ID to the tradias system which is used in the tradias system to to act as an reference or ID to the transaction in the API users system.
» req_header	req_header_type	false	This request header is part of any request creating or modifying an object (order, bulk-order, settlement, …). It consists of two parts, a request ID which will be checked on the tradias side for uniqueness, and an array of user data (tag value). Both parts are option as the complete request header is. The request ID can be used by the API user to allow, that if a request does not answer properly, to sent the request again. If the first one has been processed, then the second one will be rejected with a 409 error and the API user knows that the first request has been processed. If the first request did not make it the second one will be processed normally. The second part is an array of values tagged by a short tag. This data provided by the API user will be returned with the response of the request and if a possible will be added to the object the request relates to and later returned with all responses relating to the object.
» order_type	order_type_type	true	There are different order types. Currently only the following order types are supported * MARKET: This is a order (without limit). * LIMIT: This is a order with a limit. Buy orders are only executed if the execution price is lower or equal than the limit price. Sell orders are only executed if the execution price is higher or equal than the limit price. * BULK_MARKET: This is a list order where multiple orders are entered as a single bulk. The bulk is either executed completely or not at all.
» time_in_force	time_in_force_type	false	This order attribute defines the duration a order is active. * FOK: Fill Or Kill is an order which is either completely executed immediately or will be canceled/rejected. * IOC: Immediately Or Cancel is an order which is either executed immediately or will be canceled/rejected. The difference to FOK is that IOC allows partial executions. As tradias always executes completely there is no difference in FOK and IOC orders.
» instrument	instrument_type	true	Identifier for an instrument. It consists of the asset codes of the two legs and an optional asset tenor {leg_1_asset} “-” {leg_2_asset} [ “/” {tenor} ]
» side	side_type	true	The side of the order, seen from the perspective of the API user. * BUY The user sending the order is buying assets * SELL The user sending the order is selling his assets
» amount	order_amount_type	true	You can specify the amount of an instrument to buy or sell either in the leg_1 or in the leg_2 quantity. If you for example want to buy BTC-EUR you can either define the amount to buy in BTC by specifying the leg_1_amount, or you can specify the amount to spend in EUR by defining the leg_2_amount. Only one of the two legs can be used for a single order!
» limit_price	price_type	false	The price of a quantity of 1.0 of leg_1 expressed in a leg_2 quantity. For example the instrument “BTC-EUR” the leg_1 is “BTC” and the leg_2 is “EUR”. A price of “23768.63953056” means that you pay 23,768.63953956 EUR for one BTC.
» counter_leg_precision	counter_leg_precision_type	false	This optional key can be given in a new order request. The value specifies the number of decimals you want the computed amount of the leg that is not yet specified in the order request to be rounded to. For example, if you give the amount you want to buy/sell in the leg 2 asset, the counter_leg_precision specifies the number of decimals you want the leg 1 amount to be rounded to. Vice versa, if you specify the amount to buy/sell in the leg 1 asset, the amount in the leg 2 asset will be rounded to the specified number in the counter_leg_precision field.