SDK reference

Client and signing

Generated from mfx-sdk-python 0.9.11·rebuilt on every release

The client signs every request with your private key, applies a retry budget, and opens the stream. Secrets and signing keys render as *** everywhere.

Budget

What the key has left, as of the last answer (X-MFX-Budget-*).

Field	Type	Default	Meaning
remaining	int
source	str		`counted` when it is a measurement, `configured` when it is the key's allowance, `unconfigured` when the key has none. A number whose source is not `counted` is a ceiling, not a reading.

MfxClient

A tenant's connection to MFX.

base_url includes the version: https://api.dev.mfxhub.com/v1.

MfxClient( base_url: str, key_id: str, private_key: SigningKey | Ed25519PrivateKey | str | bytes, *, timeout_s: float = DEFAULT_TIMEOUT_S, read_retries: int = DEFAULT_READ_RETRIES, transport: httpx.AsyncBaseTransport | None = None, sleep: Callable[[float], Awaitable[None]] | None = None, jitter: Callable[[float, float], float] = random.uniform, wall: Callable[[], float] = time.monotonic, ) -> None

Parameter	Type	Default	Description
base_url	str	required	The API root, https://api.mfxhub.com/v1.
key_id	str	required	Your key id, issued with the key.
private_key	SigningKey \| Ed25519PrivateKey \| str \| bytes	required	The private half of your key, shown once at issue. Accepted as a SigningKey or as its text.
timeout_s keyword	float	DEFAULT_TIMEOUT_S
read_retries keyword	int	DEFAULT_READ_RETRIES
transport keyword	httpx.AsyncBaseTransport \| None	None
sleep keyword	Callable[[float], Awaitable[None]] \| None	None
jitter keyword	Callable[[float, float], float]	random.uniform
wall keyword	Callable[[], float]	time.monotonic

Returns None

budget -> Budget | None property

What the key had left when MFX last answered; None before the first answer.

key_id -> str property

base_url -> str property

The REST base this client was pointed at. The stream's host is derived from it.

signature -> MfxSignature property

The signer, so the WebSocket upgrade is signed by the same code as every REST call.

backoff_for(attempt: int) -> float

Jittered exponential backoff for an attempt, with no server-supplied delay in hand.

Parameter	Type	Default	Description
attempt	int	required

Returns float

Exposed so the stream's reconnects and the read path's retries lean on this tenant's quota at the same rate; two backoff policies in one client is one policy nobody tuned.

stream( *, connect: Connector | None = None, url: str | None = None, max_reconnects: int | None = None, ) -> MfxStream

The multiplexed WebSocket stream. Opened with async with.

Parameter	Type	Default	Description
connect keyword	Connector \| None	None	`connect` replaces the transport, which is how a test drives reconnects without a server.
url keyword	str \| None	None
max_reconnects keyword	int \| None	None

Returns MfxStream

connect replaces the transport, which is how a test drives reconnects without a server.

generated -> GeneratedClient property

The generated client, for the endpoint modules. Not part of the public surface.

wall() -> float

This client's clock, so latency is measured the same way everywhere and can be faked.

Returns float

async pause(seconds: float) -> None

This client's sleep — the one the retry policy uses, so a test waits for nothing.

Parameter	Type	Default	Description
seconds	float	required

Returns None

raise_for_answer(response: GeneratedResponse[Any], what: str) -> None

Raise the typed error for a failed answer, for a caller that wants to catch rather than check. execution uses it to turn a refusal into a result rather than an exception.

Parameter	Type	Default	Description
response	GeneratedResponse[Any]	required
what	str	required

Returns None

async read(call: Callable[[], Awaitable[GeneratedResponse[Any]]], what: str) -> Any

Run a generated read and return what the generated core parsed.

Parameter	Type	Default	Description
call	Callable[[], Awaitable[GeneratedResponse[Any]]]	required
what	str	required

Returns Any

async read_raw( call: Callable[[], Awaitable[GeneratedResponse[Any]]], what: str, ) -> GeneratedResponse[Any]

Run a generated read, retrying 429 with the server's own delay.

Parameter	Type	Default	Description
call	Callable[[], Awaitable[GeneratedResponse[Any]]]	required	Each attempt calls `call` again, so it is signed again: a retried request is a new request with a new nonce, never the same bytes twice.
what	str	required

Returns GeneratedResponse[Any]

Each attempt calls call again, so it is signed again: a retried request is a new request with a new nonce, never the same bytes twice.

Returns the whole answer, for the one caller that must read the body itself while the page schemas generate without their contents.

async write(call: Callable[[], Awaitable[GeneratedResponse[Any]]], what: str) -> Any

Run a generated write. Never retried: a retried write is a second order.

Parameter	Type	Default	Description
call	Callable[[], Awaitable[GeneratedResponse[Any]]]	required
what	str	required

Returns Any

async send( call: Callable[[], Awaitable[GeneratedResponse[Any]]], what: str = 'the request', ) -> GeneratedResponse[Any]

