![\"Order](\"/files/domain-order-state-89f9d5f6a4157a69691595f409854246.png\")
Order state diagram.
In the “modules and components” post, we defined the trading port as a gateway\nto exchanges, managing a trading account, placing and canceling orders.
\n--- excerpt ---
\nContinuing the strategy port sub-series, we will now design the trading port.
\n\n\n\n
\n- Market port.
\n- Trading port (this post).
\n- Other strategy ports.
\n
In the modules and components post, we defined the trading port as a gateway\nto exchanges, managing a trading account, placing and canceling orders.
\nWe will do as we did for the market port, that is, start with describing\nthe domain model then proceed to defining the features supporting this\nrepresentation of the world.
\nA trading account is a financial account maintained by an exchange or broker, that represents\nthe funds they hold on behalf of the customer. The customer can use those to trade directly,\nor in the case of more sophisticated instruments, as a collateral securing repayment of\nleveraged positions.
\nAs such, it has a more complex working than the usual deposit account. We shall use the\nfollowing definitions, relevant to our trading project using accounts that support\ntrading on margin:
\nThe amount of each commodity and security owned by the customer. Barring blocked funds\nused as collateral, those are the amounts available for withdrawal.
The total value usable as a collateral for margin positions. It might differ from the total\ncounter-value of asset balances, because not all assets might be usable as a collateral.
On-going trades, where the asset was successfully sold (for short positions) or bought (for\nlong positions) but not yet bought/sold back.
Total counter-value currently blocked as a collateral to open positions.
Current counter-value of the account. That is, the total counter-value of asset balances\nplus/minus any unrealized profits/losses from open positions.
Ratio of equity to used margin. This gives a measure of how exposed the account currently\nis to markets. When this number goes below a certain exchange-specific threshold, it will\nstart forcefully closing loosing positions (a process known as liquidation).
In addition, an account is associated a list of orders, and a ledger that keeps track of\nall fund movements for legal and fiscal proceedings.
\nApart from deposits and withdrawals, which Cryptomate does not care about, all changes on\na trading account are the results of executing orders.
\nEach order represents the intent of the account owner to buy or sell an asset for\nanother. They come in two types:
\nIn addition to their type, orders have a side (buy or sell), total volume to trade,\nexpiration date and for margin trading, the leverage to use.
Once issued, the order follows the following life-cycle:
\nMarket orders follow the same state diagram, except they are executed instantly at the best\npossible value. This leaves no opportunity for cancelling or expiration, and it only remains\nif partially filled state while it is being processed.
\nDuring its life, an order will generate trades. Possibly zero if it gets cancelled, possibly\nmany if it gets matched to a several smaller orders. The exact list of trades is usually\nof little value, but some aggregated statistics are commonly used, most notably:
\n| Name | \nDescription | \n
|---|---|
Executed volume | \nHow much was bought/sold so far. Equals total volume on a closed order. | \n
Cost | \nHow much was spent to buy/sell so far. | \n
Average price | \nCost / executed volume. | \n
Fee | \nTotal amount of fees paid for the trade so far. Ever heard trading is a zero-sum game? Well, not so much. | \n
Cancellation time | \nTime at which the order was cancelled. | \n
Close time | \nTime at which the order got fully filled. | \n
Lastly, it is a common practice to match orders on the same market into positions. This\nlogical grouping makes it possible to easily think about a position in terms of running\nprofits and losses. As this grouping as actually related to a specific way of thinking\nabout the strategy, it will not be handled at the trading port level.
\nAs previously established, the purpose of the trading port is to abstract out\nall the details of connecting to a trading account and using it. That is:
\nSeen from client code, the trading port is straightforward:
\nAccount object back.Account object when no longer needed.Assembling the features and objects described in previous sections, here is the full\nlist of interfaces that, together, constitute the trading port:
\n| Name | \nDescription | \n
|---|---|
Account | \nA valid, opened account on a trading platform. | \n
AccountDescription | \nStatic data granting access to a trading account. | \n
AccountEventHandler | \nCallable that responds to events happening on an account. | \n
Engine | \nMain port entry point. | \n
Order | \nBuy/sell intent. | \n
RuleSet | \nRelevant trading rules for an Account. | \n
Trade | \nA single trade resulting from an order. | \n
For detailed specification of each interface, check their definition and inline documentation\non GitHub. Again, due to the dynamic nature of python, not all interfaces need to\nappear as python types within the code.
\nThat is it for the trading port. You will find the result on GitHub under the trading\ndirectory. In the next post, we will turn to the remaining ports\nof the strategy evaluator, which should be simpler.