Skip to main content

vexity

Official Python client for the Vexity options-analytics API.

import vexity

client = vexity.Vexity()                      # reads VEXITY_API_KEY
levels = client.levels("SPX", scope="full")   # the JSON body, as a dict

window = client.window("series", "SPX", names="spot,net_gex_oi", scope="latest", step="1m", span="2h")
update = window.poll()                        # the first call reads the window; later calls read only the tail and merge it

with client.live() as live:                   # zstd socket, redials by the server's own client policy
    live.subscribe("levels", "SPX", scope="full", every_ms=5000)
    for event in live:
        print(event)

What it does for you, with no flags:

  • Sends If-None-Match and stores answers. A 304 saves the body, not the request, and happens only on reads that move slowly (contracts, surface, series envelopes, a window between chain cycles): live levels, frame and grid bodies change every second, so poll them rarely or use the socket. A closed window (immutable) is served from the store with no request, and Vexity(store=EtagStore(directory=...)) keeps it across runs.
  • Window reads a live window once in full (following next_cursor), then asks from=<the step boundary at or before the newest held timestamp> (the newest timestamp itself on an aligned series, so the first returned bucket is a whole one) and merges by the documented rule: drop the held points at or after the answer's first timestamp, append the answer. A step of a session day is read in full each poll. A frame read with neither from nor to is a single frame, not a window. A tail is about 1 % of a full re-read; when resolution_ms, projection_id, compute_version, the view or the lanes change, the window is read again in full.
  • Waits Retry-After (seconds or HTTP date) and paces itself when the key's budget reaches zero; a wait longer than max_wait_s raises RateLimited instead of hanging.
  • Raises typed errors (AuthError, PlanError, Forbidden, NotFound, RateLimited, BadRequest, ServerError, TransportError), each carrying the server's reason, detail and request_id.
  • Live sockets use zstd framing, take every_ms as the server's rung, answer a gap by waiting for the next snapshot, and redial on the generated backoff; a Reconnected event says to read REST once for the span it was down.

Instant reads and sockets ride compact protobuf by default, at compact layout 2 (compact=plugin&compact_layout=2&layout_id=<id>; on sockets the compact.layout.2 feature), the layout that carries every member, the freshness pairs (book_stale, basis_stale, ...) included. A decoded body equals its JSON twin; a member the JSON omits because it does not apply reads None. Windows (Window) follow the same default. Vexity(compact=False), or compact=False on one call, reads JSON instead.

What the pin does and does not promise: layout 2 is the newest layout this release of vexity was generated from (the pin moves with the release, not with the server). The server checks the layout id this release sends and answers 409 when a required member changed, and the SDK checks the layout the server served (the ETag's -cpb2) and the layout a socket negotiated; each failure raises LayoutMismatch and tells you to upgrade vexity or pass compact=False. Layout 2 can still grow in place with optional members: a member this release does not know is skipped with an UnknownMembersWarning naming it, so upgrade when you see one, or read JSON. The warning is raised once per member and process. A server release that adds a member keeps the previous layout id accepted (the register job refuses a release that drops it), so an older SDK keeps working and only warns.

The live socket takes the key in its URL, as the API requires, so keep the websockets logger above DEBUG. The key is read from VEXITY_API_KEY or api_key=; it is masked in repr and never logged.

User-Agent

Requests and the socket send vexity-py/<version>. Pass Vexity(app="myapp/1.2") to append your own name (vexity-py/0.1.0 myapp/1.2) so Vexity can reach heavy users.

Licence and use of the data

The code of this package is MIT licensed. Use of the Vexity API and of the data it returns is governed by the Vexity Terms and Conditions and the Redistribution Policy, not by the MIT licence. In particular the data may be cached transiently, not accumulated into datasets of your own. EtagStore(directory=...) is an opt-in revalidation cache: it keeps closed answers only until their max-age lapses so a re-run does not fetch them again, and it is not an archive. Entries are deleted when their max-age lapses, so a read after that downloads the body again instead of revalidating. Questions: vexity@jzn-management.com.

Metadata

Release files for vexity 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vexity 0.1.0
File Size Uploaded Provenance Actions
vexity-0.1.0.tar.gz 36.4 kB Without provenance Details for vexity-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vexity 0.1.0
File Interpreter ABI Platform Actions
vexity-0.1.0-py3-none-any.whl Python 3 none any Details for vexity-0.1.0-py3-none-any.whl

Total release size: 80.0 kB

Release files / vexity-0.1.0.tar.gz

Download URL vexity-0.1.0.tar.gz
Size 36.4 kB
Tags Source
SHA-256 checksum
How to use checksums
86052adfa27b4cd2e02341b7f9575f29de873dd7f56056bb5aa7ed3588a0290a
BLAKE2b-256 checksum
How to use checksums
b7bcaf3342a34213ed1a0e8dcf51106c92e9d703688115e7a2456d2ab5d17ded
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.0

Release files / vexity-0.1.0-py3-none-any.whl

Download URL vexity-0.1.0-py3-none-any.whl
Size 43.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c77607a4c661b400547f07e3da8d2ae4639645401ff5cd952199e24d09b2aee7
BLAKE2b-256 checksum
How to use checksums
bbce90688d3d991c4fb847586c778201133ed474ed833fab4a13e9d222a1e37e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.0

Security for vexity 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page