One attempt, with transport faults and unreadable answers turned into MFX errors.

Parameter	Type	Default	Description
call	Callable[[], Awaitable[GeneratedResponse[Any]]]	required
what	str	'the request'

Returns GeneratedResponse[Any]

async aclose() -> None

Returns None

SigningKey

A tenant's Ed25519 private key, which renders as *** everywhere it could be printed.

Accepts the key as PEM, as the base64 of its 32 raw bytes, or as an already-loaded Ed25519PrivateKey.

SigningKey(key: Ed25519PrivateKey | str | bytes | SigningKey) -> None

Parameter	Type	Default	Description
key	Ed25519PrivateKey \| str \| bytes \| SigningKey	required

Returns None

sign(message: bytes) -> str

The base64 signature of message.

Parameter	Type	Default	Description
message	bytes	required	The base64 signature of `message`.

Returns str

MfxSignature (httpx.Auth)

Signs every request as it goes out, with a fresh timestamp and nonce each time.

headers_for(method: str, path_with_query: str, body: bytes = b'') -> dict[str, str]

The four headers for one request, with a fresh timestamp and nonce.

Parameter	Type	Default
method	str	required
path_with_query	str	required
body	bytes	b''

Returns dict[str, str]

The WebSocket upgrade is signed through here too, so the stream and every REST call put the same bytes under the same signature. A second implementation for the upgrade is how the two drift until one of them is a 401 nobody can explain.

auth_flow(request: httpx.Request) -> Generator[httpx.Request, httpx.Response, None]

Parameter	Type	Default	Description
request	httpx.Request	required

Returns Generator[httpx.Request, httpx.Response, None]

signing_message()

signing_message( timestamp: str, nonce: str, method: str, path_with_query: str, body: bytes, ) -> bytes

The exact bytes an MFX signature covers — one place, so the client and the tests agree.

Parameter	Type	Default
timestamp	str	required
nonce	str	required
method	str	required
path_with_query	str	required
body	bytes	required

Returns bytes

Raises when the nonce is not ^[A-Za-z0-9_-]{16,64}$. Refusing here rather than sending it is deliberate: the server answers 401 to a bad nonce, and "auth_error" is a poor way to learn that a custom nonce generator emits something with a newline in it.

Secret

A string that renders as *** everywhere except reveal.

Secret(value: str | Secret) -> None

Parameter	Type	Default	Description
value	str \| Secret	required

Returns None

reveal() -> str

The value itself. Every call site is a place a secret can escape — keep them few.

Returns str

SyncMfxClient

The MFX client for code with no event loop. Use it as a context manager::

with SyncMfxClient(base_url, key_id, private_key) as mfx: terminal = mfx.get_terminal(terminal_id)

create_terminal( *, broker_id: Id, server_id: Id, idempotency_key: str, farm_id: Id | None = None, streaming: bool = False, execution: bool = False, instruments: list[str] | None = None, labels: dict[str, str] | None = None, redundancy: Redundancy = 'none', ) -> TenantTerminal

Parameter	Type	Default	Description
broker_id keyword	Id	required	The broker's id from the catalogue.
server_id keyword	Id	required	The server's id from the catalogue.
idempotency_key keyword	str	required	Required on every write and never defaulted. Retrying with the same key returns the original answer; a fresh key asks for a new action.
farm_id keyword	Id \| None	None	Where to place the terminal. Leave it out and the platform chooses; name one to place it deliberately.
streaming keyword	bool	False	Whether this terminal streams market data.
execution keyword	bool	False	Whether this terminal may trade.
instruments keyword	list[str] \| None	None	The broker's own symbol names to subscribe on creation.
labels keyword	dict[str, str] \| None	None	Your own key/value labels on the terminal, for your own filtering.
redundancy keyword	Redundancy	'none'	"none", "active_passive" or "active_active": whether the terminal keeps a warm stand-in.

Returns TenantTerminal

get_terminal(terminal_id: Id) -> TenantTerminal

Parameter	Type	Default	Description
terminal_id	Id	required	The terminal to act on. Another customer's id answers 404, never 403.

Returns TenantTerminal

terminals(*, limit: int | None = None) -> Iterator[TenantTerminal]

Every terminal, following the cursor — as an ordinary iterator.

Parameter	Type	Default	Description
limit keyword	int \| None	None	How many to return at most.

Returns Iterator[TenantTerminal]

Each page is one call; the walk is not read ahead, so a script that stops early has not paid for the rest.

submit_credentials( terminal_id: Id, *, login: int, password: Secret | str, server: str, idempotency_key: str, cred_type: CredentialType = 'master', ) -> CredentialAccepted

Parameter	Type	Default	Description
terminal_id	Id	required	The terminal to act on. Another customer's id answers 404, never 403.
login keyword	int	required	The broker login.
password keyword	Secret \| str	required	The broker password, wrapped in Secret. It travels once and is used by reference.
server keyword	str	required	The broker server name as the broker publishes it.
idempotency_key keyword	str	required	Required on every write and never defaulted. Retrying with the same key returns the original answer; a fresh key asks for a new action.
cred_type keyword	CredentialType	'master'

