fxsocket 0.5.0__tar.gz → 0.7.0__tar.gz

{fxsocket-0.5.0 → fxsocket-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fxsocket
-Version: 0.5.0
+Version: 0.7.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.
@@ -265,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
@@ -301,7 +443,8 @@ with Client(api_key="fxs_live_...", verify_terminal_tls=False) as fx:
             server, server="ICMarkets-Demo", login=1150125, password="..."
         )
     except SlotsFullError as err:
-        print(f"Server full ({err.used}/{err.cap}) — raise the limit in the dashboard.")
+        print(f"Server full ({err.used}/{err.cap})")
+        server = fx.private_servers.resize(server, slots=err.cap + 1)
 
     # Poll until the on-server agent has the terminal up, then trade as usual.
     while True:
@@ -318,8 +461,91 @@ Accounts on a private server are traded and streamed exactly like
 shared-cluster accounts — their `rest_url` / `ws_url` simply point at the
 server's dedicated IP. The server presents a self-signed certificate, so reach
 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.
+
+`server.cancel_at_period_end` is `True` once a server has been told to stop
+instead of renewing; it then runs until `server.period_end` and expires.
+
+### Buying, resizing and canceling
+
+`fx.private_servers.regions()` returns where servers may run, how big they may
+be and what that costs — call it before buying rather than hardcoding slugs:
+
+```python
+options = fx.private_servers.regions()
+if options.enabled:
+    print(options.region_codes)                     # ['fra1', 'lon1', ...]
+    print(options.max_slots, options.max_servers)
+    print(options.monthly_price_eur(3))             # Decimal('45') — 3 slots/month
+```
+
+`create()` buys one, charged to the prepaid balance immediately. It comes back
+`provisioning`; poll `get()` until it is `ready`, usually a couple of minutes:
+
+```python
+from fxsocket import InsufficientBalanceError, PrivateServerStatus, ServerLimitError
+
+try:
+    server = fx.private_servers.create(slots=2, region="fra1", name="prop-guard")
+except InsufficientBalanceError as err:
+    print(f"Top up {err.shortfall_eur} EUR first")
+except ServerLimitError:
+    print(f"Already own the maximum ({options.max_servers})")
+
+while server.status != PrivateServerStatus.READY:
+    time.sleep(10)
+    server = fx.private_servers.get(server)
+```
+
+`resize()` changes the slot count. Increases are prorated over the rest of the
+period and charged now (the renewal date doesn't move); decreases are free and
+apply at the next renewal, so paid-for capacity is never destroyed mid-month.
+Shrinking below the accounts already on the server raises
+`AccountsExceedTargetError` — remove accounts first:
+
+```python
+server = fx.private_servers.resize(server, slots=4)
+```
+
+`cancel()` stops the server renewing: it runs until `period_end`, then expires.
+`resume()` undoes that while the period lasts (afterwards the machine is gone
+and `AlreadyLapsedError` is raised). `delete()` destroys the machine and every
+account on it right away, with **no refund** for the rest of the prepaid month —
+prefer `cancel()` unless you really want it gone now:
+
+```python
+server = fx.private_servers.cancel(server)      # stop at period_end
+assert server.cancel_at_period_end
+server = fx.private_servers.resume(server)      # changed your mind
+fx.private_servers.delete(server)               # irreversible, no refund
+```
+
+All of these move the prepaid balance, so they only work on balance-funded
+servers — a card- or crypto-funded one raises `NotBalanceFundedError` (a
+`ForbiddenError` subclass) and is managed from the dashboard. Read-only
+`fxs_ro_…` keys get a plain `ForbiddenError`.
+
+## 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 balance is only ever *spent* through the SDK (account seats
+and `private_servers.create()` / `resize()`), never topped up.
 
 ## Timestamps
 

{fxsocket-0.5.0 → fxsocket-0.7.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.
@@ -238,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
@@ -274,7 +416,8 @@ with Client(api_key="fxs_live_...", verify_terminal_tls=False) as fx:
             server, server="ICMarkets-Demo", login=1150125, password="..."
         )
     except SlotsFullError as err:
-        print(f"Server full ({err.used}/{err.cap}) — raise the limit in the dashboard.")
+        print(f"Server full ({err.used}/{err.cap})")
+        server = fx.private_servers.resize(server, slots=err.cap + 1)
 
     # Poll until the on-server agent has the terminal up, then trade as usual.
     while True:
@@ -291,8 +434,91 @@ Accounts on a private server are traded and streamed exactly like
 shared-cluster accounts — their `rest_url` / `ws_url` simply point at the
 server's dedicated IP. The server presents a self-signed certificate, so reach
 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.
+
+`server.cancel_at_period_end` is `True` once a server has been told to stop
+instead of renewing; it then runs until `server.period_end` and expires.
+
+### Buying, resizing and canceling
+
+`fx.private_servers.regions()` returns where servers may run, how big they may
+be and what that costs — call it before buying rather than hardcoding slugs:
+
+```python
+options = fx.private_servers.regions()
+if options.enabled:
+    print(options.region_codes)                     # ['fra1', 'lon1', ...]
+    print(options.max_slots, options.max_servers)
+    print(options.monthly_price_eur(3))             # Decimal('45') — 3 slots/month
+```
+
+`create()` buys one, charged to the prepaid balance immediately. It comes back
+`provisioning`; poll `get()` until it is `ready`, usually a couple of minutes:
+
+```python
+from fxsocket import InsufficientBalanceError, PrivateServerStatus, ServerLimitError
+
+try:
+    server = fx.private_servers.create(slots=2, region="fra1", name="prop-guard")
+except InsufficientBalanceError as err:
+    print(f"Top up {err.shortfall_eur} EUR first")
+except ServerLimitError:
+    print(f"Already own the maximum ({options.max_servers})")
+
+while server.status != PrivateServerStatus.READY:
+    time.sleep(10)
+    server = fx.private_servers.get(server)
+```
+
+`resize()` changes the slot count. Increases are prorated over the rest of the
+period and charged now (the renewal date doesn't move); decreases are free and
+apply at the next renewal, so paid-for capacity is never destroyed mid-month.
+Shrinking below the accounts already on the server raises
+`AccountsExceedTargetError` — remove accounts first:
+
+```python
+server = fx.private_servers.resize(server, slots=4)
+```
+
+`cancel()` stops the server renewing: it runs until `period_end`, then expires.
+`resume()` undoes that while the period lasts (afterwards the machine is gone
+and `AlreadyLapsedError` is raised). `delete()` destroys the machine and every
+account on it right away, with **no refund** for the rest of the prepaid month —
+prefer `cancel()` unless you really want it gone now:
+
+```python
+server = fx.private_servers.cancel(server)      # stop at period_end
+assert server.cancel_at_period_end
+server = fx.private_servers.resume(server)      # changed your mind
+fx.private_servers.delete(server)               # irreversible, no refund
+```
+
+All of these move the prepaid balance, so they only work on balance-funded
+servers — a card- or crypto-funded one raises `NotBalanceFundedError` (a
+`ForbiddenError` subclass) and is managed from the dashboard. Read-only
+`fxs_ro_…` keys get a plain `ForbiddenError`.
+
+## 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 balance is only ever *spent* through the SDK (account seats
+and `private_servers.create()` / `resize()`), never topped up.
 
 ## Timestamps
 

fxsocket-0.7.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()