synpath 0.1.0__tar.gz

synpath-0.1.0/.env.example

@@ -0,0 +1,39 @@
+# Copy to .env (git-ignored) and fill in what you have. Nothing here reaches
+# the repository; `synpath doctor` reports what loads.
+
+# Kalshi: API key id and the RSA private key file (PEM, the BEGIN...END block only).
+KALSHI_KEY_ID=
+KALSHI_PRIVATE_KEY_PATH=/Users/you/.kalshi/kalshi.pem
+# prod (the default) trades real money on Kalshi; demo uses Kalshi's practice exchange with a demo key.
+KALSHI_ENV=prod
+
+# Polymarket (global CLOB V2). The signer's private key, hex, and the wallet the
+# orders spend from: signature type 3 with the Deposit Wallet address as funder
+# for any account created since May 2026 (polymarket.com -> profile menu);
+# 1 or 2 for legacy proxy / Safe wallets; 0 only for an allowlisted EOA.
+POLYMARKET_PRIVATE_KEY=
+POLYMARKET_SIGNATURE_TYPE=3
+POLYMARKET_FUNDER=
+# Optional: existing CLOB API credentials (derived from the key when absent),
+# a builder code, a Relayer API key for gasless approvals / split / merge /
+# redeem, and a Polygon RPC endpoint for an EOA's own transactions.
+POLYMARKET_API_KEY=
+POLYMARKET_API_SECRET=
+POLYMARKET_API_PASSPHRASE=
+POLYMARKET_BUILDER_CODE=
+POLYMARKET_RELAYER_API_KEY=
+POLYMARKET_RELAYER_API_KEY_ADDRESS=
+POLYMARKET_RPC_URL=
+
+# Polymarket US, retail API (api.polymarket.us): key id and base64 secret from
+# polymarket.us/developer after identity verification in the app.
+POLYMARKET_US_KEY_ID=
+POLYMARKET_US_SECRET_KEY=
+
+# Polymarket US, exchange API (polymarketexchange.com): an onboarded firm's
+# client id, RSA private key file, participant id and trading account.
+POLYMARKET_US_CLIENT_ID=
+POLYMARKET_US_PRIVATE_KEY_PATH=
+POLYMARKET_US_PARTICIPANT_ID=
+POLYMARKET_US_ACCOUNT=
+POLYMARKET_US_ENV=preprod

