synpath 0.1.0__tar.gz → 0.2.0__tar.gz

{synpath-0.1.0 → synpath-0.2.0}/.env.example

@@ -37,3 +37,11 @@ POLYMARKET_US_PRIVATE_KEY_PATH=
 POLYMARKET_US_PARTICIPANT_ID=
 POLYMARKET_US_ACCOUNT=
 POLYMARKET_US_ENV=preprod
+
+# Opinion (opinion.trade, BNB Chain): the private key of the wallet connected
+# on opinion.trade, and its Open API key (synpath init creates one by signing
+# with that wallet). The key alone also serves the WebSocket and raises the
+# market data rate limit. The account's Safe is read from the venue if unset.
+OPINION_PRIVATE_KEY=
+OPINION_API_KEY=
+OPINION_MULTISIG_ADDRESS=

{synpath-0.1.0 → synpath-0.2.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: synpath
-Version: 0.1.0
+Version: 0.2.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
+Project-URL: Discord, https://synpath.dev/discord
 Author: Synpath
 License: MIT
 License-File: LICENSE
@@ -52,19 +52,19 @@ Description-Content-Type: text/markdown
 
 <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
+# Synpath – One API for prediction markets <a href="https://x.com/Synpath_Dev"><img src="https://img.shields.io/twitter/url?url=https%3A%2F%2Fx.com%2FSynpath_Dev&style=social&label=Follow" alt="Follow @Synpath_Dev on X" height="28"></a>
 
 **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.
+One open-source API across Kalshi, Polymarket, Polymarket US and Opinion: 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>
+<a href="https://pepy.tech/projects/synpath"><img src="https://img.shields.io/pepy/dt/synpath?label=Total%20Downloads&color=blue" alt="Total Downloads"></a>
+<a href="https://synpath.dev/discord"><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)**
+**🆕 New: Smart order routing across Kalshi and Polymarket.**<br/>
+One order, both order books combined, filled from the cheapest price after fees. **[See how it works →](https://www.synpath.dev/docs/concepts/buckets)**
 
 ---
 
@@ -75,10 +75,11 @@ Full-depth books and trades for every past Kalshi trade. Query any moment in und
 | <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 |
+| | [Opinion](https://opinion.trade) | `opinion` | ✓ | ✓ not yet live-tested | WebSocket (API key) | one book per outcome token |
 
 ## 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.
+- **Liquidity is fragmented. Your time shouldn't be.** The same market trades on Kalshi, Polymarket, Polymarket US and Opinion, 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.
 
@@ -124,7 +125,7 @@ fee.estimate(price=0.50, contracts=100)            # 1.75
 **Same code, every venue**
 
 ```python
-for venue_id in synpath.exchanges:                 # ['kalshi', 'polymarket', 'polymarket_us']
+for venue_id in synpath.exchanges:                 # ['kalshi', 'polymarket', 'polymarket_us', 'opinion']
     with synpath.exchange(venue_id) as venue:
         page = venue.fetch_markets(limit=5)
 
@@ -157,18 +158,26 @@ async with PolymarketMarketStream() as stream:
             print(event.market_id, event.side, event.best_bid, event.best_ask)
 ```
 
-**The engine, and the orders the venues do not hold**
+**Smart order routing: one order across Kalshi and Polymarket**
 
 ```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:
+from synpath import Bucket, BucketMember, OrderType, PolymarketTrading
+from synpath.engine import Engine, EngineConfig
+
+creds = load_credentials()
+async with KalshiTrading(require("kalshi", creds)) as kalshi, \
+           PolymarketTrading(require("polymarket", creds)) as poly, \
+           Engine({"kalshi": kalshi, "polymarket": poly}, EngineConfig(journal_path="trading.db")) as engine:
+    # The same market on both venues; flip=True where a venue asks the question the other way round
+    bucket = await engine.save_bucket(Bucket(book="alpha", name="Fed cut in December", members=[
+        BucketMember(market_id="kalshi:KXFEDDECISION-26DEC-C25"),
+        BucketMember(market_id="polymarket:2252244", flip=True),
+    ]))
+    # Both order books combined, each level net of fees, filled from the cheapest price outward
     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",
+        market_id=bucket.market_id, side=Side.BUY, amount=Decimal("500"),
+        type=OrderType.MARKET, price=Decimal("0.45"),   # the worst price you accept
+        book="alpha",
     ))
 ```
 
@@ -189,14 +198,7 @@ npx openapi-typescript openapi.json --default-non-nullable false -o src/synpath.
 
 ## 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
+See the [API Reference](https://www.synpath.dev/docs) for detailed documentation and more examples.
 
 ## Development
 
@@ -217,7 +219,7 @@ 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.
+[ccxt](https://github.com/ccxt/ccxt) set the conventions this library follows.
 
 ## License
 

{synpath-0.1.0 → synpath-0.2.0}/README.md

@@ -2,19 +2,19 @@
 
 <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
+# Synpath – One API for prediction markets <a href="https://x.com/Synpath_Dev"><img src="https://img.shields.io/twitter/url?url=https%3A%2F%2Fx.com%2FSynpath_Dev&style=social&label=Follow" alt="Follow @Synpath_Dev on X" height="28"></a>
 
 **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.
+One open-source API across Kalshi, Polymarket, Polymarket US and Opinion: 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>
+<a href="https://pepy.tech/projects/synpath"><img src="https://img.shields.io/pepy/dt/synpath?label=Total%20Downloads&color=blue" alt="Total Downloads"></a>
+<a href="https://synpath.dev/discord"><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)**
+**🆕 New: Smart order routing across Kalshi and Polymarket.**<br/>
+One order, both order books combined, filled from the cheapest price after fees. **[See how it works →](https://www.synpath.dev/docs/concepts/buckets)**
 
 ---
 
@@ -25,10 +25,11 @@ Full-depth books and trades for every past Kalshi trade. Query any moment in und
 | <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 |
+| | [Opinion](https://opinion.trade) | `opinion` | ✓ | ✓ not yet live-tested | WebSocket (API key) | one book per outcome token |
 
 ## 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.
+- **Liquidity is fragmented. Your time shouldn't be.** The same market trades on Kalshi, Polymarket, Polymarket US and Opinion, 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.
 
@@ -74,7 +75,7 @@ fee.estimate(price=0.50, contracts=100)            # 1.75
 **Same code, every venue**
 
 ```python
-for venue_id in synpath.exchanges:                 # ['kalshi', 'polymarket', 'polymarket_us']
+for venue_id in synpath.exchanges:                 # ['kalshi', 'polymarket', 'polymarket_us', 'opinion']
     with synpath.exchange(venue_id) as venue:
         page = venue.fetch_markets(limit=5)
 
@@ -107,18 +108,26 @@ async with PolymarketMarketStream() as stream:
             print(event.market_id, event.side, event.best_bid, event.best_ask)
 ```
 
-**The engine, and the orders the venues do not hold**
+**Smart order routing: one order across Kalshi and Polymarket**
 
 ```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:
+from synpath import Bucket, BucketMember, OrderType, PolymarketTrading
+from synpath.engine import Engine, EngineConfig
+
+creds = load_credentials()
+async with KalshiTrading(require("kalshi", creds)) as kalshi, \
+           PolymarketTrading(require("polymarket", creds)) as poly, \
+           Engine({"kalshi": kalshi, "polymarket": poly}, EngineConfig(journal_path="trading.db")) as engine:
+    # The same market on both venues; flip=True where a venue asks the question the other way round
+    bucket = await engine.save_bucket(Bucket(book="alpha", name="Fed cut in December", members=[
+        BucketMember(market_id="kalshi:KXFEDDECISION-26DEC-C25"),
+        BucketMember(market_id="polymarket:2252244", flip=True),
+    ]))
+    # Both order books combined, each level net of fees, filled from the cheapest price outward
     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",
+        market_id=bucket.market_id, side=Side.BUY, amount=Decimal("500"),
+        type=OrderType.MARKET, price=Decimal("0.45"),   # the worst price you accept
+        book="alpha",
     ))
 ```
 
@@ -139,14 +148,7 @@ npx openapi-typescript openapi.json --default-non-nullable false -o src/synpath.
 
 ## 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
+See the [API Reference](https://www.synpath.dev/docs) for detailed documentation and more examples.
 
 ## Development
 
@@ -167,7 +169,7 @@ 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.
+[ccxt](https://github.com/ccxt/ccxt) set the conventions this library follows.
 
 ## License
 

{synpath-0.1.0 → synpath-0.2.0}/docs/api.md

@@ -68,7 +68,7 @@ and spot exchanges do not.
 | Method | Returns | Notes |
 |---|---|---|
 | `fetch_markets(query, limit, cursor, status, sort)` | `Page[Market]` | `limit` up to 100 |
-| `fetch_markets_by_ids(ids)` | `list[Market]` | batched (Kalshi 200, Polymarket 100, Polymarket US 50 ids a request), order preserved, closed and settled markets included |
+| `fetch_markets_by_ids(ids)` | `list[Market]` | batched (Kalshi 200, Polymarket 100, Polymarket US 50 ids a request; Opinion has no batch lookup, one request each), order preserved, closed and settled markets included |
 | `fetch_events(query, limit, cursor, status)` | `Page[Event]` | markets nested |
 | `fetch_market(market_id)` | `Market` | |
 | `fetch_order_book(market_id, side, depth)` | `OrderBook` | `side="yes"` (default) or `"no"` |

{synpath-0.1.0 → synpath-0.2.0}/docs/capabilities.md

@@ -6,21 +6,21 @@ Read `has` before you call. A capability a venue lacks raises `NotSupported`
 rather than returning an empty list, so "cannot" is never mistaken for "there
 is nothing".
 
-| Method | `kalshi` | `polymarket` | `polymarket_us` |
-|---|---|---|---|
-| `fetch_markets` | yes | yes | yes |
-| `fetch_events` | yes | yes | yes |
-| `fetch_market` | yes | yes | yes |
-| `fetch_order_book` | yes | yes | yes |
-| `fetch_order_books` (batched) | yes, one request per market | yes, one round trip | yes, one request per market |
-| `fetch_trades` | yes | yes | no public tape over REST; the last trade is on the book |
-| `fetch_ohlcv` | yes, the venue's candles | yes, built from the trade tape, both tokens folded into the YES price; the venue's quote samples via `source="quotes"` | partial: quote-derived bid/ask midpoints, no volume; no public tape to build from |
-| `fetch_series` | yes | no series tier | yes, but fees are per market, not per series |
-| `fetch_fee_schedule` | yes | yes | yes |
-| `search` | yes ([undocumented host](api.md#search)) | yes | yes |
-| `fetch_markets_by_ids` | yes | yes | yes |
-| `sort` | yes, the page is ordered after it is read | yes, at the venue | yes, the page is ordered after it is read; `volume` and `liquidity` cost one read per market |
-| `match_market` / `match_event` | no | no | no |
+| Method | `kalshi` | `polymarket` | `polymarket_us` | `opinion` |
+|---|---|---|---|---|
+| `fetch_markets` | yes | yes | yes | yes, categorical topics flattened into their options |
+| `fetch_events` | yes | yes | yes | yes, one per topic |
+| `fetch_market` | yes | yes | yes | yes; a categorical option costs a second read for its topic |
+| `fetch_order_book` | yes | yes | yes | yes |
+| `fetch_order_books` (batched) | yes, one request per market | yes, one round trip | yes, one request per market | yes, one request per market |
+| `fetch_trades` | yes | yes | no public tape over REST; the last trade is on the book | no public tape; the last trade is on `refresh_quotes` |
+| `fetch_ohlcv` | yes, the venue's candles | yes, built from the trade tape, both tokens folded into the YES price; the venue's quote samples via `source="quotes"` | partial: quote-derived bid/ask midpoints, no volume; no public tape to build from | partial: last-trade samples, hourly or daily, no volume |
+| `fetch_series` | yes | no series tier | yes, but fees are per market, not per series | no series tier |
+| `fetch_fee_schedule` | yes | yes | yes | yes, read from the venue's fee contract on BNB Chain |
+| `search` | yes ([undocumented host](api.md#search)) | yes | yes | partial: no venue search; titles matched here over 25 catalog pages |
+| `fetch_markets_by_ids` | yes | yes | yes | yes, one request per market |
+| `sort` | yes, the page is ordered after it is read | yes, at the venue | yes, the page is ordered after it is read; `volume` and `liquidity` cost one read per market | partial: `volume` and `newest` at the venue; no liquidity figure exists |
+| `match_market` / `match_event` | no | no | no | no |
 
 Polymarket US is the CFTC-regulated exchange, not the on-chain CLOB the
 `polymarket` adapter reads; the two share a brand and nothing else. It has
@@ -29,6 +29,13 @@ marked `derived=True` as on Kalshi. Its catalog payloads carry no volume, no
 sizes and no last trade; `refresh_quotes(market)` reads the book once for all
 of them, and for the market's live state.
 
+Opinion lists *topics*: a binary topic is one market, a categorical topic
+holds one binary market per option, and only those trade. Each topic is an
+event here. Its catalog carries no prices at all, so `refresh_quotes(market)`
+reads both books and the last trade. Statuses `open`, `settled` and `all`
+filter at the venue; `closed` cannot and raises. An API key is optional and
+only raises the rate limit (`Opinion(api_key=...)`).
+
 Matching spans venues, so no adapter claims it. `synpath.match_market(id)`
 and `synpath.match_event(id)` are answered by Synpath's hosted matching service
 at `api.synpath.dev`, with a Synpath API key (the one `synpath keys create` saved, `SYNPATH_API_KEY`, or `api_key=`). See
@@ -56,20 +63,20 @@ install. Polymarket US has two, because the venue has
 two: a retail API any verified account uses, and an exchange API for
 onboarded firms.
 
-| Method | `kalshi` | `polymarket` | `polymarket_us` (retail) | `polymarket_us` (exchange) |
-|---|---|---|---|---|
-| `create_order`, `create_orders` | yes | yes | yes | yes |
-| `cancel_order`, `cancel_orders`, `cancel_all_orders` | yes | yes | yes | yes |
-| `edit_order` | yes, amend or decrease | no; an edit is a cancel and a new order | yes, price, quantity and time in force | yes |
-| `fetch_order`, `fetch_open_orders` | yes | yes | yes | yes |
-| `fetch_orders` (by status or time) | yes | no | no | yes, rationed to 12 requests a minute |
-| `fetch_my_trades` | yes | yes | no; the activity feed carries no order id | yes |
-| `fetch_positions`, `fetch_balance` | yes | yes | yes | yes |
-| `fetch_settlements` | yes | yes, from the redemption activity | yes | no |
-| `fetch_queue_position` | yes | no | no | no |
-| `fetch_fee_estimate` | yes | yes | yes | yes |
-| `rfq` | yes | no | no | no |
-| `split_merge` | no; contracts are not tokens | partial: Deposit Wallets and EOAs | no | no |
+| Method | `kalshi` | `polymarket` | `polymarket_us` (retail) | `polymarket_us` (exchange) | `opinion` (not yet live-tested) |
+|---|---|---|---|---|---|
+| `create_order`, `create_orders` | yes | yes | yes | yes | one at a time; `market` and `ioc` are limits with the rest cancelled |
+| `cancel_order`, `cancel_orders`, `cancel_all_orders` | yes | yes | yes | yes | one at a time; `cancel_all_orders` lists then cancels |
+| `edit_order` | yes, amend or decrease | no; an edit is a cancel and a new order | yes, price, quantity and time in force | yes | no |
+| `fetch_order`, `fetch_open_orders` | yes | yes | yes | yes | yes |
+| `fetch_orders` (by status or time) | yes | no | no | yes, rationed to 12 requests a minute | yes, by status |
+| `fetch_my_trades` | yes | yes | no; the activity feed carries no order id | yes | yes, confirmed fills |
+| `fetch_positions`, `fetch_balance` | yes | yes | yes | yes | yes |
+| `fetch_settlements` | yes | yes, from the redemption activity | yes | no | no |
+| `fetch_queue_position` | yes | no | no | no | no |
+| `fetch_fee_estimate` | yes | yes | yes | yes | yes, from the fee contract, 0.25 USDT minimum |
+| `rfq` | yes | no | no | no | no |
+| `split_merge` | no; contracts are not tokens | partial: Deposit Wallets and EOAs | no | no | no |
 
 Order types are a separate question. A venue holds `limit` and `market`;
 everything else -- stops, icebergs, brackets, TWAP, pegs -- is held by the
@@ -93,6 +100,8 @@ Every stream answers the `watch_*` keys the same way
 | `PolymarketUSPrivateStream` | no | no | no | no | yes | yes | yes | yes |
 | `PolymarketUSExchangeMarketDataStream` | yes | yes | no | no | no | no | no | no |
 | `PolymarketUSExchangeOrderStream` | no | no | no | no | yes | yes | no | no |
+| `OpinionMarketStream` | yes | partial | yes | no | no | no | no | no |
+| `OpinionUserStream` | no | no | no | no | yes | yes | no | no |
 
 The exchange API's other gRPC streams carry one thing each and say so:
 drop copy and trade capture carry fills, position and position-change carry

{synpath-0.1.0 → synpath-0.2.0}/docs/engine.md

@@ -159,8 +159,12 @@ bound would walk each book to its end; a limit order on a bucket is refused. The
 lays the members' books side by side in bucket terms, a flipped member's
 YES book read as its NO book, prices every level net of the taker fee, and
 walks from the best net price to that worst price. A leg under its venue's minimum
-is dropped and its size moves to the next venue. The legs never sum to
-more than was asked.
+-- in contracts, or in value where the venue counts value (Opinion: 5 USDT
+of the token bought) -- is dropped and its size moves to the next venue. A
+venue that charges a minimum fee per order (Opinion: 0.25 USDT) has the
+floor added to each leg's cost: a leg it pushes past the worst price is
+dropped, and one whose size fills as fully for less elsewhere is moved. The
+legs never sum to more than was asked.
 
 The parent re-plans whenever a leg fills, a book moves or a leg is pulled.
 A leg still at a price the plan wants is kept, so it holds its place in the

{synpath-0.1.0 → synpath-0.2.0}/docs/streaming.md

@@ -31,6 +31,8 @@ asyncio.run(main())
 | `PolymarketUserStream` | CLOB user channel | CLOB API credentials, or a `PolymarketTrading` to derive them | orders; fills with settlement state |
 | `PolymarketUSMarketStream` | `api.polymarket.us/v1/ws/markets` | retail API key | full books, top of book, trades, market state |
 | `PolymarketUSPrivateStream` | `api.polymarket.us/v1/ws/private` | retail API key | orders, fills, positions, balances |
+| `OpinionMarketStream` | `ws.opinion.trade` | Opinion API key (every channel needs one) | books, trades, last prices |
+| `OpinionUserStream` | `ws.opinion.trade` | Opinion API key | orders; fills once the chain confirms them |
 
 Each stream's `has` answers the `watch_*` capability keys (`watch_order_book`,
 `watch_ticker`, `watch_trades`, `watch_market_status`, `watch_orders`,
@@ -85,6 +87,15 @@ jittered exponential backoff between attempts.
   a fresh snapshot.
 - *Polymarket US* sends the whole visible book every time, so books cannot
   drift.
+- *Opinion* sends one changed level per message, with no snapshot and no
+  sequence number. The stream reads each book over REST once the
+  subscription is live and replays the changes that arrived during the read.
+  A change is read as the level's whole size (the venue documents `size` as
+  the level's shares), so replaying one the snapshot already holds is
+  harmless; `tests/test_opinion_ws_live.py` checks this against the venue.
+  Nothing in the feed reveals a missed message, so every book is read again
+  on a timer (`resync_interval`, 60 s by default): a book that disagrees
+  while no change was in flight is a `gap`, and is replaced.
 
 **A book is right or marked not ready.** After a gap or a disconnect the
 book's `ready` is false until a snapshot arrives; deltas are not applied to
@@ -214,6 +225,10 @@ documented heartbeat and rely on gRPC keepalive.
   covers.
 - **Polymarket US:** built to the venue's documentation and SDK, with the
   envelope spellings both of them accept.
+- **Opinion:** built to the venue's documentation and SDK samples, with the
+  REST books recorded for the read adapter. `tests/test_opinion_ws_live.py`
+  checks streamed books against the venue's own over a live minute; it needs
+  `OPINION_API_KEY`.
 - **Polymarket US exchange API (gRPC):** a real local gRPC server speaking
   the venue's own compiled messages. It covers a refused token, a snapshot,
   an execution report and a drop, and a drop-copy resume token surviving a

{synpath-0.1.0 → synpath-0.2.0}/docs/trading.md

@@ -53,6 +53,7 @@ they point at and the public half of the identity. It prints no secret.
 | Polymarket | `POLYMARKET_PRIVATE_KEY`, `POLYMARKET_SIGNATURE_TYPE` (3 Deposit Wallet, used by every account created since May 2026 and what `synpath init` suggests; 1 proxy, 2 Safe, 0 allowlisted EOA, which is also what an unset value means), `POLYMARKET_FUNDER` (the wallet address, required for 1-3); optional `POLYMARKET_API_KEY` / `_API_SECRET` / `_API_PASSPHRASE` (derived when absent), `POLYMARKET_BUILDER_CODE`, `POLYMARKET_RELAYER_API_KEY` / `_RELAYER_API_KEY_ADDRESS` (gasless wallet transactions), `POLYMARKET_RPC_URL` (an EOA's own transactions) |
 | Polymarket US, retail API | `POLYMARKET_US_KEY_ID`, `POLYMARKET_US_SECRET_KEY` (from polymarket.us/developer) |
 | Polymarket US, exchange API | `POLYMARKET_US_CLIENT_ID`, `POLYMARKET_US_PRIVATE_KEY_PATH`, `POLYMARKET_US_PARTICIPANT_ID`, `POLYMARKET_US_ACCOUNT` (optional), `POLYMARKET_US_ENV` = `preprod` or `prod` |
+| Opinion | `OPINION_PRIVATE_KEY` (the wallet connected on opinion.trade), `OPINION_API_KEY` (`synpath init` creates it by signing with that wallet), `OPINION_MULTISIG_ADDRESS` (optional; the account's Safe, read from the venue when absent) |
 
 ## Through your own server
 
@@ -316,3 +317,32 @@ five-second latency stopgap, not a rate limit, and maps to `OrderRejected`
 with `reason="latency_stopgap"`: safe to resend. Venue `day` orders do not
 cancel at the session roll, so `day` is refused here as on the other venues.
 
+## Opinion
+
+`OpinionTrading`. **Not yet tested against the live venue**: it is built to
+Opinion's documentation and its own SDK, with signing and amounts checked
+byte for byte against the SDK's code. Start small.
+
+Orders are the CTF exchange's EIP-712 `Order` on BNB Chain, signed by the
+wallet for the account's Safe, which holds the USDT and the tokens; the
+Safe's address is read from the venue when not configured. YES and NO are
+separate tokens, as on Polymarket: `buy` buys YES, `sell` buys NO at
+`1 - price`, and with `reduce_only` they sell the tokens held instead.
+
+The venue rests limit orders until cancelled and has nothing else: no time
+in force, no post-only, and a market buy that spends a USDT amount rather
+than taking a number of contracts. So `market` and `ioc` are sent as a limit
+at the price given and the unmatched rest is cancelled at once; `fok`, `gtd`
+and `post_only` are refused. The two amounts of an order must state its
+price exactly, which trims the size to four significant digits of its USDT
+value: the order's `amount` is what was actually sent. The minimum order is
+5 USDT. Fees are taker only, `rate * notional * p * (1 - p)` with the rate
+read from the venue's fee contract, and at least 0.25 USDT an order.
+
+A match moves an order's filled figures, and produces a trade, only once the
+chain confirms it. `OpinionUserStream` carries both
+([Streaming](streaming.md)). The one-time approvals ("enable trading") are
+made on opinion.trade; split, merge and redeem are not built here.
+
+Opinion's terms bar residents and citizens of several countries, the UK and
+US among them: check them before trading.

{synpath-0.1.0 → synpath-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "synpath"
-version = "0.1.0"
+version = "0.2.0"
 description = "One API for prediction markets. Kalshi and Polymarket, normalized, with every price labelled by source and time."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -57,7 +57,7 @@ Homepage = "https://synpath.dev"
 Documentation = "https://synpath.dev/docs"
 Repository = "https://github.com/Synpath-ai/synpath"
 Issues = "https://github.com/Synpath-ai/synpath/issues"
-Discord = "https://discord.gg/QZzsHTpGA3"
+Discord = "https://synpath.dev/discord"
 
 [tool.hatch.build.targets.wheel]
 packages = ["synpath"]

{synpath-0.1.0 → synpath-0.2.0}/synpath/__init__.py

@@ -42,6 +42,7 @@ from .errors import (
 from .kalshi import Kalshi
 from .polymarket import Polymarket
 from .polymarket_us import PolymarketUS
+from .opinion import Opinion
 from .matching import match_event, match_market
 from .history import fetch_order_book_at, fetch_order_book_range, fetch_trades_range
 from .bucket import Bucket, BucketMember, BucketOrderReport, BucketPosition
@@ -75,12 +76,13 @@ from .types import (
     TradesRangeResponse,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 exchanges: dict[str, type[Exchange]] = {
     "kalshi": Kalshi,
     "polymarket": Polymarket,
     "polymarket_us": PolymarketUS,
+    "opinion": Opinion,
 }
 """Every venue this library speaks, by id."""
 
@@ -101,6 +103,7 @@ def exchange(venue: str, **kwargs) -> Exchange:
 # keeps working. Imported last, after the read API it builds on.
 from .trading import (
     TradingExchange, KalshiTrading, PolymarketTrading, PolymarketUSTrading, PolymarketUSExchangeTrading,
+    OpinionTrading,
     Account, Balance, EditRequest, FeeEstimate, Fill, HeldBy, Liquidity,
     Order, OrderRequest, OrderStatus, OrderType, Position, PositionSide,
     Precision, Settlement, SettlementState, Side, TimeInForce,
@@ -128,6 +131,7 @@ _STREAM_CLASSES = (
     "PolymarketUSExchangeTradeCaptureStream", "PolymarketUSExchangePositionChangeStream",
     "PolymarketUSExchangeInstrumentStream", "PolymarketUSExchangePositionStream",
     "PolymarketUSExchangeMarketDataStream", "PolymarketUSExchangeBalanceLedgerStream",
+    "OpinionMarketStream", "OpinionUserStream",
 )
 _SERVER_NAMES = ("create_app", "create_trading_app", "VenueRegistry", "ControlStore", "Principal")
 
@@ -149,7 +153,7 @@ def __getattr__(name: str):
 
 
 __all__ = [
-    "Kalshi", "Polymarket", "PolymarketUS", "Exchange", "exchange", "exchanges",
+    "Kalshi", "Polymarket", "PolymarketUS", "Opinion", "Exchange", "exchange", "exchanges",
     "Capability", "HttpClient", "RateLimiter",
     "Market", "Event", "Outcome", "Quote", "MarketStats", "OrderBook",
     "OrderLevel", "Trade", "Candle", "FeeSchedule", "Series", "Page",
@@ -166,6 +170,7 @@ __all__ = [
     "MarketNotFound", "NotSupported", "AuthenticationError",
     # order entry
     "TradingExchange", "KalshiTrading", "PolymarketTrading", "PolymarketUSTrading", "PolymarketUSExchangeTrading",
+    "OpinionTrading",
     "Account", "Balance", "EditRequest", "FeeEstimate", "Fill", "HeldBy", "Liquidity",
     "Order", "OrderRequest", "OrderStatus", "OrderType", "Position", "PositionSide",
     "Precision", "Settlement", "SettlementState", "Side", "TimeInForce",

{synpath-0.1.0 → synpath-0.2.0}/synpath/client.py

@@ -353,4 +353,9 @@ def _polymarket_us(creds: Credentials) -> TradingExchange:
     return PolymarketUSTrading(creds)  # type: ignore[arg-type]
 
 
-_TRADING = {"kalshi": _kalshi, "polymarket": _polymarket, "polymarket_us": _polymarket_us}
+def _opinion(creds: Credentials) -> TradingExchange:
+    from .trading.opinion import OpinionTrading
+    return OpinionTrading(creds)  # type: ignore[arg-type]
+
+
+_TRADING = {"kalshi": _kalshi, "polymarket": _polymarket, "polymarket_us": _polymarket_us, "opinion": _opinion}

{synpath-0.1.0 → synpath-0.2.0}/synpath/engine/__main__.py

@@ -60,6 +60,7 @@ ADAPTERS = {
     "polymarket": ("..trading.polymarket", "PolymarketTrading"),
     "polymarket_us": ("..trading.polymarket_us", "PolymarketUSTrading"),
     "polymarket_us_exchange": ("..trading.polymarket_us_exchange", "PolymarketUSExchangeTrading"),
+    "opinion": ("..trading.opinion", "OpinionTrading"),
 }
 
 

{synpath-0.1.0 → synpath-0.2.0}/synpath/engine/feeds.py

@@ -71,6 +71,13 @@ def default_streams(adapters: Mapping[str, Any], credentials: Mapping[str, Any])
         elif venue == "polymarket_us" and creds is not None:
             from ..ws.polymarket_us import PolymarketUSMarketStream, PolymarketUSPrivateStream
             out[venue] = VenueStreams(market=PolymarketUSMarketStream(creds), private=PolymarketUSPrivateStream(creds))
+        elif venue == "opinion" and creds is not None:
+            from ..ws.opinion import OpinionMarketStream, OpinionUserStream
+            catalog = getattr(adapter, "catalog", None)
+            out[venue] = VenueStreams(
+                market=OpinionMarketStream(api_key=creds.api_key, catalog=catalog),
+                private=OpinionUserStream(api_key=creds.api_key, catalog=catalog),
+            )
         else:
             log.info("synpath.engine.feeds: no stream for %s; its orders reach the engine by polling", venue)
     return out