The PMXT SDKs manage a local sidecar server automatically. When you
create an exchange instance without a hosted API key, the SDK spawns a
sidecar process, waits for it to become healthy, and routes every
request through it.
The server namespace gives you explicit control over that sidecar
lifecycle.
Quick reference
| Method | Description |
|---|
server.start() | Start the sidecar if it is not already running (idempotent). |
server.stop() | Stop the running sidecar (SIGTERM + lock file cleanup). |
server.restart() | Stop then start. |
server.status() | Structured snapshot: running, pid, port, version, uptime. |
server.health() | true/True if /health responds OK, false/False otherwise. |
server.logs(n) | Last n lines from ~/.pmxt/server.log (default 50). |
Start
Idempotent. If the sidecar is already running and healthy, returns
immediately. Otherwise spawns pmxt-ensure-server and waits for the
health check.
import pmxt
pmxt.server.start()
import pmxt from "pmxtjs";
await pmxt.server.start();
You rarely need to call start() yourself — creating an exchange
instance (e.g. pmxt.Polymarket()) calls it automatically.
Stop
Reads the lock file at ~/.pmxt/server.lock, sends SIGTERM to the
sidecar process, and removes the lock file.
await pmxt.server.stop();
Restart
Equivalent to stop() followed by start().
await pmxt.server.restart();
Status
Returns a structured snapshot of the sidecar state. A new object is
returned on every call (no shared mutable references).
info = pmxt.server.status()
print(info)
# {
# "running": True,
# "pid": 4242,
# "port": 3847,
# "version": "2.30.9",
# "uptime_seconds": 3612.5,
# "lock_file": "/Users/you/.pmxt/server.lock"
# }
const info = await pmxt.server.status();
console.log(info);
// {
// running: true,
// pid: 4242,
// port: 3847,
// version: "2.30.9",
// uptimeSeconds: 3612.5,
// lockFile: "/Users/you/.pmxt/server.lock"
// }
| Field | Type | Description |
|---|
running | bool | Whether the sidecar is alive and responding to /health. |
pid | int | null | Process ID from the lock file. |
port | int | null | Port the sidecar is listening on (default 3847). |
version | string | null | Server version from the lock file. |
uptime_seconds / uptimeSeconds | float | null | Seconds since the lock file was written. |
lock_file / lockFile | string | Absolute path to ~/.pmxt/server.lock. |
Health
Returns true/True if the sidecar’s /health endpoint responds with
{"status": "ok"}, false/False otherwise.
if pmxt.server.health():
print("sidecar is up")
if (await pmxt.server.health()) {
console.log("sidecar is up");
}
Logs
Returns the last n lines from ~/.pmxt/server.log. Defaults to 50.
Returns an empty list/array if the log file does not exist.
for line in pmxt.server.logs(20):
print(line)
pmxt.server.logs(20).forEach((line) => console.log(line));
Deprecated aliases
The top-level stop_server() / stopServer() and restart_server() /
restartServer() functions still work but emit deprecation warnings. Use
the server namespace instead.
# Old (deprecated)
pmxt.stop_server()
# New
pmxt.server.stop()
Environment variables
| Variable | Effect |
|---|
PMXT_ALWAYS_RESTART=1 | Force-restart the sidecar on every ensure_server_running / ensureServerRunning call (useful during development). |
