Skip to content

API reference ​

This page names every public symbol of the mftik package. The other pages explain how a session uses them. The text is hand-written. It is not generated from docstrings.

A name that starts with one underscore is part of the native module. Strategy code does not call it. Generated protobuf classes live under common, md, and td. Their fields follow the proto files. This page states the mapping and the types that appear in signatures. It does not list every generated field.

Package ​

__version__ is the installed distribution's version. A checkout that has not been installed reports the fallback written next to the package.

run hosts one Strategy until the process exits. It does not return. run(strategy, release=None, *, version="", commit="") sends release as Hello.release when that argument is set. version and commit are the strategy's log fields. Empty strings are still written. They do not change Hello.release. See Install and run.

log is the module-level Log. Use it outside a hook. It does not carry session_id. debug, info, warn, and error take a positional-only message and keyword fields: log.info("msg", key=value). A field value must be a str, int, float, bool, or None. Anything else, including a subclass or a list, raises TypeError. A call below MFTIKO_LOG_LEVEL returns at once without checking the message or the fields, so it raises no TypeError. Lines are JSON objects on stderr. MFTIKO_LOG_LEVEL defaults to info. MFTIKO_LOG_FORMAT=console selects the console layout.

Strategy is the base class. Construct it with no arguments. on_init, on_start, and on_stop are required. The 17 optional hooks are listed in Lifecycle.

topic is the market-data topic strings. volume is read and write for the session directories. main is the entry of python -m mftik.pack. A hook does not call it.

common, md, and td are the proto packages. Each has a v1 submodule: mftik.common.v1, mftik.md.v1, and mftik.td.v1. Importing mftik registers those modules. There is no protobuf dependency, and there is no bytes marshal of these messages.

Context ​

Every hook receives a Context. The methods below raise ContextError outside that hook. Behavior is in Context.

MethodRole
session_idSession id, or empty when the record is absent
logLog for this hook. It carries session_id
paramsThe strategy's parameter bytes
exitRequest outcome DONE
failRequest outcome FAILED and store the reason
volume_dirWritable directory, or empty
input_dirDirectory of one named input, or empty
resolveLook up a universal ticker; only on_init and on_start
infoThe current Info row for a UID this session resolved
submitPlace an Order; returns the client order id
cancelCancel one order by account and client order id
batch_cancelCancel open orders of one algo, optionally limited to UIDs
request_reconAsk for a fresh account snapshot
orderOne of this strategy's orders, or None
open_ordersLive orders of one algo; algo id 0 is every declared algo
positionThe account's position for a UID, or None
balanceThe account's balance of an asset, or None
afterRun a callback on the dispatcher after a delay in seconds
postQueue a callback on the dispatcher
posterThe Poster that may leave the hook
bookA BookView, or None while the book is not synced
tapeAsk for a tape page; the answer is a later callback
book_snapshotAsk for a book snapshot
fetch_klinesAsk for klines of one interval
fetch_open_interestAsk for open interest

after rejects a delay that is negative, NaN, infinite, or too large. The message is delay must be a finite number of seconds >= 0.

submit requires an Order. Any other type raises TypeError (submit() argument must be mftik.Order).

Poster ​

Poster is the only object that may be used from another thread. Poster.post queues a callable. The callable later runs on the dispatcher with a new Context. post drops the callback when the dispatcher is missing or the account buffer is closed. See Threads.

Book view ​

BookView reads the local book inside the hook that called book.

tick_size is the price of one tick. price maps a tick index to a price (tick * tick_size). window is how many ticks the book keeps. best_bid_tick and best_ask_tick return the best tick on that side, or None when the side is empty. qty returns the size at a price. Pass True for the bid side. It returns None when the price is outside the window or the level is empty.

bids and asks return a list of (tick, qty) pairs from the best price outward, at most limit levels. A limit that is not positive returns an empty list. The lists are copies. The view itself does not outlive the hook.