synpath-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: publish
+
+# Publishing a GitHub release uploads that version to PyPI through Trusted
+# Publishing: PyPI trusts this workflow in this repository, so no API token is
+# stored anywhere. The release tag must match the version in pyproject.toml.
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Tag matches the package version
+        run: |
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          test "${GITHUB_REF_NAME#v}" = "$version" || { echo "tag $GITHUB_REF_NAME does not match version $version"; exit 1; }
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - name: Install the wheel and run it, outside the checkout
+        run: |
+          python -m venv /tmp/check
+          /tmp/check/bin/pip install dist/*.whl
+          cd /tmp && /tmp/check/bin/python -c "import synpath; print(synpath.__file__)" && /tmp/check/bin/synpath --help > /dev/null
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/synpath/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

synpath-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,21 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q

synpath-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+.pytest_cache/
+*.egg-info/
+dist/
+
+# secrets: venue credentials live in the environment or a local .env, never in git
+.env
+.env.*
+!.env.example
+*.pem
+*.key

synpath-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Synpath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

synpath-0.1.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.5
+Name: synpath
+Version: 0.1.0
+Summary: One API for prediction markets. Kalshi and Polymarket, normalized, with every price labelled by source and time.
+Project-URL: Homepage, https://synpath.dev
+Project-URL: Documentation, https://synpath.dev/docs
+Project-URL: Repository, https://github.com/Synpath-ai/synpath
+Project-URL: Issues, https://github.com/Synpath-ai/synpath/issues
+Project-URL: Discord, https://discord.gg/QZzsHTpGA3
+Author: Synpath
+License: MIT
+License-File: LICENSE
+Keywords: kalshi,market-data,polymarket,prediction-markets,trading,unified-api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: cryptography>=42
+Requires-Dist: eth-account>=0.13
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyjwt[crypto]>=2.8
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: uvicorn[standard]>=0.27
+Requires-Dist: websockets>=13
+Provides-Extra: dev
+Requires-Dist: anyio>=4; extra == 'dev'
+Requires-Dist: cryptography>=42; extra == 'dev'
+Requires-Dist: grpcio-tools>=1.60; extra == 'dev'
+Requires-Dist: grpcio>=1.60; extra == 'dev'
+Requires-Dist: protobuf>=5.26; extra == 'dev'
+Requires-Dist: pyjwt[crypto]>=2.8; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Provides-Extra: engine
+Provides-Extra: grpc
+Requires-Dist: cryptography>=42; extra == 'grpc'
+Requires-Dist: grpcio-tools>=1.60; extra == 'grpc'
+Requires-Dist: grpcio>=1.60; extra == 'grpc'
+Requires-Dist: protobuf>=5.26; extra == 'grpc'
+Requires-Dist: pyjwt[crypto]>=2.8; extra == 'grpc'
+Provides-Extra: server
+Provides-Extra: trading
+Provides-Extra: ws
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/Synpath-ai/synpath/main/assets/synpath-banner.png" alt="Synpath: one API for every prediction market" width="100%">
+
+# Synpath – One API for prediction markets
+
+**Build on prediction markets without building against each one.**<br/>
+One open-source API across Kalshi, Polymarket and Polymarket US: market data, order entry, live streams, and an execution engine that remembers what it sent. In-process from Python, over REST and WebSocket from anywhere.
+
+<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
+<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
+<a href="https://discord.gg/QZzsHTpGA3"><img src="https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
+
+</div>
+
+**🆕 New: Every Kalshi order book, every tick.**<br/>
+Full-depth books and trades for every past Kalshi trade. Query any moment in under a minute. **[Get the data →](https://synpath.dev/tick-data)**
+
+---
+
+## Supported Exchanges
+
+| | Exchange | id | Market data | Order entry | Streams | Order books |
+|:-:|---|---|:-:|:-:|:-:|---|
+| <img src="assets/kalshi.png" width="20" height="20" alt="Kalshi"> | [Kalshi](https://kalshi.com) | `kalshi` | ✓ | ✓ | WebSocket | one book per market, both sides read it |
+| <img src="assets/polymarket.png" width="20" height="20" alt="Polymarket"> | [Polymarket](https://polymarket.com) | `polymarket` | ✓ | ✓ | WebSocket | one book per outcome token |
+| <img src="assets/polymarket.png" width="20" height="20" alt="Polymarket US"> | [Polymarket US](https://polymarket.us) | `polymarket_us` | ✓ | ✓ retail and exchange APIs | WebSocket and gRPC | one book per market, both sides read it |
+
+## Why Synpath
+
+- **Liquidity is fragmented. Your time shouldn't be.** The same market trades on Kalshi, Polymarket and Polymarket US, each with its own API, units and quirks. Synpath gives you one interface for all of them, and smart order routing buys from whichever book is cheapest. Spend your time on alpha, not plumbing.
+
+- **Traders deserve advanced order types.** Stops, trailing stops, icebergs, OCO, brackets, TWAP and pegs, on every venue, even where the exchange has none. Orders are journaled before they're sent, so a crash never places one twice.
+
+- **A home after Dome and pmxt.** Dome's API shut down in April 2026, and pmxt hasn't shipped since July 2026. Synpath is MIT-licensed, actively maintained, and follows ccxt conventions.
+
+## Installation
+
+```bash
+pip install synpath              # market data, order entry, streams, the engine and the server
+pip install "synpath[grpc]"      # + Polymarket US exchange gRPC streams
+```
+
+Python 3.10 or newer.
+
+**Hosted API.** Run `synpath login`, then `synpath keys create`. It serves tick-level Kalshi order book and trade history, and cross-venue market matching. Trading stays on your machine: Synpath never holds your keys or funds.
+
+## Quick Start
+
+**Markets and quotes**
+
+```python
+import synpath
+
+kalshi = synpath.Kalshi()
+market = kalshi.fetch_markets(limit=1)[0]
+
+print(market.title)                                # Will Elon Musk visit Mars before Aug 1, 2099?
+print(market.yes.quote.bid, market.yes.quote.ask)  # 0.1 0.12
+```
+
+**Order books and search**
+
+```python
+book = kalshi.fetch_order_book(market.id, depth=5)
+book.best_bid, book.best_ask                       # best first on both sides
+kalshi.fetch_order_book(market.id, side="no")      # what NO costs
+
+markets = kalshi.fetch_markets(query="trump", limit=10)
+fee = kalshi.fetch_fee_schedule(markets[0].id)
+fee.estimate(price=0.50, contracts=100)            # 1.75
+```
+
+**Same code, every venue**
+
+```python
+for venue_id in synpath.exchanges:                 # ['kalshi', 'polymarket', 'polymarket_us']
+    with synpath.exchange(venue_id) as venue:
+        page = venue.fetch_markets(limit=5)
+
+client = synpath.Client()                          # or one client, routed by the id
+client.fetch_market("polymarket:2252244")          # every id starts with its venue
+```
+
+**Order entry**
+
+```python
+from decimal import Decimal
+from synpath import KalshiTrading, OrderRequest, Side, load_credentials, require
+
+async with KalshiTrading(require("kalshi", load_credentials())) as kalshi:
+    order = await kalshi.create_order(OrderRequest(
+        market_id=market.id, side=Side.BUY,          # buy takes YES, sell takes NO
+        amount=Decimal("10"), price=Decimal("0.42"), # always the YES price
+    ))
+```
+
+**Live streams**
+
+```python
+from synpath import PolymarketMarketStream, BookEvent
+
+async with PolymarketMarketStream() as stream:
+    await stream.watch_order_book(["polymarket:2252244"])   # both sides of the market
+    async for event in stream:
+        if isinstance(event, BookEvent):
+            print(event.market_id, event.side, event.best_bid, event.best_ask)
+```
+
+**The engine, and the orders the venues do not hold**
+
+```python
+from synpath.engine import Engine, EngineConfig, RiskConfig
+from synpath import OrderType
+
+async with Engine({"kalshi": kalshi}, EngineConfig(journal_path="trading.db"),
+                  risk=RiskConfig(max_order_contracts=Decimal("100"))) as engine:
+    await engine.submit(OrderRequest(
+        market_id=market.id, side=Side.SELL, amount=Decimal("20"),
+        type=OrderType.TRAILING_STOP, stop_price=Decimal("0.40"),
+        params={"trail": "0.03"}, book="alpha",
+    ))
+```
+
+**REST server**
+
+```bash
+python -m synpath.server                           # http://127.0.0.1:8000/docs
+curl "localhost:8000/venues/kalshi/markets?limit=1"
+```
+
+Trading has its own app, with per-account keys and an append-only audit log:
+
+```bash
+python -m synpath.server bootstrap --control control.db     # the first key
+python -m synpath.server schema --trading --out openapi.json
+npx openapi-typescript openapi.json --default-non-nullable false -o src/synpath.d.ts
+```
+
+## Documentation
+
+- [CLI](https://synpath.dev/docs/quickstart): hosted data API sign-in and keys versus local venue trading server setup
+- [Unified API](https://synpath.dev/docs/sdks/python): methods, data structures, identifiers, paging, status, errors
+- [Capabilities](https://synpath.dev/docs/concepts/exchanges): what each venue can and cannot answer
+- [HTTP server](https://synpath.dev/docs/api-reference): routes, envelopes, typed client generation, trading routes with per-account keys, mounting behind your own auth
+- [Trading](https://synpath.dev/docs/concepts/orders): credentials, `Decimal` money, order entry on Kalshi, Polymarket and Polymarket US
+- [Streaming](https://synpath.dev/docs/ws-api-reference): WebSocket and gRPC books, trades, orders and fills as self-healing event streams
+- [Engine](docs/engine.md): a journal written before anything is sent, pre-trade risk, a ledger, reconciliation, a kill switch, the order types the venues do not hold, buckets that route one order across venues, paper trading
+- [TypeScript client](https://synpath.dev/docs/sdks/typescript): generate a typed client from the OpenAPI document, place through cancel without Python
+
+## Development
+
+```bash
+git clone https://github.com/Synpath-ai/synpath
+cd synpath
+pip install -e ".[dev]"
+
+pytest              # offline, against recorded venue payloads
+pytest -m live      # market data against the real venues
+pytest -m demo      # order entry on a venue's demo environment
+```
+
+The `demo` tests place and cancel real orders on a demo exchange with the
+credentials in your environment, and leave the account flat. `python -m
+synpath.trading doctor` says which venues are configured without printing a
+secret.
+
+## Prior Art
+
+[ccxt](https://github.com/ccxt/ccxt) set the conventions this library follows. [pmxt](https://github.com/pmxt-dev/pmxt) got to prediction markets first.
+
+## License
+
+MIT

synpath-0.1.0/README.md

@@ -0,0 +1,174 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/Synpath-ai/synpath/main/assets/synpath-banner.png" alt="Synpath: one API for every prediction market" width="100%">
+
+# Synpath – One API for prediction markets
+
+**Build on prediction markets without building against each one.**<br/>
+One open-source API across Kalshi, Polymarket and Polymarket US: market data, order entry, live streams, and an execution engine that remembers what it sent. In-process from Python, over REST and WebSocket from anywhere.
+
+<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
+<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
+<a href="https://discord.gg/QZzsHTpGA3"><img src="https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
+
+</div>
+
+**🆕 New: Every Kalshi order book, every tick.**<br/>
+Full-depth books and trades for every past Kalshi trade. Query any moment in under a minute. **[Get the data →](https://synpath.dev/tick-data)**
+
+---
+
+## Supported Exchanges
+
+| | Exchange | id | Market data | Order entry | Streams | Order books |
+|:-:|---|---|:-:|:-:|:-:|---|
+| <img src="assets/kalshi.png" width="20" height="20" alt="Kalshi"> | [Kalshi](https://kalshi.com) | `kalshi` | ✓ | ✓ | WebSocket | one book per market, both sides read it |
+| <img src="assets/polymarket.png" width="20" height="20" alt="Polymarket"> | [Polymarket](https://polymarket.com) | `polymarket` | ✓ | ✓ | WebSocket | one book per outcome token |
+| <img src="assets/polymarket.png" width="20" height="20" alt="Polymarket US"> | [Polymarket US](https://polymarket.us) | `polymarket_us` | ✓ | ✓ retail and exchange APIs | WebSocket and gRPC | one book per market, both sides read it |
+
+## Why Synpath
+
+- **Liquidity is fragmented. Your time shouldn't be.** The same market trades on Kalshi, Polymarket and Polymarket US, each with its own API, units and quirks. Synpath gives you one interface for all of them, and smart order routing buys from whichever book is cheapest. Spend your time on alpha, not plumbing.
+
+- **Traders deserve advanced order types.** Stops, trailing stops, icebergs, OCO, brackets, TWAP and pegs, on every venue, even where the exchange has none. Orders are journaled before they're sent, so a crash never places one twice.
+
+- **A home after Dome and pmxt.** Dome's API shut down in April 2026, and pmxt hasn't shipped since July 2026. Synpath is MIT-licensed, actively maintained, and follows ccxt conventions.
+
+## Installation
+
+```bash
+pip install synpath              # market data, order entry, streams, the engine and the server
+pip install "synpath[grpc]"      # + Polymarket US exchange gRPC streams
+```
+
+Python 3.10 or newer.
+
+**Hosted API.** Run `synpath login`, then `synpath keys create`. It serves tick-level Kalshi order book and trade history, and cross-venue market matching. Trading stays on your machine: Synpath never holds your keys or funds.
+
+## Quick Start
+
+**Markets and quotes**
+
+```python
+import synpath
+
+kalshi = synpath.Kalshi()
+market = kalshi.fetch_markets(limit=1)[0]
+
+print(market.title)                                # Will Elon Musk visit Mars before Aug 1, 2099?
+print(market.yes.quote.bid, market.yes.quote.ask)  # 0.1 0.12
+```
+
+**Order books and search**
+
+```python
+book = kalshi.fetch_order_book(market.id, depth=5)
+book.best_bid, book.best_ask                       # best first on both sides
+kalshi.fetch_order_book(market.id, side="no")      # what NO costs
+
+markets = kalshi.fetch_markets(query="trump", limit=10)
+fee = kalshi.fetch_fee_schedule(markets[0].id)
+fee.estimate(price=0.50, contracts=100)            # 1.75
+```
+
+**Same code, every venue**
+
+```python
+for venue_id in synpath.exchanges:                 # ['kalshi', 'polymarket', 'polymarket_us']
+    with synpath.exchange(venue_id) as venue:
+        page = venue.fetch_markets(limit=5)
+
+client = synpath.Client()                          # or one client, routed by the id
+client.fetch_market("polymarket:2252244")          # every id starts with its venue
+```
+
+**Order entry**
+
+```python
+from decimal import Decimal
+from synpath import KalshiTrading, OrderRequest, Side, load_credentials, require
+
+async with KalshiTrading(require("kalshi", load_credentials())) as kalshi:
+    order = await kalshi.create_order(OrderRequest(
+        market_id=market.id, side=Side.BUY,          # buy takes YES, sell takes NO
+        amount=Decimal("10"), price=Decimal("0.42"), # always the YES price
+    ))
+```
+
+**Live streams**
+
+```python
+from synpath import PolymarketMarketStream, BookEvent
+
+async with PolymarketMarketStream() as stream:
+    await stream.watch_order_book(["polymarket:2252244"])   # both sides of the market
+    async for event in stream:
+        if isinstance(event, BookEvent):
+            print(event.market_id, event.side, event.best_bid, event.best_ask)
+```
+
+**The engine, and the orders the venues do not hold**
+
+```python
+from synpath.engine import Engine, EngineConfig, RiskConfig
+from synpath import OrderType
+
+async with Engine({"kalshi": kalshi}, EngineConfig(journal_path="trading.db"),
+                  risk=RiskConfig(max_order_contracts=Decimal("100"))) as engine:
+    await engine.submit(OrderRequest(
+        market_id=market.id, side=Side.SELL, amount=Decimal("20"),
+        type=OrderType.TRAILING_STOP, stop_price=Decimal("0.40"),
+        params={"trail": "0.03"}, book="alpha",
+    ))
+```
+
+**REST server**
+
+```bash
+python -m synpath.server                           # http://127.0.0.1:8000/docs
+curl "localhost:8000/venues/kalshi/markets?limit=1"
+```
+
+Trading has its own app, with per-account keys and an append-only audit log:
+
+```bash
+python -m synpath.server bootstrap --control control.db     # the first key
+python -m synpath.server schema --trading --out openapi.json
+npx openapi-typescript openapi.json --default-non-nullable false -o src/synpath.d.ts
+```
+
+## Documentation
+
+- [CLI](https://synpath.dev/docs/quickstart): hosted data API sign-in and keys versus local venue trading server setup
+- [Unified API](https://synpath.dev/docs/sdks/python): methods, data structures, identifiers, paging, status, errors
+- [Capabilities](https://synpath.dev/docs/concepts/exchanges): what each venue can and cannot answer
+- [HTTP server](https://synpath.dev/docs/api-reference): routes, envelopes, typed client generation, trading routes with per-account keys, mounting behind your own auth
+- [Trading](https://synpath.dev/docs/concepts/orders): credentials, `Decimal` money, order entry on Kalshi, Polymarket and Polymarket US
+- [Streaming](https://synpath.dev/docs/ws-api-reference): WebSocket and gRPC books, trades, orders and fills as self-healing event streams
+- [Engine](docs/engine.md): a journal written before anything is sent, pre-trade risk, a ledger, reconciliation, a kill switch, the order types the venues do not hold, buckets that route one order across venues, paper trading
+- [TypeScript client](https://synpath.dev/docs/sdks/typescript): generate a typed client from the OpenAPI document, place through cancel without Python
+
+## Development
+
+```bash
+git clone https://github.com/Synpath-ai/synpath
+cd synpath
+pip install -e ".[dev]"
+
+pytest              # offline, against recorded venue payloads
+pytest -m live      # market data against the real venues
+pytest -m demo      # order entry on a venue's demo environment
+```
+
+The `demo` tests place and cancel real orders on a demo exchange with the
+credentials in your environment, and leave the account flat. `python -m
+synpath.trading doctor` says which venues are configured without printing a
+secret.
+
+## Prior Art
+
+[ccxt](https://github.com/ccxt/ccxt) set the conventions this library follows. [pmxt](https://github.com/pmxt-dev/pmxt) got to prediction markets first.
+
+## License
+
+MIT

synpath-0.1.0/clients/typescript/.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+src/
+openapi.json
+package-lock.json

synpath-0.1.0/clients/typescript/example.ts

@@ -0,0 +1,77 @@
+/**
+ * The step's exit criterion: a TypeScript user places, watches and cancels an
+ * order without Python. Types come from the generated `synpath.d.ts`, so a
+ * wrong field name is a compile error rather than a runtime surprise.
+ */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import WebSocket from "ws";
+import type { components } from "./src/synpath.js";  // generated: npm run types; see synpath.dev/docs/sdks/typescript
+
+type Order = components["schemas"]["Order"];
+type OrderRequest = components["schemas"]["OrderRequest"];
+type PageResponseOrder = components["schemas"]["PageResponse_Order_"];
+
+// Your own `synpath serve`: market data at /, trading at /trading.
+const server = process.env.SYNPATH_SERVER ?? "http://127.0.0.1:8000";
+const base = server.replace(/\/$/, "") + "/trading";
+
+// The server's access token: given, or, for a server on this machine, read from where
+// `synpath serve` left it (~/.synpath/servers.json, readable by you only).
+function localKey(url: string): string | undefined {
+  const { hostname, port, protocol } = new URL(url);
+  if (!["127.0.0.1", "localhost", "::1"].includes(hostname)) return undefined;
+  const name = `127.0.0.1:${port || (protocol === "https:" ? 443 : 80)}`;
+  try {
+    const home = process.env.SYNPATH_HOME ?? join(homedir(), ".synpath");
+    return JSON.parse(readFileSync(join(home, "servers.json"), "utf8"))[name]?.access_token ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+const key = process.env.SYNPATH_ACCESS_TOKEN ?? localKey(server);
+if (!key) throw new Error(`no access token for ${server}: set SYNPATH_ACCESS_TOKEN, or start synpath serve on this machine`);
+const headers = { authorization: `Bearer ${key}`, "content-type": "application/json" };
+
+async function call<T>(path: string, init: RequestInit = {}): Promise<T> {
+  const response = await fetch(base + path, { ...init, headers: { ...headers, ...(init.headers ?? {}) } });
+  if (!response.ok) {
+    const { error } = await response.json();          // { code, message, details } on every route
+    throw new Error(`${init.method ?? "GET"} ${path} → ${response.status} ${error.code}: ${error.message}`);
+  }
+  return (await response.json()) as T;
+}
+
+const seen: string[] = [];
+const socket = new WebSocket(`${base.replace(/^http/, "ws")}/ws/events?key=${key}&since=0`);
+await new Promise<void>((resolve) => socket.on("open", () => resolve()));
+socket.on("message", (raw) => seen.push(JSON.parse(raw.toString()).kind));
+
+const request: OrderRequest = {
+  market_id: "kalshi:KX-A",
+  side: "buy",
+  amount: "5",
+  type: "limit",
+  price: "0.35",
+  book: "typescript",
+  account: { venue: "kalshi", name: "desk-a", subaccount: null },
+};
+
+const placed = await call<Order>("/orders", { method: "POST", body: JSON.stringify(request) });
+console.log(`placed  ${placed.id} ${placed.side} ${placed.amount} at ${placed.price} (${placed.status})`);
+
+const open = await call<PageResponseOrder>("/orders");
+console.log(`open    ${open.count} order(s): ${open.data.map((o) => o.id).join(", ")}`);
+
+const canceled = await call<Order>(`/orders/${placed.id}`, { method: "DELETE" });
+console.log(`cancel  ${canceled.id} → ${canceled.status}`);
+
+await new Promise((resolve) => setTimeout(resolve, 600));
+socket.close();
+const interesting = seen.filter((k) => k.startsWith("order.") || k.startsWith("intent."));
+console.log(`watched ${seen.length} events, including ${[...new Set(interesting)].join(", ")}`);
+
+const after = await call<PageResponseOrder>("/orders");
+if (after.count !== 0) throw new Error(`expected no open orders, got ${after.count}`);
+console.log("done    the account is flat, no Python was involved");

synpath-0.1.0/clients/typescript/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "synpath-typescript-example",
+  "private": true,
+  "type": "module",
+  "description": "Place, watch and cancel an order on a self-hosted Synpath server from TypeScript.",
+  "scripts": {
+    "types": "openapi-typescript openapi.json --default-non-nullable false -o src/synpath.d.ts",
+    "build": "tsc",
+    "start": "node dist/example.js"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.12",
+    "openapi-typescript": "^7.4.0",
+    "typescript": "^5.6.0"
+  }
+}

synpath-0.1.0/clients/typescript/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["example.ts", "src/**/*.d.ts"]
+}