skewtape 0.1.3__tar.gz

skewtape-0.1.3/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+# skewtape-python's tests on every push to main and every pull request: the
+# client against a mock API from testdata/, on the floor Python (3.11) and
+# the newest. This file is kept in the tape repository
+# (sdk/python/.github/workflows) and mirrored here by each release
+# (scripts/sdk-release.sh): change it there.
+
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    name: tests (Python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.9.7"
+
+      - name: Tests
+        run: uv run --locked --python "${{ matrix.python }}" --group dev pytest -q

skewtape-0.1.3/.github/workflows/publish.yml

@@ -0,0 +1,98 @@
+# Publish skewtape to PyPI on the vX.Y.Z tag that tape's release pushes here
+# (tape's release-sdks.yml and scripts/sdk-release.sh), by trusted
+# publishing: no token is stored anywhere. PyPI trusts this workflow file, in
+# this repository, in the pypi environment. The build job tests and builds
+# with no token in reach; only the publish job may ask GitHub for the OIDC
+# token, and it runs no code of the package's. This file is kept in the tape
+# repository (sdk/python/.github/workflows) and mirrored here by each
+# release: change it there.
+#
+# TODO(decision): Olivier adds the trusted publisher on PyPI (for a new
+# project, a pending publisher: project name skewtape, owner skewtape,
+# repository skewtape-python, workflow publish.yml, environment pypi), and
+# decides the package name. The licence is MIT (LICENSE, mirrored with the
+# package).
+
+name: publish
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  # A tag whose push started no run (api/v0.1.2, 15 Nov 2026) is published by
+  # hand on that tag: gh workflow run publish.yml --ref vX.Y.Z. A run on a
+  # branch stops at the version check.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: test and build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.9.7"
+
+      # The release sets the version module from the same X.Y.Z it tags.
+      - name: The tag is the package's version
+        run: |
+          set -euo pipefail
+          if [ "${GITHUB_REF_TYPE}" != "tag" ]; then
+            echo "::error::run it on a vX.Y.Z tag: gh workflow run publish.yml --ref vX.Y.Z"
+            exit 1
+          fi
+          want="${GITHUB_REF_NAME#v}"
+          got="$(sed -nE 's/^__version__ = "([^"]+)"$/\1/p' src/skewtape/version.py)"
+          if [ "${got}" != "${want}" ]; then
+            echo "::error::the tag is ${GITHUB_REF_NAME} but src/skewtape/version.py says ${got:-nothing}"
+            exit 1
+          fi
+
+      - name: Tests
+        run: uv run --locked --python 3.11 --group dev pytest -q
+
+      - name: Build the wheel and the sdist
+        run: uv build --out-dir dist
+
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    name: publish to PyPI
+    needs: [build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/skewtape/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+
+      # Attestations sign each file in the public Sigstore log, with this
+      # repository's name: only once the repository is public.
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+        with:
+          attestations: ${{ !github.event.repository.private }}

skewtape-0.1.3/.gitignore

@@ -0,0 +1,7 @@
+# Mirrored into skewtape-python by scripts/sdk-release.sh (the package is
+# staged in tape under sdk/python). Local environments and build output.
+.venv/
+dist/
+__pycache__/
+.pytest_cache/
+*.egg-info/

skewtape-0.1.3/AGENTS.md

@@ -0,0 +1,107 @@
+<!-- Rendered from tape's sdk/agents/AGENTS.md.tmpl by scripts/sdk-agents.py. Do not edit: change the template in tape. -->
+
+# AGENTS.md: skewtape (Python)
+
+For a coding agent working in this repository, or with the `skewtape` package in another one. Skewtape serves prediction-market history from every venue it covers in one schema: markets, fills, candles, fees and resolutions, and matched events that link the same question across venues. This package is the Python client of its API ([docs.skewtape.com](https://docs.skewtape.com)).
+
+## Install
+
+```bash
+pip install skewtape
+```
+
+Python 3.11 or later. The dependencies are httpx and attrs; `pip install 'skewtape[kalshi]'` adds what signing requests with a Kalshi key needs.
+
+## Authenticate
+
+Every call sends the key in the `X-API-Key` header. The client reads it from `SKEWTAPE_API_KEY`, or takes it as an argument. Keys start with `st_live_` and come from the dashboard ([docs.skewtape.com/keys](https://docs.skewtape.com/keys)). Never commit a key, print it or put it in a URL.
+
+```bash
+export SKEWTAPE_API_KEY=st_live_...
+```
+
+```python
+import datetime as dt
+
+import skewtape
+
+sk = skewtape.Skewtape()  # the key from SKEWTAPE_API_KEY, or skewtape.Skewtape(api_key=...)
+```
+
+## The five most common calls
+
+The examples use a dated window, 2 to 3 November 2026: keep examples static and dated, never live.
+
+1. **Matched events**: the same question across venues, with a confidence and whether every member resolves the same way. One by id with `get`.
+
+```python
+for event in sk.events(min_confidence=0.9, resolution_equal=True):
+    print(event.event_id, [m.venue for m in event.members])
+event = sk.events.get("st_evt_00412")
+```
+
+2. **Markets** of one venue, with their outcomes, status and `fee_category`. Iterating a list reads every page, one call each against the plan's monthly calls, so read the pages you need: this reads the first.
+
+```python
+page = next(sk.markets(venue="kalshi").pages())
+for market in page:
+    print(market.market_id, market.status, market.fee_category)
+```
+
+3. **Fills** of a matched event (or of a venue and market) over a window, maker legs by default. Sizes and notionals are exact integers in raw units: divide by `10 ** decimals`. Fills are on the Builder and Pro plans.
+
+```python
+since = dt.datetime(2026, 11, 2, tzinfo=dt.timezone.utc)
+until = dt.datetime(2026, 11, 3, tzinfo=dt.timezone.utc)
+for fill in sk.fills(event_id="st_evt_00412", since=since, until=until):
+    print(fill.venue, fill.ts, fill.price, fill.size_raw, fill.decimals)
+```
+
+4. **Candles** of one size (1m, 1h or 1d) over the same window. Builder and Pro read every venue at every size; Free and History read Polymarket `1d` candles only, so this `1h` read is `403 forbidden_plan` there. The generated model names the open price `open_`, since `open` is a Python builtin.
+
+```python
+for candle in sk.candles(res="1h", event_id="st_evt_00412", since=since, until=until):
+    print(candle.ts, candle.open_, candle.close, candle.volume)
+```
+
+5. **Fee schedules**, to net fees out of a fill: the row in force for a market's `fee_category` at the fill's time, and the fee it gives.
+
+```python
+rows = list(sk.fees(venue="kalshi"))
+row = skewtape.select_fee_row(rows, "kalshi", "quadratic:1", since)
+if row is not None:
+    print(row.category, skewtape.taker_fee_raw(row, 10_000_000_000, 4_000_000_000, 8))
+```
+
+Every list pages itself: iterate for every item, `.pages()` for the pages, `.first()` for the first item. Nothing is fetched until you iterate.
+
+## More
+
+- `sk.venues()`: the venues and their flags. `sk.resolutions(venue=..., market_id=[...])`: how and when each market resolved, of up to 100 markets at a time. `sk.pairs(...)`: matched events with exactly two active members.
+- `sk.quote(event_id, outcome=..., side=..., size=...)`: the best venue, or a split across venues, for a size of one outcome of a matched event once each venue's taker fee is counted. One metered call reads the quote context; the books are read from each venue by a client that never carries the key. It places nothing.
+- `sk.backtest(trades)`: fee-aware P&L for trades you supply, over the recorded history. It is arithmetic on history: it forecasts nothing, suggests no trade and optimises nothing. A trade no fee row covers is refused: give its `fee_category` on the trade, or pass `on_missing_fee="zero"` to count its fee as zero with a warning.
+- `sk.download(url, dest)` and `sk.download.verify(folder)`: bundle files, resumed and checked against their sha256.
+- `sk.kalshi()`: an optional read-only client of Kalshi's own API, under your own Kalshi membership. It is not how Skewtape's Kalshi data is delivered.
+- `skewtape.route(venue=..., ...)` (also `sk.route`): an unsigned order for Polymarket, DFlow or Hyperliquid with your own builder code or fee. It never signs, never sends and never takes a private key; you sign and send it. `skewtape.geoblock.polymarket()` asks Polymarket whether it takes orders from this machine's location: one indication, not a licence.
+
+## Errors and limits
+
+A `429 rate_limited` is retried after the server's `Retry-After`; a `429 lookup_rate_limited` (too many invalid keys from the address) is not, and raises `AuthenticationError`: fix the key. Every other error raises a `SkewtapeError` subclass with the API's `code`, `message`, `docs_url` and `request_id`: `ForbiddenPlanError` names the plan a route needs, `QuotaExceededError` says when the monthly quota resets. Quote the `request_id` to support.
+
+## Generated code
+
+`src/skewtape/_generated/` is generated from Skewtape's public OpenAPI document by pinned generators, in the tape repository, and replaced whole on every release. Never edit it: a change there is lost and fails the release's check. Hand-written code lives beside it (`src/skewtape/client.py`, `quote.py`, `quote_math.py`, `route.py`, `route_hyperliquid.py`, `geoblock.py`, `backtest.py`, `fees.py`, `kalshi.py`, `download.py`, `errors.py`); a change the API needs goes to the API first. This file is rendered from a template in tape too.
+
+## Rules
+
+- **No custody.** Skewtape never holds funds, wallets, keys to them or orders. This package reads data and builds unsigned orders (`route`): it has no call that places an order, moves funds or signs a transaction. `sk.kalshi()` signs read requests with your own Kalshi key, which stays on your machine. Do not add code that sends funds or orders through Skewtape.
+- **Static, dated examples.** Examples and docs use dated windows and recorded data, never live prices.
+- **Copy.** Say "matched event" (a pair is a matched event with exactly two active members).
+
+## Tests
+
+```bash
+uv run --locked --group dev pytest
+```
+
+The tests run against a mock API and recorded data in `testdata/` and `conformance/`; they make no network call. The code blocks of this file are among them.

skewtape-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blockbrainers SAS (Skewtape)
+
+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.

skewtape-0.1.3/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.5
+Name: skewtape
+Version: 0.1.3
+Summary: Skewtape API client: prediction-market data across venues in one schema, with matched events.
+Project-URL: Documentation, https://docs.skewtape.com
+Project-URL: Source, https://github.com/skewtape/skewtape-python
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: attrs>=23.1
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: kalshi
+Requires-Dist: cryptography>=42; extra == 'kalshi'
+Description-Content-Type: text/markdown
+
+# skewtape
+
+Prediction-market data from every venue Skewtape serves, in one schema: markets, fills, candles, fees and resolutions, with matched events that link the same question across venues. This is the Python client for the [Skewtape API](https://docs.skewtape.com).
+
+```bash
+pip install skewtape
+export SKEWTAPE_API_KEY=st_live_...   # a key from the dashboard, docs.skewtape.com/keys
+```
+
+```python
+import skewtape
+
+sk = skewtape.Skewtape()  # or Skewtape(api_key="st_live_...")
+
+for venue in sk.venues():
+    print(venue.key, venue.flags)
+
+# Matched events: the same question across venues, with a confidence and
+# whether every member resolves the same way.
+for event in sk.events(min_confidence=0.9, resolution_equal=True):
+    print(event.event_id, event.question_canonical, [m.venue for m in event.members])
+
+event = sk.events.get("st_evt_00412")
+
+# Markets of one venue. Iterating a list reads every page, one call each
+# against your plan's monthly calls, so this reads the first page only.
+page = next(sk.markets(venue="kalshi").pages())
+for market in page:
+    print(market.market_id, market.status, market.fee_category)
+
+# Fills of a matched event over a dated window (maker legs by default).
+# Fills are on the Builder and Pro plans: a Free or History key gets a
+# ForbiddenPlanError here.
+from datetime import datetime, timezone
+
+since = datetime(2026, 11, 2, tzinfo=timezone.utc)
+until = datetime(2026, 11, 3, tzinfo=timezone.utc)
+for fill in sk.fills(event_id="st_evt_00412", since=since, until=until):
+    print(fill.venue, fill.ts, fill.price)
+
+# Pairs: matched events with exactly two active members.
+pairs = list(sk.pairs(min_confidence=0.9))
+```
+
+The quickstart above is run against a mock API by the package's tests, so it stays current.
+
+- Every list (`markets`, `events`, `pairs`, `fills`, `candles`, `resolutions`, `fees`) returns a `Paginated`: iterate for every item across pages, `.pages()` for the pages, `.first()` for the first item. Nothing is fetched until you iterate. `markets(resolved=...)` filters on the client, so every page is still fetched: pass a venue or market ids with it.
+- A `429 rate_limited`, or a `429` with no error body as a proxy sends, is retried with the server's `Retry-After` (three times by default, `max_retries=`). A `429 lookup_rate_limited` (too many invalid keys from your address) raises `AuthenticationError` at once: fix the key. A `429 quota_exceeded` raises `QuotaExceededError` at once, with `resets_at` and `upgrade_url`. Any other error raises a `SkewtapeError` subclass (`AuthenticationError`, `ForbiddenPlanError` with `.plan`, `BlockedError` with `.block_reason_code`, `NotFoundError`, `RateLimitError`, `QuotaExceededError`, `ServerError`), carrying the API's `code`, `message`, `docs_url` and `request_id`.
+- `sk.download.bundles()` lists the History snapshots and monthly deltas your account may download, and `sk.download.bundle(bundle_id, folder)` fetches one whole, resuming a partial download, checking each file's sha256 and the folder's `CHECKSUMS.sha256`; `sk.download.file(bundle_id, path, dest)` fetches one file. They need a key on the Builder or Pro plan (a History purchase downloads from the dashboard), and the file host never sees the key. `sk.download(url, dest, sha256=...)` fetches a link you already hold; `sk.download.verify(folder)` checks a folder.
+- Withheld fields read `None` with `blocked` true and `block_reason_code` on the row: see [Data rights and geoblocking](https://docs.skewtape.com/rights).
+- `sk.quote(event_id, outcome=..., side=..., size=...)` is the best venue, or split across venues, for a size of one outcome of a matched event once each venue's taker fee is counted ([Quotes](https://docs.skewtape.com/quote)). It places nothing. One metered call reads the quote context; the books are read from each venue, from your machine, by a client that never carries your key. Amounts are integers in millionths (`net_micros`, `net_avg_price_micros`, ...). A venue that cannot be reached is left out and named in `skipped`, and none reachable raises `VenueUnreachableError`; members that do not resolve alike raise `RuleMismatchError` unless `allow_rule_mismatch=True`; a venue whose fee is unknown (no fee row, or one the data policy withholds) is never compared with one whose fee is known: when a venue whose fee is known can fill some of the size, it is left out of the plan, quoted alone in `venues` before fees, and `warnings` says so (otherwise they are compared before fees, and `warnings` says the fee is not counted). Kalshi's book is Kalshi's public orderbook, read with no key (a `kalshi_dflow` member waits for DFlow access and is left out); any venue's reader can be replaced in `book_readers`.
+
+```python
+# The best venue, or split, for 100 contracts of "yes" once each taker fee is
+# counted: one metered call, then each venue's book. It places nothing.
+q = sk.quote("st_evt_00412", outcome="yes", side="buy", size=100)
+print(q.plan, q.filled_micro, q.net_avg_price_micros, [(leg.venue, leg.size_micro) for leg in q.legs])
+for skip in q.skipped:
+    print("left out:", skip.venue, skip.reason, skip.detail)
+for warning in q.warnings:
+    print("warning:", warning)
+```
+
+## Backtest: fee-aware P&L on the record
+
+`sk.backtest(trades)` replays trades you supply over the history Skewtape records and gives their P&L before and after fees. It is arithmetic on history: it forecasts nothing, suggests no trade and optimises nothing.
+
+```python
+# Two trades on a real Kalshi market that resolved yes on 3 Nov 2026; the prices are illustrative, not the market's.
+trades = [
+    {"venue": "kalshi", "market_id": "KXKBORFI-26NOV030430SAMKTW-Y", "token_id": "yes", "side": "buy", "ts": "2026-11-02T10:00:00Z", "size": "100", "price": "0.40"},
+    {"venue": "kalshi", "market_id": "KXKBORFI-26NOV030430SAMKTW-Y", "token_id": "yes", "side": "sell", "ts": "2026-11-02T20:00:00Z", "size": "30", "price": "0.62"},
+]
+result = sk.backtest(trades, as_of=datetime(2026, 11, 4, tzinfo=timezone.utc))
+print(result.totals.pnl, result.totals.pnl_before_fees, result.totals.fees)
+for position in result.positions:
+    print(position.token_id, position.status, position.outcome, position.pnl_raw)
+```
+
+- **Prices.** A trade carries `price` (0 to 1) or an exact `notional_raw`, or neither: then the last fill (`history="fills"`, the default, Builder and Pro) or candle (`history="candles"`, `candle_res=`, `1h` by default; any size on Builder and Pro, Polymarket `1d` only on Free and History) at or before its time prices it. A candle prices a time only once its bucket has ended. `lookback` (a day by default) is how far back it looks, a candle more for candles. An open position at `as_of` is marked the same way. Trades that all carry a price, on markets resolved by `as_of`, read no fills or candles, so they run on every plan.
+- **What it reads.** The fee rows of the trades' venues, their markets and those markets' resolutions (a request per 100 markets), and the history windows above. Pass any of them (`fees=`, `markets=`, `resolutions=`, `fills=`, `candles=`) to read nothing for it.
+- **Fees.** The schedule row in force for the market's `fee_category` at the trade's time, as on [Fees](https://docs.skewtape.com/fees); `role="maker"` pays the maker fee where the venue charges one. A trade no row covers is refused, and the error names it. Where the data policy withholds a market's `fee_category` (the market row reads `blocked` true), give it on the trade (`fee_category=`), or pass `on_missing_fee="zero"` to count the fee as zero with a warning.
+- **Value.** At `as_of` (now by default), each position is worth what its market resolved to (1 a share for the outcome it resolved to, 0 for the other), or, still open, the last price on record. A market whose current word is a reversal (it resolved, then the venue's word changed) is valued as open, at the last price on record, so it needs the history read on its window. A voided market is valued only with `void_payout=`, since what a venue pays on a void is its rule. Nothing after `as_of` is read.
+- **Exact.** Amounts are integers in raw units (`totals.decimals`), prices exact fractions; `run_backtest(...)` is the same arithmetic over data you pass in, with no request. `conformance/backtest.json` pins it; the TypeScript SDK passes the same vectors, and every fee in them is checked against Skewtape's own fee code. `taker_fee_raw`, `maker_fee_raw` and `select_fee_row` are exported for fills you price yourself.
+
+## Kalshi, live and optional
+
+Skewtape's Kalshi data (markets, fills, candles, resolutions) comes from the calls above, under the Kalshi data licence. `sk.kalshi()` is something else: an optional live client that calls Kalshi's Trade API from your machine, under your own Kalshi membership, for a reading of the live venue beside that history. It is read only, writes nothing to disk, and never talks to a Skewtape host.
+
+```python
+kalshi = sk.kalshi()  # public requests; with your own key: sk.kalshi(access_key=key_id, private_key=pem)
+
+# The live Kalshi markets of a matched event, found by the ticker its kalshi
+# and kalshi_dflow members share.
+event = sk.events.get("st_evt_00412")
+for market in kalshi.markets_for(event):
+    print(market.ticker, market.status, market.yes_bid_dollars, market.yes_ask_dollars)
+
+book = kalshi.orderbook("KXKBORFI-26NOV030430SAMKTW-Y", depth=5)
+print(book.best_yes_bid, book.best_no_bid)
+
+for trade in kalshi.trades(ticker="KXKBORFI-26NOV030430SAMKTW-Y", since=since):
+    print(trade.created_time, trade.taker_outcome_side, trade.yes_price_dollars, trade.count_fp)
+
+sticks = kalshi.candlesticks("KXKBORFI-26NOV030430SAMKTW-Y", period="1h", since=since)
+```
+
+- `kalshi.markets(status=, series_ticker=, event_ticker=, tickers=)`, `kalshi.market(ticker)`, `kalshi.trades(ticker=, since=, until=)`, `kalshi.orderbook(ticker, depth=)` and `kalshi.candlesticks(ticker, period=, since=, until=)` (`1m`, `1h` or `1d`; a Kalshi `1d` stick is a New York day). `kalshi.tickers(event)` and `kalshi.markets_for(event)` read a matched event's `kalshi` and `kalshi_dflow` members, whose `market_id` is the Kalshi ticker.
+- Prices and counts are Kalshi's own strings; every row keeps the whole JSON object in `.raw`.
+- Kalshi serves older trades and settled markets from its `/historical` routes, past a cutoff that moves, and this client does not call them: for that history use `sk.fills` and `sk.markets`.
+- Your key goes in the arguments, from wherever you keep it; the client reads no environment variable. With one, every request is signed as Kalshi's docs describe (Ed25519 or RSA; `pip install 'skewtape[kalshi]'` brings the signing) and counts against your account's rate-limit tier. Without one the calls are public requests. Kalshi's terms and rate limits apply to them, not your Skewtape plan.
+- A `429` is retried with a backoff (0.5, 1 and 2 seconds); any other error raises `KalshiError`, a `SkewtapeError` with Kalshi's `code`, `message` and `details`.
+
+## Notebooks
+
+`notebooks/01_parity_spread.ipynb` measures the cross-venue parity spread on the free sample: for the members of a matched event that resolve alike, how far a Yes on one venue and a No on another stray from the one dollar they pay together, hour by hour, before and after each venue's taker fee. It reads the sample's Parquet files with pandas and makes no network call. The sample is not published yet ([docs.skewtape.com/history](https://docs.skewtape.com/history)); once it is, each sample ships the notebook too: unzip it and run the notebook there, or point `SKEWTAPE_SAMPLE_DIR` at the folder.
+
+Two more read a History snapshot (the History plan's files, not open yet), with pandas and DuckDB, and make no network call. Run them in the snapshot's folder, or point `SKEWTAPE_HISTORY_DIR` at it:
+
+- `notebooks/02_longshot_pattern.ipynb`: price and outcome. Every trade in a market with a known result, in ten-cent price bins, with how often its token paid, after Qin and Yang (arXiv 2606.04217, Table 3).
+- `notebooks/03_maker_rebates.ipynb`: the fee table's maker rebates and maker fees, applied to every trade by venue, fee category and month, and the fee a venue reports set against the schedule's.
+
+They describe what happened in the data; they are not forecasts. `pip install pandas pyarrow matplotlib duckdb notebook` runs all three.
+
+`notebooks/charts.py` draws the website's three static charts from an unzipped bundle with this package: the parity spread of one matched event over time, a question two venues list under different rules, and the fee impact on a simple backtest. Each is an SVG and a PNG with the bundle's date in the image, and `charts.json` gives its caption and the code that draws it. It checks the bundle against its checksums, prices fees with the SDK's fee arithmetic, and makes no network call: `pip install skewtape pandas pyarrow matplotlib`, then `python notebooks/charts.py <unzipped bundle> <output folder>`. It holds every title, caption and rule note to the copy rules and stops on a break; `--title EVENT_ID=TEXT` and `--rule-note TEXT` replace the text.
+
+`skewtape._generated` is generated from the public OpenAPI document and never edited by hand; the facade above is this package. `AGENTS.md` tells a coding agent how to use it. The version's major and minor follow the API's version.
+
+## Routing an order with your own code
+
+`skewtape.route(...)` (also `sk.route`) builds an unsigned order and stops there: it never signs, never sends, never takes a private key, and needs no Skewtape key. The builder code or fee it carries is yours; omit it and the order carries none. The package holds no Skewtape code or account, and a test keeps it that way.
+
+```python
+import skewtape
+
+# Polymarket: a V2 order to sign as EIP-712 typed data. exchange is the book's
+# ("ctf", "neg_risk" or "protocol_v2"); tick_size is the book's tick.
+order = skewtape.route(
+    venue="polymarket", exchange="ctf", token_id="71321045679252212594626385532706912750332728571942532289631379312455583992563",
+    side="BUY", price="0.52", size="10", tick_size="0.01", maker=your_address,
+    builder=your_builder_code,  # optional: your bytes32 code from your Polymarket profile
+)
+signature = your_signer(order.typed_data)  # your wallet signs; the SDK never sees a key
+body = order.post_body(signature=signature, owner=your_clob_api_key_id)  # POST /order, with your CLOB credentials
+
+# DFlow (tokenized Kalshi outcome tokens): the GET /order request that returns
+# the unsigned transaction, with your fee and fee account.
+request = skewtape.route(
+    venue="kalshi_dflow", input_mint=usdc_mint, output_mint=outcome_mint, amount=25_000_000,
+    user_public_key=your_users_wallet, platform_fee_scale=50, fee_account=your_fee_token_account,
+)
+# GET request.full_url with your own DFlow key in the request.api_key_header header.
+
+# Hyperliquid HIP-4 outcomes: an order on side 0 or 1 of an outcome (coin
+# "#960" is outcome 96, side 0), signed by the key that trades (an API wallet).
+hl = skewtape.route(
+    venue="hyperliquid", outcome=96, side=0, is_buy=False, price="0.55", size="20",
+    builder=your_builder_address, builder_fee=10,  # optional, yours: 10 is 1 basis point
+)
+body = hl.post_body(your_api_wallet_signer(hl.typed_data))  # POST to hl.exchange_url
+
+# Once per builder, the user's main wallet approves your maximum fee.
+approval = skewtape.hyperliquid_approve_builder_fee(builder=your_builder_address, max_fee_rate="0.01%", signature_chain_id=42161)
+# The wallet signs approval.typed_data; a signer that signs a hash signs approval.digest.
+```
+
+- **Polymarket:** the order is the V2 `Order` (salt, maker, signer, tokenId, makerAmount, takerAmount, side, signatureType, timestamp, metadata, builder), on the exchange's EIP-712 domain: "Polymarket CTF Exchange", version "2" for `ctf` and `neg_risk`, "3" for a Protocol V2 book (`protocol_v2`), Polygon. Amounts follow Polymarket's rounding by tick size. A limit order (`GTC`, `GTD` with `expiration` in Unix seconds) and a market SELL (`FOK`, `FAK`) take `size` in shares; a market BUY takes `amount`, the USD to spend, with `price` the most you pay. `signature_type` is `EOA` (the default; `signer` is the maker), `POLY_PROXY` or `POLY_GNOSIS_SAFE` (pass `signer`). A Deposit Wallet order (`POLY_1271`) is signed through an ERC-7739 wrapper this builder does not produce. Builder fee rates are set on your Polymarket profile, not in the order.
+- **DFlow:** `platform_fee_scale` is DFlow's fee for a prediction market swap, 0 to 999 in thousandths; `platform_fee_bps` its fixed spot fee. Either needs `fee_account`, your token account for the fee mint, which must exist before the trade.
+- **Hyperliquid (HIP-4 outcomes):** the order is an L1 action, signed as a "phantom agent" on the EIP-712 domain "Exchange", chain 1337, so it is signed by a key you hold (usually an API wallet your user approved), not a browser wallet on its own chain. `builder` and `builder_fee` (tenths of a basis point, at most 1000) are yours, both or neither; your user first approves your maximum fee with their main wallet (`hyperliquid_approve_builder_fee`). Prices have at most 5 significant figures and 8 decimals less `sz_decimals` (pass it if you have it: the docs do not give one for outcomes); `tif` is `Gtc`, `Ioc` or `Alo`; `nonce` is now in milliseconds by default. Hyperliquid's HIP-4 page says outcome fees are zero for testing and builders earn on sell orders, its fees page that fees are charged on closing or settling: the order is the same either way.
+- **Your users are your responsibility:** who may trade on which venue, from where, under which terms. `skewtape.geoblock.polymarket()` asks Polymarket whether it would take orders from this machine's network location: `status` is `"allowed"`, `"blocked"` or `"unknown"`, and any failure (network, timeout, an unexpected reply) is `"unknown"`, never `"allowed"`. It is one indication, not a licence.
+
+## Licence
+
+MIT, copyright 2026 Blockbrainers SAS (Skewtape): see [LICENSE](LICENSE).