Returns CredentialAccepted

drain_terminal( terminal_id: Id, *, idempotency_key: str, reason: str | None = None, confirm_open_positions: bool = False, ) -> TenantTerminal

Parameter	Type	Default	Description
terminal_id	Id	required	The terminal to act on. Another customer's id answers 404, never 403.
idempotency_key keyword	str	required	Required on every write and never defaulted. Retrying with the same key returns the original answer; a fresh key asks for a new action.
reason keyword	str \| None	None	Your own words, recorded with the action.
confirm_open_positions keyword	bool	False

Returns TenantTerminal

resume_terminal(terminal_id: Id, *, idempotency_key: str) -> TenantTerminal

Parameter	Type	Default	Description
terminal_id	Id	required	The terminal to act on. Another customer's id answers 404, never 403.
idempotency_key keyword	str	required	Required on every write and never defaulted. Retrying with the same key returns the original answer; a fresh key asks for a new action.

Returns TenantTerminal

retire_terminal(terminal_id: Id, *, idempotency_key: str) -> TenantTerminal

Parameter	Type	Default	Description
terminal_id	Id	required	The terminal to act on. Another customer's id answers 404, never 403.
idempotency_key keyword	str	required	Required on every write and never defaulted. Retrying with the same key returns the original answer; a fresh key asks for a new action.

Returns TenantTerminal

brokers() -> Iterator[TenantBroker]

Returns Iterator[TenantBroker]

servers(broker_id: Id) -> Iterator[TenantBrokerServer]

Parameter	Type	Default	Description
broker_id	Id	required	The broker's id from the catalogue.

Returns Iterator[TenantBrokerServer]

symbols(broker_id: Id) -> Iterator[Symbol]

Parameter	Type	Default	Description
broker_id	Id	required	The broker's id from the catalogue.

Returns Iterator[Symbol]

symbol(broker_id: Id, symbol: str) -> Symbol

Parameter	Type	Default	Description
broker_id	Id	required	The broker's id from the catalogue.
symbol	str	required	The broker's own symbol name, exactly as the catalogue returns it. MFX Hub never renames an instrument.

Returns Symbol

quote(broker_id: Id, symbol: str) -> SymbolQuote

Parameter	Type	Default	Description
broker_id	Id	required	The broker's id from the catalogue.
symbol	str	required	The broker's own symbol name, exactly as the catalogue returns it. MFX Hub never renames an instrument.

Returns SymbolQuote

account(terminal_id: Id) -> Account

Parameter	Type	Default	Description
terminal_id	Id	required	The terminal to act on. Another customer's id answers 404, never 403.

Returns Account

positions(terminal_id: Id) -> PositionList

Parameter	Type	Default	Description
terminal_id	Id	required	The terminal to act on. Another customer's id answers 404, never 403.

Returns PositionList

pending_orders(terminal_id: Id) -> PendingOrderList

Parameter	Type	Default	Description
terminal_id	Id	required	The terminal to act on. Another customer's id answers 404, never 403.

Returns PendingOrderList

deals(terminal_id: Id, *, from_: dt.datetime, to: dt.datetime) -> Iterator[Deal]

Parameter	Type	Default	Description
terminal_id	Id	required	The terminal to act on. Another customer's id answers 404, never 403.
from_ keyword	dt.datetime	required
to keyword	dt.datetime	required

Returns Iterator[Deal]

spread(terminal_id: Id) -> SpreadList

Parameter	Type	Default	Description
terminal_id	Id	required	The terminal to act on. Another customer's id answers 404, never 403.

Returns SpreadList

usage() -> Usage

Returns Usage

candles() -> CandleList

A symbol's bars for a window; see candles.

Returns CandleList

ticks() -> TickList

One read of tick history; see ticks.

Returns TickList

place_order() -> ExecutionResult

Never raises for a refused or failed order — it returns the result, exactly as the async boundary does. A script that treats an exception as "it did not happen" would treat a refusal as a network fault and retry a filled order.

Returns ExecutionResult

cancel_order() -> ExecutionResult

Returns ExecutionResult

modify_order() -> ExecutionResult

Returns ExecutionResult

modify_position() -> ExecutionResult

Returns ExecutionResult

close_position() -> ExecutionResult

Returns ExecutionResult

close_position_by() -> ExecutionResult

Returns ExecutionResult

close_position_partial() -> ExecutionResult

Returns ExecutionResult

get_command() -> ExecutionResult

Returns ExecutionResult

budget -> Any property

What the key had left when MFX last answered.

close() -> None

Close the connections, stop the loop and join its thread. Closing twice is harmless.

Returns None

Page

One page, and the cursor for the next. next_cursor is None on the last.

Field	Type	Default	Meaning
items	list[T]	default_factory=list
next_cursor	str \| None	None
returned	int \| None	None	How many are in THIS page. Not a total, and never to be shown as one.