fxsocket 0.2__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fxsocket
-Version: 0.2
+Version: 0.4.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
@@ -40,8 +40,11 @@ interfaces.
 ## Features
 
 - **Account management** — link, list, fetch, and disconnect MT4/MT5 accounts.
-- **Trading** — market & pending orders, modify, close, plus margin/profit calculators.
-- **Market data** — quotes, symbol specifications, OHLC history, account state & info.
+- **Private servers** — list your dedicated hosting servers and manage the
+  accounts on them.
+- **Trading** — market & pending orders, modify, close, close-all, plus margin/profit calculators.
+- **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
   over WebSocket, with automatic reconnect + subscription replay.
 - **Sync *and* async** — `Client` / `AsyncClient`, method-for-method mirrors.
@@ -155,6 +158,21 @@ if res.is_effective:        # applied now, or already in effect
     ...
 ```
 
+There's also a panic button. `close_all()` closes every open position in one
+trade-EA pass — optionally filtered by `symbol` and/or `magic` (`magic=0`
+matches manually-opened orders), and `delete_pending=True` also deletes
+matching pending orders. It returns a `CloseAllSummary` with per-ticket
+results. On a 504 the pass *continues inside the terminal* — check
+`opened_orders()` before acting again rather than re-sending:
+
+```python
+summary = term.close_all(symbol="EURUSD", delete_pending=True)
+if summary.failed:
+    for r in summary.results:
+        if not r.success:
+            print(r.ticket, r.retcode, r.retcode_description)
+```
+
 Inputs are validated client-side before they're sent. One guard worth knowing:
 in `order_modify`, a literal `stop_loss=0.0` would *remove* your stop-loss, so
 it's rejected — pass `clear_stop_loss=True` to remove one deliberately, while
@@ -238,11 +256,41 @@ except AccountCapError as e:
 
 ## Private hosting
 
-Privately-hosted accounts (a dedicated droplet) are listed, traded, and streamed
-exactly like shared-cluster accounts — their `rest_url` / `ws_url` simply point
-at the droplet. The droplet serves a self-signed certificate, so reach it with
-`Client(..., verify_terminal_tls=False)` (or supply a pinned CA). *Creating* a
-private-hosted account is done in the dashboard.
+Dedicated private servers are managed through `client.private_servers`:
+
+```python
+import time
+
+from fxsocket import Client, PrivateAccountStatus, SlotsFullError
+
+with Client(api_key="fxs_live_...", verify_terminal_tls=False) as fx:
+    [server] = fx.private_servers.list()
+    print(server.name, server.status, f"{server.used_slots}/{server.purchased_slots}")
+
+    try:
+        account = fx.private_servers.add_account(
+            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.")
+
+    # Poll until the on-server agent has the terminal up, then trade as usual.
+    while True:
+        server = fx.private_servers.get(server)
+        account = next(a for a in server.accounts if a.id == account.id)
+        if account.status == PrivateAccountStatus.READY:
+            break
+        time.sleep(5)
+
+    print(fx.terminal(account).account_summary())
+```
+
+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.
 
 ## Timestamps
 

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

@@ -13,8 +13,11 @@ interfaces.
 ## Features
 
 - **Account management** — link, list, fetch, and disconnect MT4/MT5 accounts.
-- **Trading** — market & pending orders, modify, close, plus margin/profit calculators.
-- **Market data** — quotes, symbol specifications, OHLC history, account state & info.
+- **Private servers** — list your dedicated hosting servers and manage the
+  accounts on them.
+- **Trading** — market & pending orders, modify, close, close-all, plus margin/profit calculators.
+- **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
   over WebSocket, with automatic reconnect + subscription replay.
 - **Sync *and* async** — `Client` / `AsyncClient`, method-for-method mirrors.
@@ -128,6 +131,21 @@ if res.is_effective:        # applied now, or already in effect
     ...
 ```
 
+There's also a panic button. `close_all()` closes every open position in one
+trade-EA pass — optionally filtered by `symbol` and/or `magic` (`magic=0`
+matches manually-opened orders), and `delete_pending=True` also deletes
+matching pending orders. It returns a `CloseAllSummary` with per-ticket
+results. On a 504 the pass *continues inside the terminal* — check
+`opened_orders()` before acting again rather than re-sending:
+
+```python
+summary = term.close_all(symbol="EURUSD", delete_pending=True)
+if summary.failed:
+    for r in summary.results:
+        if not r.success:
+            print(r.ticket, r.retcode, r.retcode_description)
+```
+
 Inputs are validated client-side before they're sent. One guard worth knowing:
 in `order_modify`, a literal `stop_loss=0.0` would *remove* your stop-loss, so
 it's rejected — pass `clear_stop_loss=True` to remove one deliberately, while
@@ -211,11 +229,41 @@ except AccountCapError as e:
 
 ## Private hosting
 
-Privately-hosted accounts (a dedicated droplet) are listed, traded, and streamed
-exactly like shared-cluster accounts — their `rest_url` / `ws_url` simply point
-at the droplet. The droplet serves a self-signed certificate, so reach it with
-`Client(..., verify_terminal_tls=False)` (or supply a pinned CA). *Creating* a
-private-hosted account is done in the dashboard.
+Dedicated private servers are managed through `client.private_servers`:
+
+```python
+import time
+
+from fxsocket import Client, PrivateAccountStatus, SlotsFullError
+
+with Client(api_key="fxs_live_...", verify_terminal_tls=False) as fx:
+    [server] = fx.private_servers.list()
+    print(server.name, server.status, f"{server.used_slots}/{server.purchased_slots}")
+
+    try:
+        account = fx.private_servers.add_account(
+            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.")
+
+    # Poll until the on-server agent has the terminal up, then trade as usual.
+    while True:
+        server = fx.private_servers.get(server)
+        account = next(a for a in server.accounts if a.id == account.id)
+        if account.status == PrivateAccountStatus.READY:
+            break
+        time.sleep(5)
+
+    print(fx.terminal(account).account_summary())
+```
+
+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.
 
 ## Timestamps
 

{fxsocket-0.2 → fxsocket-0.4.0}/src/fxsocket/__init__.py

@@ -16,6 +16,8 @@ from .enums import (
     OrderOperation,
     OrderOutcome,
     Platform,
+    PrivateAccountStatus,
+    PrivateServerStatus,
     Timeframe,
     TradingStatus,
 )
@@ -28,6 +30,7 @@ from .errors import (
     NoSubscriptionError,
     NotFoundError,
     RateLimitError,
+    SlotsFullError,
     StreamError,
     TerminalNotReadyError,
     TerminalTimeoutError,
@@ -39,6 +42,10 @@ from .models import (
     AccountInfo,
     AccountSummary,
     Candle,
+    CloseAllResult,
+    CloseAllSummary,
+    CommissionRule,
+    CommissionTier,
     Health,
     HealthChecks,
     HistoryTrade,
@@ -46,12 +53,15 @@ from .models import (
     OpenedOrder,
     OrderResult,
     PositionTrade,
+    PrivateServer,
+    PrivateServerAccount,
     ProfitCalc,
     Quote,
     ServerTimezone,
     SymbolInfo,
     TerminalStatusData,
     TradeEventData,
+    TradingSession,
 )
 from .terminal import (
     AccountUpdate,
@@ -97,6 +107,8 @@ __all__ = [
     "TradeEventData",
     "TerminalStatusData",
     "Account",
+    "PrivateServer",
+    "PrivateServerAccount",
     "AccountSummary",
     "AccountInfo",
     "OpenedOrder",
@@ -105,13 +117,20 @@ __all__ = [
     "ServerTimezone",
     "Quote",
     "SymbolInfo",
+    "CommissionRule",
+    "CommissionTier",
+    "TradingSession",
     "Candle",
     "OrderResult",
+    "CloseAllResult",
+    "CloseAllSummary",
     "MarginCalc",
     "ProfitCalc",
     "Health",
     "HealthChecks",
     "Platform",
+    "PrivateAccountStatus",
+    "PrivateServerStatus",
     "TradingStatus",
     "OrderOperation",
     "OrderOutcome",
@@ -128,6 +147,7 @@ __all__ = [
     "AccountCapError",
     "NoSubscriptionError",
     "DuplicateAccountError",
+    "SlotsFullError",
     "ConnectFailedError",
     "TerminalNotReadyError",
     "TerminalTimeoutError",

fxsocket-0.4.0/src/fxsocket/_version.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"

{fxsocket-0.2 → fxsocket-0.4.0}/src/fxsocket/client.py

@@ -15,8 +15,13 @@ import httpx
 from ._http import AsyncHTTP, SyncHTTP, auth_headers
 from .config import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, ENV_API_KEY
 from .errors import AuthError, TerminalNotReadyError
-from .management import Accounts, AsyncAccounts
-from .models import Account
+from .management import (
+    Accounts,
+    AsyncAccounts,
+    AsyncPrivateServers,
+    PrivateServers,
+)
+from .models import Account, PrivateServerAccount
 from .terminal.client import AsyncTerminalClient, TerminalClient
 from .terminal.stream import AsyncStream, Stream
 
@@ -63,11 +68,13 @@ class Client:
         )
         #: Account management (the v1 API).
         self.accounts = Accounts(SyncHTTP(self._http_client))
+        #: Private hosting servers (the v1 API).
+        self.private_servers = PrivateServers(SyncHTTP(self._http_client))
         self._terminals: dict[tuple[str, str], TerminalClient] = {}
 
     def terminal(
         self,
-        account: Account,
+        account: Account | PrivateServerAccount,
         *,
         verify: bool | None = None,
         timeout: float | None = None,
@@ -100,7 +107,7 @@ class Client:
 
     def stream(
         self,
-        account: Account,
+        account: Account | PrivateServerAccount,
         *,
         verify: bool | None = None,
         auto_reconnect: bool = True,
@@ -178,11 +185,12 @@ class AsyncClient:
             timeout=timeout,
         )
         self.accounts = AsyncAccounts(AsyncHTTP(self._http_client))
+        self.private_servers = AsyncPrivateServers(AsyncHTTP(self._http_client))
         self._terminals: dict[tuple[str, str], AsyncTerminalClient] = {}
 
     def terminal(
         self,
-        account: Account,
+        account: Account | PrivateServerAccount,
         *,
         verify: bool | None = None,
         timeout: float | None = None,
@@ -212,7 +220,7 @@ class AsyncClient:
 
     def stream(
         self,
-        account: Account,
+        account: Account | PrivateServerAccount,
         *,
         verify: bool | None = None,
         auto_reconnect: bool = True,

{fxsocket-0.2 → fxsocket-0.4.0}/src/fxsocket/enums.py

@@ -76,6 +76,25 @@ class OrderOutcome(str, Enum):
     REJECTED = "rejected"     #: anything else — inspect ``retcode`` / ``comment``
 
 
+class PrivateServerStatus(str, Enum):
+    """Lifecycle of a private hosting server (v1 ``status``)."""
+
+    PENDING_PAYMENT = "pending_payment"
+    PROVISIONING = "provisioning"
+    READY = "ready"
+    RESIZING = "resizing"
+    EXPIRED = "expired"
+
+
+class PrivateAccountStatus(str, Enum):
+    """Lifecycle of an account living on a private server (v1 ``status``)."""
+
+    PROVISIONING = "provisioning"
+    READY = "ready"
+    ERROR = "error"
+    EXPIRED = "expired"
+
+
 class OrderKind(str, Enum):
     """Whether an opened row is a live position or a resting pending order."""
 

{fxsocket-0.2 → fxsocket-0.4.0}/src/fxsocket/errors.py

@@ -74,6 +74,24 @@ class DuplicateAccountError(FxSocketError):
     """This account is already linked (HTTP 409)."""
 
 
+class SlotsFullError(FxSocketError):
+    """Every purchased slot on the private server is taken (HTTP 409
+    ``slots_full``). Raise the server's limit from the dashboard."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        used: int | None = None,
+        cap: int | None = None,
+        **kw: Any,
+    ):
+        super().__init__(message, **kw)
+        self.used = used
+        self.cap = cap
+
+
+
 class ConnectFailedError(FxSocketError):
     """The broker rejected the login during account creation (HTTP 400).
 
@@ -145,6 +163,10 @@ def error_from_response(resp: httpx.Response) -> FxSocketError:
     if status == 404:
         return NotFoundError(message, **common)
     if status == 409:
+        if code == "slots_full" and isinstance(body, dict):
+            return SlotsFullError(
+                message, used=body.get("used"), cap=body.get("cap"), **common
+            )
         return DuplicateAccountError(message, **common)
     if status == 402:
         if code == "account_cap_reached" and isinstance(body, dict):

fxsocket-0.4.0/src/fxsocket/management.py

@@ -0,0 +1,264 @@
+"""Account management — the public v1 API (``/v1/accounts``).
+
+Accessible as ``client.accounts`` on both :class:`~fxsocket.Client` and
+:class:`~fxsocket.AsyncClient`.
+"""
+
+from __future__ import annotations
+
+from ._http import AsyncHTTP, SyncHTTP
+from .enums import Platform
+from .models import Account, PrivateServer, PrivateServerAccount
+
+
+def account_id_of(account: Account | str) -> str:
+    """Accept either an :class:`Account` or a bare id string."""
+    return account.id if isinstance(account, Account) else str(account)
+
+
+def _create_payload(
+    *,
+    server: str,
+    login: int,
+    password: str,
+    platform: Platform | str,
+    nickname: str,
+) -> dict[str, object]:
+    return {
+        "platform": Platform(platform).value,
+        "server": server,
+        "login": login,
+        "password": password,
+        "nickname": nickname,
+    }
+
+
+class Accounts:
+    """Synchronous account operations."""
+
+    def __init__(self, http: SyncHTTP) -> None:
+        self._http = http
+
+    def list(self) -> list[Account]:
+        """List every account owned by the authenticated user."""
+        data = self._http.request("GET", "/accounts")
+        return [Account.model_validate(row) for row in data]
+
+    def get(self, account: Account | str) -> Account:
+        """Fetch one account by id (use this to poll connection status)."""
+        data = self._http.request("GET", f"/accounts/{account_id_of(account)}")
+        return Account.model_validate(data)
+
+    def create(
+        self,
+        *,
+        server: str,
+        login: int,
+        password: str,
+        platform: Platform | str = Platform.MT5,
+        nickname: str = "",
+    ) -> Account:
+        """Link (connect) a new MT4/MT5 account. Returns it in ``connecting``
+        state when terminal pods are enabled, else ``connected``."""
+        data = self._http.request(
+            "POST",
+            "/accounts",
+            json=_create_payload(
+                server=server,
+                login=login,
+                password=password,
+                platform=platform,
+                nickname=nickname,
+            ),
+        )
+        return Account.model_validate(data)
+
+    def delete(self, account: Account | str) -> None:
+        """Unlink (disconnect) an account and tear down its terminal."""
+        self._http.request("DELETE", f"/accounts/{account_id_of(account)}")
+
+
+class AsyncAccounts:
+    """Asynchronous mirror of :class:`Accounts`."""
+
+    def __init__(self, http: AsyncHTTP) -> None:
+        self._http = http
+
+    async def list(self) -> list[Account]:
+        data = await self._http.request("GET", "/accounts")
+        return [Account.model_validate(row) for row in data]
+
+    async def get(self, account: Account | str) -> Account:
+        data = await self._http.request("GET", f"/accounts/{account_id_of(account)}")
+        return Account.model_validate(data)
+
+    async def create(
+        self,
+        *,
+        server: str,
+        login: int,
+        password: str,
+        platform: Platform | str = Platform.MT5,
+        nickname: str = "",
+    ) -> Account:
+        data = await self._http.request(
+            "POST",
+            "/accounts",
+            json=_create_payload(
+                server=server,
+                login=login,
+                password=password,
+                platform=platform,
+                nickname=nickname,
+            ),
+        )
+        return Account.model_validate(data)
+
+    async def delete(self, account: Account | str) -> None:
+        await self._http.request("DELETE", f"/accounts/{account_id_of(account)}")
+
+
+# --------------------------------------------------------------------------- #
+# Private servers (``/v1/private-servers``)
+# --------------------------------------------------------------------------- #
+
+
+def private_server_id_of(server: PrivateServer | str) -> str:
+    """Accept either a :class:`PrivateServer` or a bare id string."""
+    return server.id if isinstance(server, PrivateServer) else str(server)
+
+
+def _private_account_payload(
+    *,
+    server: str,
+    login: int,
+    password: str,
+    platform: Platform | str,
+    nickname: str,
+    trade_ea_symbol: str,
+) -> dict[str, object]:
+    return {
+        "platform": Platform(platform).value,
+        "server": server,
+        "login": login,
+        "password": password,
+        "nickname": nickname,
+        "trade_ea_symbol": trade_ea_symbol,
+    }
+
+
+class PrivateServers:
+    """Synchronous private-server operations.
+
+    Read + on-server account management only: purchasing a server,
+    canceling, and slot changes happen in the dashboard.
+    """
+
+    def __init__(self, http: SyncHTTP) -> None:
+        self._http = http
+
+    def list(self) -> list[PrivateServer]:
+        """List every private server owned by the authenticated user."""
+        data = self._http.request("GET", "/private-servers")
+        return [PrivateServer.model_validate(row) for row in data]
+
+    def get(self, server: PrivateServer | str) -> PrivateServer:
+        """Fetch one server by id (use this to poll account readiness)."""
+        data = self._http.request(
+            "GET", f"/private-servers/{private_server_id_of(server)}"
+        )
+        return PrivateServer.model_validate(data)
+
+    def add_account(
+        self,
+        private_server: PrivateServer | str,
+        *,
+        server: str,
+        login: int,
+        password: str,
+        platform: Platform | str = Platform.MT5,
+        nickname: str = "",
+        trade_ea_symbol: str = "",
+    ) -> PrivateServerAccount:
+        """Connect an MT4/MT5 account onto the server.
+
+        The on-server agent brings the terminal up asynchronously — poll
+        :meth:`get` until the account's ``status`` reaches ``ready``.
+        Raises :class:`~fxsocket.SlotsFullError` when every purchased slot
+        is taken and :class:`~fxsocket.DuplicateAccountError` when the
+        account is already linked.
+        """
+        data = self._http.request(
+            "POST",
+            f"/private-servers/{private_server_id_of(private_server)}/accounts",
+            json=_private_account_payload(
+                server=server,
+                login=login,
+                password=password,
+                platform=platform,
+                nickname=nickname,
+                trade_ea_symbol=trade_ea_symbol,
+            ),
+        )
+        return PrivateServerAccount.model_validate(data)
+
+    def remove_account(
+        self,
+        private_server: PrivateServer | str,
+        account: PrivateServerAccount | str,
+    ) -> None:
+        """Detach an account from the server, freeing its slot."""
+        sid = private_server_id_of(private_server)
+        aid = account.id if isinstance(account, PrivateServerAccount) else str(account)
+        self._http.request("DELETE", f"/private-servers/{sid}/accounts/{aid}")
+
+
+class AsyncPrivateServers:
+    """Asynchronous mirror of :class:`PrivateServers`."""
+
+    def __init__(self, http: AsyncHTTP) -> None:
+        self._http = http
+
+    async def list(self) -> list[PrivateServer]:
+        data = await self._http.request("GET", "/private-servers")
+        return [PrivateServer.model_validate(row) for row in data]
+
+    async def get(self, server: PrivateServer | str) -> PrivateServer:
+        data = await self._http.request(
+            "GET", f"/private-servers/{private_server_id_of(server)}"
+        )
+        return PrivateServer.model_validate(data)
+
+    async def add_account(
+        self,
+        private_server: PrivateServer | str,
+        *,
+        server: str,
+        login: int,
+        password: str,
+        platform: Platform | str = Platform.MT5,
+        nickname: str = "",
+        trade_ea_symbol: str = "",
+    ) -> PrivateServerAccount:
+        data = await self._http.request(
+            "POST",
+            f"/private-servers/{private_server_id_of(private_server)}/accounts",
+            json=_private_account_payload(
+                server=server,
+                login=login,
+                password=password,
+                platform=platform,
+                nickname=nickname,
+                trade_ea_symbol=trade_ea_symbol,
+            ),
+        )
+        return PrivateServerAccount.model_validate(data)
+
+    async def remove_account(
+        self,
+        private_server: PrivateServer | str,
+        account: PrivateServerAccount | str,
+    ) -> None:
+        sid = private_server_id_of(private_server)
+        aid = account.id if isinstance(account, PrivateServerAccount) else str(account)
+        await self._http.request("DELETE", f"/private-servers/{sid}/accounts/{aid}")