Errors ​

Error is the base of the SDK's context failures. The subclasses are not subclasses of each other.

ExceptionWhen
NotInInitresolve outside on_init and on_start
UnknownUidinfo for a UID this session has not resolved
UnknownAccountThe account is not bound to this session
AlgoNotDeclaredThe algo id is not declared for that account
NoFeedThe session has no such feed
StoppingThe session is already stopping
ReadErrorA read callback's failure. Not raised by the method that sent the request
ContextErrorA Context or BookView used outside its hook

The messages are in Errors and exit codes.

Origin is where an on_order event came from. from_td is 1, local_reject is 2, and timeout is 3. An unknown int raises ValueError. A submit that times out arrives with origin timeout, status unknown, and the SDK does not query the account or send the order again. A missing responder is a local reject.

RejectedRequest is which call an on_reject event refused. cancel is 1 and batch_cancel is 2. An unknown int raises ValueError. A cancel that gets no answer is not reported. Wait for the account event.

Market-data and account values ​

These objects compare with __eq__ and print with __repr__. UniversalTicker also implements __str__, which is venue_category_symbol with _ between the three parts. Bybit_Perp_BTCUSDT is one such string.

Md, Td, BookUpdate, UniversalTicker, Info, Order, and TapeQuery are built with keyword-only __new__. Feed and the account events are built by the runtime. Python code does not construct them.

Md carries uid, md_ts_ns, conn_epoch, and seq. Td carries api_id, incarnation, and seq. Feed carries md and data. data is the decoded proto message for that topic. BookUpdate carries md and exch_ts_ns. Order-book deltas are applied even when on_book is not called. on_book runs when the book is synced and the update is inside the receive window.

OrderEvent carries td, origin, order, cause, code, and reason. order is the account's order message. cause is why the account emitted it. code and reason describe a refusal. The order is stored before on_order runs. Inside that hook, order still returns a terminal order. open_orders omits it. The row is dropped when the hook returns.

FillEvent carries td and fill. A fill does not change what order, position, or balance return. PositionEvent carries td and positions. BalanceEvent carries td and balances. Those rows are stored before the hook runs. ReconEvent carries td and recon. Before on_recon runs, that snapshot is already what order, position, and balance return. A reply to request_recon keeps a local pending-new order that the snapshot omitted when the order was submitted at or after the request. RejectEvent carries td, request, client_order_ids, code, and reason. request says whether the refused call was a cancel or a batch cancel. client_order_ids are the ids the refusal names.

Instruments ​

UniversalTicker is keyword-only: venue, category, and symbol. Parsing a string is strict. The three parts are required.

Info is one symbol-service row. ticker is required at construction. The other fields default.

Field or methodMeaning
uidInstrument id. Zero is not a valid id
tickerThe universal ticker
exch_tickerThe venue's own symbol text
baseBase currency
quoteQuote currency
contract_sizeContract size
contract_value_ccyCurrency of the contract value
price_ccyCurrency of the price
settleSettlement currency
expiry_nsExpiry, nanoseconds, or zero
strikeOption strike
option_typeC, P, or empty
statusPRELISTING, TRADABLE, HALTED, SETTLING, EXPIRED, DELISTED, UNKNOWN, or empty when unspecified
filtersA new dict on each read. Known keys include price_tick, qty_step, min_qty, max_qty, min_notional, max_notional, min_price, and max_price
updated_at_nsWhen the row was updated, nanoseconds
is_tradableTrue only when status is TRADABLE
price_tickThe price_tick filter, or 0.0 when that filter is absent. NaN stays NaN
linearsettle is quote, contract_value_ccy is base, price_ccy is quote, and base and quote are both set
inversebase and quote differ, settle is base, contract_value_ccy is quote, and price_ccy is quote
quantosettle is set and is neither base nor quote. The other margin flags are false
coin_marginedsettle is set and equals base
u_marginedsettle is set, is not base, and the row is not quanto

