Best practices

Idempotency keys

Derive the key from your own intent, not from time: "close-" + position_id, not a UUID per attempt. Then a retry after a timeout is safe by construction.

Read results, never catch

Execution methods return a result; ok is false on a timeout, a transport fault and a broker rejection alike, each with a reason. Branch on the reason, not on an exception. A result whose reason is unknown is not a failure and must never be retried: the order may have reached the broker, and reconciliation against the deal history resolves it.

Resume the stream from a sequence

Store the last seq you processed and pass it on reconnect. Treat a gap as data you missed, not as noise.

Wait on conditions, not on time

A terminal that is not ACTIVE after a minute has a condition that says why. Read it, surface it, and act on the ones that are yours (a rejected password) rather than retrying blindly.

Secrets

Wrap every password in Secret and every key in SigningKey. They render as *** everywhere, so a stack trace cannot leak one.

Symbol names

Use your broker’s names exactly as the catalogue returns them. MFX Hub never renames a symbol, so there is nothing to map.

Amounts

Volume, prices and stops are a Decimal, a string or an int. A float is refused, because a float cannot hold a price exactly.

Budgets and backoff

Give the client a budget for retries and honour the backoff it reports. A rate-limit answer carries when to try again.

Two latencies

Log broker_latency_ms and agent_latency_ms separately. When fills slow down you will know whose side it is.