fxsocket 0.4.0__tar.gz → 0.6.0__tar.gz

{fxsocket-0.4.0 → fxsocket-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: fxsocket
-Version: 0.4.0
+Version: 0.6.0
 Summary: Python SDK for the FxSocket API — MT4/MT5 account management, trading, and real-time streaming.
 Project-URL: Homepage, https://fxsocket.com
 Project-URL: Documentation, https://api.fxsocket.com/v1/docs
@@ -42,7 +42,12 @@ interfaces.
 - **Account management** — link, list, fetch, and disconnect MT4/MT5 accounts.
 - **Private servers** — list your dedicated hosting servers and manage the
   accounts on them.
+- **Read-only keys** — mint, scope, rotate and revoke `fxs_ro_…` keys for
+  dashboards and monitors.
 - **Trading** — market & pending orders, modify, close, close-all, plus margin/profit calculators.
+- **Multi-account trading** — one order, or one close, fanned out to several
+  accounts in a single request, with idempotency keys for safe retries.
+- **Wallet** — read your prepaid balance, pending top-ups and upcoming charges.
 - **Market data** — quotes, symbol specifications (incl. commission rules & trading
   sessions), OHLC history, account state & info.
 - **Live streaming** — ticks, bars, account, positions, trades, and terminal status
@@ -104,9 +109,28 @@ with Client(api_key="fxs_live_…") as fx:
     # Where this account's terminal API lives (empty until provisioned).
     print(account.rest_url, account.ws_url)
 
+    # Move the trade expert to a specific chart symbol (the terminal
+    # restarts on it — poll until connected again). "" reverts to automatic.
+    account = fx.accounts.update(account, trade_ea_symbol="EURUSDm")
+
     fx.accounts.delete(account.id)         # unlink
 ```
 
+An account's terminal can be routed through an outbound proxy at link time.
+The proxy is verified first — an unreachable one raises `ConnectFailedError`
+with `code == "proxy_unreachable"` and nothing is created. The address, type
+and local port are readable on the `Account`; the credentials never come
+back.
+
+```python
+account = fx.accounts.create(
+    server="ICMarkets-Demo", login=1150125, password="…",
+    trade_ea_symbol="EURUSDm",                 # optional, broker-exact
+    proxy_address="10.0.0.5:1080", proxy_type="socks5",
+    proxy_auth="user:secret", proxy_local_port=1080,
+)
+```
+
 Everything is also available on `AsyncClient`:
 
 ```python
@@ -116,6 +140,36 @@ async with AsyncClient(api_key="fxs_live_…") as fx:
     accounts = await fx.accounts.list()
 ```
 
+## Read-only keys
+
+A read-only key (`fxs_ro_…`) can call every GET endpoint but nothing that
+mutates state. `fx.readonly_keys` manages named ones; each has a `scope` —
+`all` sees every account, `selected` only the accounts attached to it
+(everything else is absent from lists, 404 by id and 401 at the terminal).
+Passing `accounts` implies `selected`.
+
+```python
+from fxsocket import Client, KeyScope
+
+with Client(api_key="fxs_live_…") as fx:
+    key = fx.readonly_keys.create(name="dashboard", accounts=[account])
+    print(key.key)                          # plaintext, returned on every read
+
+    key = fx.readonly_keys.update(key, name="ops-dashboard")
+    key = fx.readonly_keys.rotate(key)      # new secret, same name & scope
+    fx.readonly_keys.delete(key)            # revoke — immediate, irreversible
+
+    for k in fx.readonly_keys.list():
+        print(k.name, k.scope == KeyScope.ALL, k.last_used_at)
+```
+
+Terminals are started with the exact set of read-only keys they accept, so
+creating, re-scoping, rotating or revoking a key **restarts the terminals of
+every account in its scope** — each goes briefly offline, typically a few
+minutes. Renaming is free. Key management itself always needs the full
+`fxs_live_…` key, even for reads, because the replies contain plaintext
+key values.
+
 ## Trading & market data
 
 `fx.terminal(account)` returns a REST client bound to that account's terminal
@@ -186,6 +240,86 @@ MT4 and MT5 share one interface. MT5-only timeframes (`M2`, `M3`, `H2`, `H6`,
 > hasn't loaded that history. Calling `price_history(symbol, timeframe)` without
 > date bounds returns the most recent bars reliably.
 
+## Multi-account trading
+
+`fx.orders` sends one order — or one close — to several accounts in a single
+request, through the management API rather than each terminal. Every leg
+inherits `defaults` and may override any of it, so "same trade, three
+accounts, three lot sizes" stays short. A leg can be an `OrderLeg`, a plain
+dict, or just the account (object or id) when `defaults` say everything else.
+
+```python
+from fxsocket import Client, OrderDefaults, OrderLeg
+
+with Client(api_key="fxs_live_…") as fx:
+    accounts = [a for a in fx.accounts.list() if a.has_terminal]
+
+    result = fx.orders.send(
+        [OrderLeg(account_id=a, volume=0.1 * (i + 1)) for i, a in enumerate(accounts)],
+        defaults=OrderDefaults(symbol="EURUSD", operation="buy", stop_loss=1.07),
+        idempotency_key="signal-4711",
+    )
+    for account, leg in zip(accounts, result.results):
+        print(account.nickname, leg.status, leg.order, leg.message)
+```
+
+**Validation is all-or-nothing, execution is not.** A malformed leg raises
+`ValidationError` before anything is sent (the SDK checks what the API
+checks — symbol / operation / volume present, a price for pending orders,
+…). Once dispatched the legs are independent: you get a `BatchOrderResult`
+with a positional `results` list — `zip` it with what you sent rather than
+matching on `account_id`, which repeats when several legs target one
+account. Each `OrderLegResult.status` is only trustworthy as `filled`; a
+`timeout` leg *may* have executed (`is_unknown`), so never blind-retry it.
+`result.all_filled`, `filled_legs`, `failed_legs` and `unknown_legs` roll
+this up.
+
+Symbols are per broker (`EURUSD`, `EURUSD.sd`, `EURUSDm`), so a single
+`defaults` symbol across mixed brokers will partly fail by design — that is
+what a leg-level `symbol` is for.
+
+**Idempotency.** Pass an `idempotency_key` (any opaque string, ≤ 128 chars)
+whenever a retry is possible: replaying the identical batch with the same
+key returns the stored reply (`idempotent_replay=True`) and sends nothing.
+Keys are remembered for 15 minutes. A key that is still in flight, was
+already used for a different body, or can't currently be guaranteed raises
+`IdempotencyError` — nothing is sent in any of those cases.
+
+Closing works by **selector**, not by ticket: each account is matched
+against `symbol` (plus optional `side`, `kind`, `magic`), the backend
+resolves the tickets from that account's open orders and closes them.
+`symbol` is required — type `"*"` to mean every symbol; it is never implied.
+`symbol_match="base"` lets one selector reach `EURUSD`, `EURUSD.sd` and
+`EURUSDm` across brokers. `kind` defaults to `position`, so a routine close
+does not also delete resting pending orders.
+
+```python
+from fxsocket import CloseDefaults, CloseLeg
+
+closed = fx.orders.close(
+    [
+        CloseLeg(account_id=accounts[0], side="long", volume=0.05),   # partial
+        CloseLeg(account_id=accounts[1], tickets=[123456, 123457]),  # explicit
+        accounts[2],                                                 # defaults only
+    ],
+    defaults=CloseDefaults(symbol="EURUSD", symbol_match="base"),
+    idempotency_key="flatten-4711",
+)
+for leg in closed.results:
+    print(leg.account_id, leg.status, f"{leg.closed}/{leg.matched}")
+    for ticket in leg.results:
+        print("   ", ticket.ticket, ticket.status, ticket.retcode_description)
+```
+
+`nothing_matched` is a normal answer, not an error. Per-account `status`
+compares against `CloseLegStatus` and per-ticket against
+`ClosedTicketStatus`; `skipped` tickets were never sent, `timeout` ones may
+well have closed. An `idempotency_key` matters most for partial closes,
+where a blind retry genuinely over-closes.
+
+Both calls need the full `fxs_live_…` key — a read-only key raises
+`ForbiddenError`.
+
 ## Streaming (WebSocket)
 
 Subscribe to live ticks, bars, account, positions, trades, and terminal status.
@@ -229,6 +363,35 @@ with Client(api_key="fxs_live_…") as fx:
                 print(event.data.bid, event.data.ask)
 ```
 
+### Trade events
+
+A `TradeUpdate` carries the full deal: `commission`, `swap`, `magic` and a
+real `comment` alongside `profit` (bridges MT5 0.12+ / MT4 0.11+; zero on
+older pods). Event-only P&L accounting is `data.net_profit`
+(`profit + commission + swap`).
+
+Correlate the `In` and `Out` events of one round-trip through
+`data.position` — on MT5, `Out` deals carry `magic=0` / `comment=""` unless
+the closing request set them (platform behavior, not a bridge gap), so
+position id is the reliable join key. On MT4, `deal` is always 0 and
+`position` equals the order ticket. The same id appears as `position` in
+`order_history()` rows (bridges MT5 0.14+ / MT4 0.13+) and as
+`position_id` in `position_history()`.
+
+If the bridge can't fully enrich an event in time it sets
+`data.degraded=True`: identifiers, `symbol`, `type`, `volume` and `price`
+are still trustworthy, but `entry` is `"Unknown"` and the cost fields are
+zeroed — reconcile that deal via `order_history()`.
+
+```python
+async for event in s:
+    match event:
+        case TradeUpdate() as t if t.data.degraded:
+            reconcile_later(t.data.position)     # costs/entry unreliable
+        case TradeUpdate() as t if t.data.entry == DealEntry.OUT:
+            print(t.data.position, "closed, net", t.data.net_profit)
+```
+
 ## Errors
 
 Every failure raises a subclass of `fxsocket.FxSocketError`:
@@ -236,22 +399,30 @@ Every failure raises a subclass of `fxsocket.FxSocketError`:
 | Exception | When |
 |---|---|
 | `AuthError` | missing/invalid API key |
+| `ForbiddenError` | key not allowed to do this (read-only key on a mutating call) |
 | `RateLimitError` | rate limited (`.retry_after`) |
-| `ValidationError` | malformed request |
+| `ValidationError` | malformed request (`.code`: `invalid_batch`, `unknown_account`, …) |
+| `IdempotencyError` | batch refused because of its `Idempotency-Key` (`.code`) |
 | `NotFoundError` | account/resource not found |
+| `PaymentRequiredError` | base for every 402 below (plan / balance doesn't allow it) |
 | `AccountCapError` | plan account limit reached (`.cap`, `.current`) |
+| `NoSubscriptionError` | no plan permits linking accounts |
+| `InsufficientBalanceError` | prepaid balance too low (`.shortfall_eur_cents`, `.shortfall_eur`) |
+| `SeatLapsedError` | seats lapsed, existing accounts unseated — renew first |
 | `DuplicateAccountError` | account already linked |
 | `ConnectFailedError` | broker rejected the login |
 | `TerminalNotReadyError` | terminal not provisioned / not ready |
 | `UnsupportedOnPlatformError` | feature not available on this platform |
 
 ```python
-from fxsocket import Client, AccountCapError
+from fxsocket import Client, AccountCapError, InsufficientBalanceError
 
 try:
     fx.accounts.create(server="Demo", login=1, password="…")
 except AccountCapError as e:
     print(f"Plan limit reached: {e.current}/{e.cap}")
+except InsufficientBalanceError as e:
+    print(f"Top up {e.shortfall_eur} EUR first")   # None if the API gave no figure
 ```
 
 ## Private hosting
@@ -292,6 +463,28 @@ it with `Client(..., verify_terminal_tls=False)` (or supply a pinned CA).
 *Purchasing* a server, canceling, and slot changes happen in the dashboard;
 the API deliberately exposes no billing operations.
 
+## Wallet
+
+`fx.wallet.get()` is a read-only view of your prepaid balance: what is in
+it, top-ups that haven't landed yet, and what the balance will pay for over
+the next 30 days (account seats and balance-funded private servers
+together). Amounts are integer EUR cents; the `*_eur` properties give
+`Decimal` euros.
+
+```python
+wallet = fx.wallet.get()
+print(f"balance {wallet.balance_eur} EUR, covers next 30 days: {wallet.covers_upcoming}")
+for charge in wallet.upcoming:
+    print(f"  {charge.when:%Y-%m-%d} {charge.kind:6} {charge.label} {charge.amount_eur} EUR")
+if not wallet.covers_upcoming:
+    print(f"top up at least {wallet.shortfall_eur} EUR")
+```
+
+Affordability is cumulative — with 24 EUR and three 12 EUR renewals the
+first two are covered and the third is not — so `shortfall_eur` is the
+total gap, not the size of any single charge. Topping up happens in the
+dashboard; the SDK deliberately exposes no payment operations.
+
 ## Timestamps
 
 Terminal timestamps (`quote.time`, candle `time`, order times) are returned as

{fxsocket-0.4.0 → fxsocket-0.6.0}/README.md

@@ -15,7 +15,12 @@ interfaces.
 - **Account management** — link, list, fetch, and disconnect MT4/MT5 accounts.
 - **Private servers** — list your dedicated hosting servers and manage the
   accounts on them.
+- **Read-only keys** — mint, scope, rotate and revoke `fxs_ro_…` keys for
+  dashboards and monitors.
 - **Trading** — market & pending orders, modify, close, close-all, plus margin/profit calculators.
+- **Multi-account trading** — one order, or one close, fanned out to several
+  accounts in a single request, with idempotency keys for safe retries.
+- **Wallet** — read your prepaid balance, pending top-ups and upcoming charges.
 - **Market data** — quotes, symbol specifications (incl. commission rules & trading
   sessions), OHLC history, account state & info.
 - **Live streaming** — ticks, bars, account, positions, trades, and terminal status
@@ -77,9 +82,28 @@ with Client(api_key="fxs_live_…") as fx:
     # Where this account's terminal API lives (empty until provisioned).
     print(account.rest_url, account.ws_url)
 
+    # Move the trade expert to a specific chart symbol (the terminal
+    # restarts on it — poll until connected again). "" reverts to automatic.
+    account = fx.accounts.update(account, trade_ea_symbol="EURUSDm")
+
     fx.accounts.delete(account.id)         # unlink
 ```
 
+An account's terminal can be routed through an outbound proxy at link time.
+The proxy is verified first — an unreachable one raises `ConnectFailedError`
+with `code == "proxy_unreachable"` and nothing is created. The address, type
+and local port are readable on the `Account`; the credentials never come
+back.
+
+```python
+account = fx.accounts.create(
+    server="ICMarkets-Demo", login=1150125, password="…",
+    trade_ea_symbol="EURUSDm",                 # optional, broker-exact
+    proxy_address="10.0.0.5:1080", proxy_type="socks5",
+    proxy_auth="user:secret", proxy_local_port=1080,
+)
+```
+
 Everything is also available on `AsyncClient`:
 
 ```python
@@ -89,6 +113,36 @@ async with AsyncClient(api_key="fxs_live_…") as fx:
     accounts = await fx.accounts.list()
 ```
 
+## Read-only keys
+
+A read-only key (`fxs_ro_…`) can call every GET endpoint but nothing that
+mutates state. `fx.readonly_keys` manages named ones; each has a `scope` —
+`all` sees every account, `selected` only the accounts attached to it
+(everything else is absent from lists, 404 by id and 401 at the terminal).
+Passing `accounts` implies `selected`.
+
+```python
+from fxsocket import Client, KeyScope
+
+with Client(api_key="fxs_live_…") as fx:
+    key = fx.readonly_keys.create(name="dashboard", accounts=[account])
+    print(key.key)                          # plaintext, returned on every read
+
+    key = fx.readonly_keys.update(key, name="ops-dashboard")
+    key = fx.readonly_keys.rotate(key)      # new secret, same name & scope
+    fx.readonly_keys.delete(key)            # revoke — immediate, irreversible
+
+    for k in fx.readonly_keys.list():
+        print(k.name, k.scope == KeyScope.ALL, k.last_used_at)
+```
+
+Terminals are started with the exact set of read-only keys they accept, so
+creating, re-scoping, rotating or revoking a key **restarts the terminals of
+every account in its scope** — each goes briefly offline, typically a few
+minutes. Renaming is free. Key management itself always needs the full
+`fxs_live_…` key, even for reads, because the replies contain plaintext
+key values.
+
 ## Trading & market data
 
 `fx.terminal(account)` returns a REST client bound to that account's terminal
@@ -159,6 +213,86 @@ MT4 and MT5 share one interface. MT5-only timeframes (`M2`, `M3`, `H2`, `H6`,
 > hasn't loaded that history. Calling `price_history(symbol, timeframe)` without
 > date bounds returns the most recent bars reliably.
 
+## Multi-account trading
+
+`fx.orders` sends one order — or one close — to several accounts in a single
+request, through the management API rather than each terminal. Every leg
+inherits `defaults` and may override any of it, so "same trade, three
+accounts, three lot sizes" stays short. A leg can be an `OrderLeg`, a plain
+dict, or just the account (object or id) when `defaults` say everything else.
+
+```python
+from fxsocket import Client, OrderDefaults, OrderLeg
+
+with Client(api_key="fxs_live_…") as fx:
+    accounts = [a for a in fx.accounts.list() if a.has_terminal]
+
+    result = fx.orders.send(
+        [OrderLeg(account_id=a, volume=0.1 * (i + 1)) for i, a in enumerate(accounts)],
+        defaults=OrderDefaults(symbol="EURUSD", operation="buy", stop_loss=1.07),
+        idempotency_key="signal-4711",
+    )
+    for account, leg in zip(accounts, result.results):
+        print(account.nickname, leg.status, leg.order, leg.message)
+```
+
+**Validation is all-or-nothing, execution is not.** A malformed leg raises
+`ValidationError` before anything is sent (the SDK checks what the API
+checks — symbol / operation / volume present, a price for pending orders,
+…). Once dispatched the legs are independent: you get a `BatchOrderResult`
+with a positional `results` list — `zip` it with what you sent rather than
+matching on `account_id`, which repeats when several legs target one
+account. Each `OrderLegResult.status` is only trustworthy as `filled`; a
+`timeout` leg *may* have executed (`is_unknown`), so never blind-retry it.
+`result.all_filled`, `filled_legs`, `failed_legs` and `unknown_legs` roll
+this up.
+
+Symbols are per broker (`EURUSD`, `EURUSD.sd`, `EURUSDm`), so a single
+`defaults` symbol across mixed brokers will partly fail by design — that is
+what a leg-level `symbol` is for.
+
+**Idempotency.** Pass an `idempotency_key` (any opaque string, ≤ 128 chars)
+whenever a retry is possible: replaying the identical batch with the same
+key returns the stored reply (`idempotent_replay=True`) and sends nothing.
+Keys are remembered for 15 minutes. A key that is still in flight, was
+already used for a different body, or can't currently be guaranteed raises
+`IdempotencyError` — nothing is sent in any of those cases.
+
+Closing works by **selector**, not by ticket: each account is matched
+against `symbol` (plus optional `side`, `kind`, `magic`), the backend
+resolves the tickets from that account's open orders and closes them.
+`symbol` is required — type `"*"` to mean every symbol; it is never implied.
+`symbol_match="base"` lets one selector reach `EURUSD`, `EURUSD.sd` and
+`EURUSDm` across brokers. `kind` defaults to `position`, so a routine close
+does not also delete resting pending orders.
+
+```python
+from fxsocket import CloseDefaults, CloseLeg
+
+closed = fx.orders.close(
+    [
+        CloseLeg(account_id=accounts[0], side="long", volume=0.05),   # partial
+        CloseLeg(account_id=accounts[1], tickets=[123456, 123457]),  # explicit
+        accounts[2],                                                 # defaults only
+    ],
+    defaults=CloseDefaults(symbol="EURUSD", symbol_match="base"),
+    idempotency_key="flatten-4711",
+)
+for leg in closed.results:
+    print(leg.account_id, leg.status, f"{leg.closed}/{leg.matched}")
+    for ticket in leg.results:
+        print("   ", ticket.ticket, ticket.status, ticket.retcode_description)
+```
+
+`nothing_matched` is a normal answer, not an error. Per-account `status`
+compares against `CloseLegStatus` and per-ticket against
+`ClosedTicketStatus`; `skipped` tickets were never sent, `timeout` ones may
+well have closed. An `idempotency_key` matters most for partial closes,
+where a blind retry genuinely over-closes.
+
+Both calls need the full `fxs_live_…` key — a read-only key raises
+`ForbiddenError`.
+
 ## Streaming (WebSocket)
 
 Subscribe to live ticks, bars, account, positions, trades, and terminal status.
@@ -202,6 +336,35 @@ with Client(api_key="fxs_live_…") as fx:
                 print(event.data.bid, event.data.ask)
 ```
 
+### Trade events
+
+A `TradeUpdate` carries the full deal: `commission`, `swap`, `magic` and a
+real `comment` alongside `profit` (bridges MT5 0.12+ / MT4 0.11+; zero on
+older pods). Event-only P&L accounting is `data.net_profit`
+(`profit + commission + swap`).
+
+Correlate the `In` and `Out` events of one round-trip through
+`data.position` — on MT5, `Out` deals carry `magic=0` / `comment=""` unless
+the closing request set them (platform behavior, not a bridge gap), so
+position id is the reliable join key. On MT4, `deal` is always 0 and
+`position` equals the order ticket. The same id appears as `position` in
+`order_history()` rows (bridges MT5 0.14+ / MT4 0.13+) and as
+`position_id` in `position_history()`.
+
+If the bridge can't fully enrich an event in time it sets
+`data.degraded=True`: identifiers, `symbol`, `type`, `volume` and `price`
+are still trustworthy, but `entry` is `"Unknown"` and the cost fields are
+zeroed — reconcile that deal via `order_history()`.
+
+```python
+async for event in s:
+    match event:
+        case TradeUpdate() as t if t.data.degraded:
+            reconcile_later(t.data.position)     # costs/entry unreliable
+        case TradeUpdate() as t if t.data.entry == DealEntry.OUT:
+            print(t.data.position, "closed, net", t.data.net_profit)
+```
+
 ## Errors
 
 Every failure raises a subclass of `fxsocket.FxSocketError`:
@@ -209,22 +372,30 @@ Every failure raises a subclass of `fxsocket.FxSocketError`:
 | Exception | When |
 |---|---|
 | `AuthError` | missing/invalid API key |
+| `ForbiddenError` | key not allowed to do this (read-only key on a mutating call) |
 | `RateLimitError` | rate limited (`.retry_after`) |
-| `ValidationError` | malformed request |
+| `ValidationError` | malformed request (`.code`: `invalid_batch`, `unknown_account`, …) |
+| `IdempotencyError` | batch refused because of its `Idempotency-Key` (`.code`) |
 | `NotFoundError` | account/resource not found |
+| `PaymentRequiredError` | base for every 402 below (plan / balance doesn't allow it) |
 | `AccountCapError` | plan account limit reached (`.cap`, `.current`) |
+| `NoSubscriptionError` | no plan permits linking accounts |
+| `InsufficientBalanceError` | prepaid balance too low (`.shortfall_eur_cents`, `.shortfall_eur`) |
+| `SeatLapsedError` | seats lapsed, existing accounts unseated — renew first |
 | `DuplicateAccountError` | account already linked |
 | `ConnectFailedError` | broker rejected the login |
 | `TerminalNotReadyError` | terminal not provisioned / not ready |
 | `UnsupportedOnPlatformError` | feature not available on this platform |
 
 ```python
-from fxsocket import Client, AccountCapError
+from fxsocket import Client, AccountCapError, InsufficientBalanceError
 
 try:
     fx.accounts.create(server="Demo", login=1, password="…")
 except AccountCapError as e:
     print(f"Plan limit reached: {e.current}/{e.cap}")
+except InsufficientBalanceError as e:
+    print(f"Top up {e.shortfall_eur} EUR first")   # None if the API gave no figure
 ```
 
 ## Private hosting
@@ -265,6 +436,28 @@ it with `Client(..., verify_terminal_tls=False)` (or supply a pinned CA).
 *Purchasing* a server, canceling, and slot changes happen in the dashboard;
 the API deliberately exposes no billing operations.
 
+## Wallet
+
+`fx.wallet.get()` is a read-only view of your prepaid balance: what is in
+it, top-ups that haven't landed yet, and what the balance will pay for over
+the next 30 days (account seats and balance-funded private servers
+together). Amounts are integer EUR cents; the `*_eur` properties give
+`Decimal` euros.
+
+```python
+wallet = fx.wallet.get()
+print(f"balance {wallet.balance_eur} EUR, covers next 30 days: {wallet.covers_upcoming}")
+for charge in wallet.upcoming:
+    print(f"  {charge.when:%Y-%m-%d} {charge.kind:6} {charge.label} {charge.amount_eur} EUR")
+if not wallet.covers_upcoming:
+    print(f"top up at least {wallet.shortfall_eur} EUR")
+```
+
+Affordability is cumulative — with 24 EUR and three 12 EUR renewals the
+first two are covered and the third is not — so `shortfall_eur` is the
+total gap, not the size of any single charge. Topping up happens in the
+dashboard; the SDK deliberately exposes no payment operations.
+
 ## Timestamps
 
 Terminal timestamps (`quote.time`, candle `time`, order times) are returned as

fxsocket-0.6.0/examples/multi_account_trade.py

@@ -0,0 +1,49 @@
+"""Send one trade to every connected account, then flatten it everywhere.
+
+Run:  FXSOCKET_API_KEY=fxs_live_... python examples/multi_account_trade.py
+
+Requires the full ``fxs_live_…`` key — read-only keys cannot trade.
+"""
+
+import uuid
+
+from fxsocket import Client, CloseDefaults, OrderDefaults, OrderLeg
+
+
+def main() -> None:
+    with Client() as fx:  # reads FXSOCKET_API_KEY from the environment
+        accounts = [a for a in fx.accounts.list() if a.has_terminal]
+        if not accounts:
+            print("no connected accounts")
+            return
+
+        # Same trade on every account; the first one gets a bigger size.
+        legs = [OrderLeg(account_id=a) for a in accounts]
+        legs[0].volume = 0.2
+        result = fx.orders.send(
+            legs,
+            defaults=OrderDefaults(symbol="EURUSD", operation="buy", volume=0.1),
+            idempotency_key=str(uuid.uuid4()),  # makes a retry safe
+        )
+        print(f"batch {result.batch_id}: {result.summary}")
+        for account, leg in zip(accounts, result.results, strict=True):
+            print(f"  {account.nickname or account.id}: {leg.status} {leg.message}")
+        if result.unknown_legs:
+            print("  some legs timed out — reconcile before re-sending")
+
+        # Flatten: close every EURUSD position on every account, whatever
+        # suffix the broker uses (EURUSD, EURUSD.sd, EURUSDm ...).
+        closed = fx.orders.close(
+            accounts,
+            defaults=CloseDefaults(symbol="EURUSD", symbol_match="base"),
+            idempotency_key=str(uuid.uuid4()),
+        )
+        for account, leg in zip(accounts, closed.results, strict=True):
+            print(
+                f"  {account.nickname or account.id}: {leg.status} "
+                f"({leg.closed}/{leg.matched} closed)"
+            )
+
+
+if __name__ == "__main__":
+    main()