resolve of an unknown ticker raises Error. The message starts with symbol: no such instrument:.

Orders and tape queries ​

Order is keyword-only and frozen. params is copied. A NaN qty, quote_qty, or price is stored as None.

FieldMeaning
api_idAccount
algo_idAlgo declared for that account
uidInstrument
sideRead back as the proto enum
order_typeRead back as the proto enum
tifTime in force, read back as the proto enum
qtyBase quantity, or None
quote_qtyQuote quantity, or None
priceLimit price, or None
recv_window_msReceive window for this order, milliseconds
reduce_onlyWhether the order may only reduce a position
paramsString pairs copied onto the order

An int that is not a stored enumerator can sit on side, order_type, or tif. submit then raises ValueError. A bool in one of those fields raises TypeError at construction. See Errors and exit codes.

The client order id is a decimal of version, algo id, millisecond timestamp, and sequence. The version is 1. One counter serves the process. An undeclared algo raises AlgoNotDeclared and takes no id.

TapeQuery is keyword-only. limit is how many events to return. before is a Cursor or None. since_ns is the oldest exchange time to include, nanoseconds. The callback is (ctx, value, err). A callback that is not callable raises TypeError before the request is sent. The number of parameters is not checked until the callback runs.

Topics ​

topic does not build NATS subjects. The values are the topic strings the runtime subscribes to.

NameValue
BEST_QUOTEbestquote
TRADEtrade
AGG_TRADEaggtrade
ORDER_BOOK_DELTAorderbook_delta
TICKERticker
LIQUIDATIONliquidation
FUNDING_RATEfunding_rate
OPEN_INTERESTopen_interest
GREEKSgreeks
MARK_PRICEmark_price

kline takes an interval and returns kline_ plus that interval. kline("1m") is kline_1m. kline("") is kline_.

Volume ​

read looks in the volume directory, then the input directory, and returns bytes or None. write replaces one file atomically. See Volume and inputs.

volume_read and volume_write are the same operations on the native module. Strategy code calls read and write.

Pack ​

main parses the pack command and pushes the image. The printed digest is StrategyRef.code. The manifest's contract list comes from session_contracts: worker.v1, stsctl.v1, md.v1, and td.v1. See Pack and deploy.

Native module ​

These names are on mftik._mftik. They are how the interpreter entry and the packer reach the runtime. A strategy does not call them.

_run hosts a strategy until the process exits. run calls it after it has resolved the release string.

_run_load_failed is the path that still speaks Hello and ends INIT_FAILED when module:Class cannot be loaded. The error text is the argument.

_registered_hooks returns the optional hook names the class overrides. The decision matches registration: a method counts when type(strategy).on_x is not Strategy.on_x.

session_contracts returns the contract names a worker Hello and a packed manifest both list.

Proto messages ​

Messages and enums under common, md, and td are frozen. Field names match the proto files. Python code does not construct a message. Calling one raises TypeError.

An unset message field is None. Each arm of a oneof is its own attribute, None when another arm is set. The attribute whose name is the proto oneof returns the selected arm's name, or None when none is set. A repeated field is a tuple. A map field is a new dict on each read.

Proto enums keep an unknown int and reject a bool with ValueError (bool is not an enum value). Origin and RejectedRequest reject both.

Types that show up in the signatures above:

TypeWhere
Side, OrderType, TimeInForcemftik.common.v1, read from an Order
OrderCausemftik.td.v1, the cause of an OrderEvent
Balance, Fill, Position, Reconmftik.td.v1, account snapshots and events
BookSnapshot, TapePage, Klines, Cursor, OpenInterestmftik.md.v1, read replies and TapeQuery.before
BestQuote, Trademftik.md.v1, the data of those feeds

The account Order message is mftik.td.v1.Order. It is not mftik.Order, which is the order a strategy submits.

mftik v1.1.0