typed-grvt 0.1.0__tar.gz

typed_grvt-0.1.0/LICENSE

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

typed_grvt-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: typed-grvt
+Version: 0.1.0
+Summary: A fully typed, validated async client for the GRVT API.
+Author-email: Marcel Claramunt <marcel@tribulnation.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/tribulnation/typed
+Project-URL: Documentation, https://tribulnation.com/typed/grvt
+Project-URL: Website, https://tribulnation.com/typed
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typed-core>=0.13
+Requires-Dist: lazy-loader
+Requires-Dist: eth-account>=0.13
+Requires-Dist: httpx>=0.26
+Requires-Dist: pydantic>=2.7
+Dynamic: license-file
+
+# Typed GRVT
+
+<p align="center">
+  <em>A fully typed, validated async client for the GRVT API.</em>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/typed-grvt/">
+    <img src="https://img.shields.io/pypi/v/typed-grvt.svg" alt="PyPI version">
+  </a>
+  <a href="https://pypi.org/project/typed-grvt/">
+    <img src="https://img.shields.io/pypi/pyversions/typed-grvt.svg" alt="Python versions">
+  </a>
+  <a href="https://tribulnation.com/typed/grvt">
+    <img src="https://img.shields.io/badge/docs-live-black" alt="Docs">
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/pypi/l/typed-grvt.svg" alt="License">
+  </a>
+</p>
+
+---
+
+- **Documentation**: [https://tribulnation.com/typed/grvt](https://tribulnation.com/typed/grvt)
+- **Source Code**: [https://github.com/tribulnation/typed/tree/main/packages/grvt](https://github.com/tribulnation/typed/tree/main/packages/grvt)
+
+---
+
+```python
+from typed_grvt import Grvt
+
+async with Grvt.new(public=True) as client:
+  ticker = await client.market.ticker('BTC_USDT_Perp')
+  print(ticker.get('mark_price'))
+```
+
+`Grvt.new()` connects to GRVT production. Pass `env='testnet'` (or `env='staging'`) to use a
+test deployment instead.
+
+## Why Typed GRVT?
+
+- **🎯 Precise Types**: Typed orders, fills, positions and market data across perpetuals, futures, options, spot swaps and stable perpetuals, not `dict`/`Any`.
+- **✅ Runtime Validation**: Every HTTP reply and WebSocket feed message is validated by default, with a per-call `validate` override.
+- **⚡ Async First**: Async HTTP and JSON-RPC over WebSocket, with a per-call `transport` choice and live streams, built for concurrent workflows.
+- **📚 Full Surface**: Market data, trading, account history, transfers, withdrawals, deposits, RFQs and vault summaries, with session login and EIP-712 signing handled for you.
+
+## Installation
+
+```bash
+pip install typed-grvt
+```
+
+## Surfaces
+
+| Attribute | What it covers | Credentials |
+| --- | --- | --- |
+| `client.market` | Instruments, currencies, tickers, order books, trades, candles, funding rates | none |
+| `client.market_streams` | Live tickers, order books, trades and candles | none |
+| `client.trading` | Orders, fills, positions, account summaries, transfers, withdrawals, leverage, RFQs, vault summaries, redemption queues and redemption cancels | API key (+ signer key for `create_order`, `bulk_orders`, `transfer`, `withdrawal` and `set_derisk_mm_ratio`) |
+| `client.trading_streams` | Your orders, fills, positions, transfers, deposits and withdrawals, live | API key |
+| `client.edge` | Deposit addresses, bridge withdrawal quotes and status, referrals, strategies | API key (none for `investment_strategies` and `rhino_chain_id`) |
+
+## How To
+
+- [Fetch Market Data](https://tribulnation.com/typed/grvt/how-to/fetch-market-data)
+- [Fetch Account Data](https://tribulnation.com/typed/grvt/how-to/fetch-account-data)
+- [Place & Manage Orders](https://tribulnation.com/typed/grvt/how-to/place-and-manage-orders)
+- [Paginate Through Results](https://tribulnation.com/typed/grvt/how-to/paginate-through-results)
+- [Listen To Live Streams](https://tribulnation.com/typed/grvt/how-to/listen-to-live-streams)
+- [Manage Transfers & Withdrawals](https://tribulnation.com/typed/grvt/how-to/manage-transfers-and-withdrawals)
+
+## Reference
+
+- [API Keys Setup](https://tribulnation.com/typed/grvt/api-keys)
+- [Async Usage](https://tribulnation.com/typed/grvt/reference/async-usage)
+- [Error Handling](https://tribulnation.com/typed/grvt/reference/error-handling)
+- [Environment Variables](https://tribulnation.com/typed/grvt/reference/env-vars)
+- [Timestamps](https://tribulnation.com/typed/grvt/reference/timestamps)
+
+## Design Philosophy
+
+Typed GRVT follows the principles outlined in [this blog post](https://tribulnation.com/blog/clients).
+
+*Details matter. Developer experience matters.*
+
+## License
+
+MIT — see [LICENSE](LICENSE).

typed_grvt-0.1.0/README.md

@@ -0,0 +1,88 @@
+# Typed GRVT
+
+<p align="center">
+  <em>A fully typed, validated async client for the GRVT API.</em>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/typed-grvt/">
+    <img src="https://img.shields.io/pypi/v/typed-grvt.svg" alt="PyPI version">
+  </a>
+  <a href="https://pypi.org/project/typed-grvt/">
+    <img src="https://img.shields.io/pypi/pyversions/typed-grvt.svg" alt="Python versions">
+  </a>
+  <a href="https://tribulnation.com/typed/grvt">
+    <img src="https://img.shields.io/badge/docs-live-black" alt="Docs">
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/pypi/l/typed-grvt.svg" alt="License">
+  </a>
+</p>
+
+---
+
+- **Documentation**: [https://tribulnation.com/typed/grvt](https://tribulnation.com/typed/grvt)
+- **Source Code**: [https://github.com/tribulnation/typed/tree/main/packages/grvt](https://github.com/tribulnation/typed/tree/main/packages/grvt)
+
+---
+
+```python
+from typed_grvt import Grvt
+
+async with Grvt.new(public=True) as client:
+  ticker = await client.market.ticker('BTC_USDT_Perp')
+  print(ticker.get('mark_price'))
+```
+
+`Grvt.new()` connects to GRVT production. Pass `env='testnet'` (or `env='staging'`) to use a
+test deployment instead.
+
+## Why Typed GRVT?
+
+- **🎯 Precise Types**: Typed orders, fills, positions and market data across perpetuals, futures, options, spot swaps and stable perpetuals, not `dict`/`Any`.
+- **✅ Runtime Validation**: Every HTTP reply and WebSocket feed message is validated by default, with a per-call `validate` override.
+- **⚡ Async First**: Async HTTP and JSON-RPC over WebSocket, with a per-call `transport` choice and live streams, built for concurrent workflows.
+- **📚 Full Surface**: Market data, trading, account history, transfers, withdrawals, deposits, RFQs and vault summaries, with session login and EIP-712 signing handled for you.
+
+## Installation
+
+```bash
+pip install typed-grvt
+```
+
+## Surfaces
+
+| Attribute | What it covers | Credentials |
+| --- | --- | --- |
+| `client.market` | Instruments, currencies, tickers, order books, trades, candles, funding rates | none |
+| `client.market_streams` | Live tickers, order books, trades and candles | none |
+| `client.trading` | Orders, fills, positions, account summaries, transfers, withdrawals, leverage, RFQs, vault summaries, redemption queues and redemption cancels | API key (+ signer key for `create_order`, `bulk_orders`, `transfer`, `withdrawal` and `set_derisk_mm_ratio`) |
+| `client.trading_streams` | Your orders, fills, positions, transfers, deposits and withdrawals, live | API key |
+| `client.edge` | Deposit addresses, bridge withdrawal quotes and status, referrals, strategies | API key (none for `investment_strategies` and `rhino_chain_id`) |
+
+## How To
+
+- [Fetch Market Data](https://tribulnation.com/typed/grvt/how-to/fetch-market-data)
+- [Fetch Account Data](https://tribulnation.com/typed/grvt/how-to/fetch-account-data)
+- [Place & Manage Orders](https://tribulnation.com/typed/grvt/how-to/place-and-manage-orders)
+- [Paginate Through Results](https://tribulnation.com/typed/grvt/how-to/paginate-through-results)
+- [Listen To Live Streams](https://tribulnation.com/typed/grvt/how-to/listen-to-live-streams)
+- [Manage Transfers & Withdrawals](https://tribulnation.com/typed/grvt/how-to/manage-transfers-and-withdrawals)
+
+## Reference
+
+- [API Keys Setup](https://tribulnation.com/typed/grvt/api-keys)
+- [Async Usage](https://tribulnation.com/typed/grvt/reference/async-usage)
+- [Error Handling](https://tribulnation.com/typed/grvt/reference/error-handling)
+- [Environment Variables](https://tribulnation.com/typed/grvt/reference/env-vars)
+- [Timestamps](https://tribulnation.com/typed/grvt/reference/timestamps)
+
+## Design Philosophy
+
+Typed GRVT follows the principles outlined in [this blog post](https://tribulnation.com/blog/clients).
+
+*Details matter. Developer experience matters.*
+
+## License
+
+MIT — see [LICENSE](LICENSE).

typed_grvt-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "typed-grvt"
+version = "0.1.0"
+authors = [
+  {name="Marcel Claramunt", email="marcel@tribulnation.com"}
+]
+description = "A fully typed, validated async client for the GRVT API."
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Typing :: Typed",
+]
+dependencies = [
+  "typed-core>=0.13", "lazy-loader", "eth-account>=0.13", "httpx>=0.26", "pydantic>=2.7",
+]
+requires-python = ">=3.10"
+readme = {file="README.md", content-type="text/markdown"}
+
+[tool.setuptools.package-data]
+"typed_grvt" = ["py.typed", "*.pyi", "**/*.pyi"]
+
+[project.urls]
+Repository = "https://github.com/tribulnation/typed"
+Documentation = "https://tribulnation.com/typed/grvt"
+Website = "https://tribulnation.com/typed"

typed_grvt-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

typed_grvt-0.1.0/src/typed_grvt/__init__.py

@@ -0,0 +1,15 @@
+"""A fully typed, validated async client for the GRVT API.
+
+Examples:
+  ```python
+  from typed_grvt import Grvt
+
+  async with Grvt.new(public=True) as client:
+    instrument = await client.market.instrument('BTC_USDT_Perp')
+    print(instrument['tick_size'])
+  ```
+"""
+
+import lazy_loader as lazy
+
+__getattr__, __dir__, __all__ = lazy.attach_stub(__name__, __file__)

typed_grvt-0.1.0/src/typed_grvt/__init__.pyi

@@ -0,0 +1,23 @@
+from .core import (
+  ApiError,
+  AuthError,
+  BadRequest,
+  Error,
+  LogicError,
+  NetworkError,
+  RateLimited,
+  ValidationError,
+)
+from .main import Grvt
+
+__all__ = [
+  'Grvt',
+  'Error',
+  'NetworkError',
+  'ValidationError',
+  'ApiError',
+  'BadRequest',
+  'AuthError',
+  'RateLimited',
+  'LogicError',
+]

typed_grvt-0.1.0/src/typed_grvt/core/__init__.py

@@ -0,0 +1,5 @@
+"""GRVT client core: transports, session authentication, EIP-712 signing and error mapping."""
+
+import lazy_loader as lazy
+
+__getattr__, __dir__, __all__ = lazy.attach_stub(__name__, __file__)

typed_grvt-0.1.0/src/typed_grvt/core/__init__.pyi

@@ -0,0 +1,73 @@
+from .auth import Credentials, Session, SessionState, resolve_credentials
+from .base import ClientBase
+from .endpoint.edge import EdgeClient, EdgeEndpoint, EdgeMeta
+from .endpoint.gateway import (
+  GatewayClient,
+  GatewayEndpoint,
+  Meta,
+  Sign,
+  SubAccount,
+  Transport,
+)
+from .env import Environment, Hosts
+from .envelope import Unwrap
+from .exc import (
+  ApiError,
+  AuthError,
+  BadRequest,
+  Error,
+  LogicError,
+  NetworkError,
+  RateLimited,
+  ValidationError,
+)
+from .signing import Signer
+from .transport.edge import EdgeTransport
+from .transport.gateway import GatewayTransport
+from .transport.ws import GatewaySocket
+from .types import (
+  TimestampIso,
+  TimestampMillis,
+  TimestampNanos,
+  timestamp_iso,
+  timestamp_millis,
+  timestamp_nanos,
+)
+
+__all__ = [
+  'Credentials',
+  'Session',
+  'SessionState',
+  'resolve_credentials',
+  'ClientBase',
+  'EdgeClient',
+  'EdgeEndpoint',
+  'EdgeMeta',
+  'GatewayClient',
+  'GatewayEndpoint',
+  'Meta',
+  'Sign',
+  'SubAccount',
+  'Transport',
+  'Environment',
+  'Hosts',
+  'Unwrap',
+  'Error',
+  'NetworkError',
+  'ValidationError',
+  'ApiError',
+  'BadRequest',
+  'AuthError',
+  'RateLimited',
+  'LogicError',
+  'Signer',
+  'EdgeTransport',
+  'GatewayTransport',
+  'GatewaySocket',
+  'TimestampNanos',
+  'timestamp_nanos',
+  'TimestampMillis',
+  'timestamp_millis',
+  'TimestampIso',
+  'timestamp_iso',
+]

typed_grvt-0.1.0/src/typed_grvt/core/auth.py

@@ -0,0 +1,283 @@
+"""Credential resolution and the GRVT session: cookie login, shared by every authenticated transport.
+
+GRVT authenticates calls with a session, not per-request signatures:
+
+1. `POST {edge}/auth/api_key/login` with `{"api_key"}` (or `POST {edge}/auth/wallet/login`
+   with an EIP-712 `WalletLogin` signature, for a funding wallet without an API key).
+2. The reply sets a `gravity` cookie (24 h `Max-Age` on testnet) and an `X-Grvt-Account-Id`
+   header; the body names the funding account and, for a trading-account key, its
+   sub-account.
+3. Every authenticated call sends `Cookie: gravity=...` and `X-Grvt-Account-Id: ...`.
+
+Payload signatures (orders, transfers, withdrawals) are separate: see `signing.py`.
+"""
+
+from dataclasses import dataclass, field
+from datetime import timedelta
+from http.cookies import CookieError, SimpleCookie
+from email.utils import parsedate_to_datetime
+import os
+import re
+import time
+
+import httpx
+from typing_extensions import Any, Literal
+
+from typed_core.exceptions import AuthError, ValidationError
+from typed_core.http import HttpClient
+
+from .env import Environment
+from .envelope import check_edge
+from .locks import LoopLock
+from .owners import Connection, Owned
+from .signing import Signer
+
+ENV_PREFIXES: dict[Environment, str] = {
+  'prod': 'GRVT_',
+  'testnet': 'GRVT_TESTNET_',
+  'staging': 'GRVT_STAGING_',
+}
+"""Environment-variable prefix per environment, so a testnet credential can never be read
+for production: `GRVT_TESTNET_API_KEY`, `GRVT_TESTNET_PRIVATE_KEY`,
+`GRVT_TESTNET_TRADING_ACCOUNT_ID` (and `GRVT_API_KEY`, ... for `prod`, the default). The
+last is the default trading sub-account: see `GatewayTransport.sub_account_id()`."""
+
+REFRESH_BEFORE = timedelta(minutes=1)
+"""Log in again this long before the session cookie expires."""
+
+SESSION_COOKIE = 'gravity'
+ACCOUNT_HEADER = 'X-Grvt-Account-Id'
+
+
+@dataclass(frozen=True, kw_only=True)
+class Credentials:
+  """GRVT credentials. Either secret alone can open a session; the private key also signs."""
+
+  api_key: str | None = field(default=None, repr=False)
+  """API key, exchanged for a session cookie at login."""
+  private_key: str | None = field(default=None, repr=False)
+  """EIP-712 signer key: the API key's signer, or the funding wallet itself."""
+  trading_account_id: str | None = None
+  """Default trading sub-account id, filled into a trading call that leaves its
+  `sub_account_id` out (see `GatewayTransport.sub_account_id()`)."""
+  source: Literal['arguments', 'environment'] = 'arguments'
+  """Where the secrets came from: `new()`'s arguments, or the environment variables."""
+
+
+def resolve_credentials(
+  env: Environment,
+  *,
+  api_key: str | None = None,
+  private_key: str | None = None,
+  trading_account_id: str | None = None,
+  public: bool = False,
+) -> Credentials | None:
+  """Resolve the one `Credentials` every authenticated transport of a client shares.
+
+  Called once, from the root's `.new()`. The secrets come from one source only, so an
+  explicit key is never paired with another account's key from the environment:
+
+  - If `api_key` or `private_key` is passed, the arguments are the whole credential set and
+    nothing is read from the environment (`trading_account_id` then defaults to the
+    sub-account the API key is scoped to, when not passed).
+  - Otherwise all three are read from the environment, under the environment-specific
+    prefix (`ENV_PREFIXES`), and an explicit `trading_account_id` overrides
+    `{prefix}TRADING_ACCOUNT_ID`.
+
+  Args:
+    env: Target environment, which picks the variable prefix.
+    api_key: API key; read from `{prefix}API_KEY` when neither secret is passed.
+    private_key: Signer private key; read from `{prefix}PRIVATE_KEY` when neither secret is
+      passed.
+    trading_account_id: Default trading sub-account id; read from
+      `{prefix}TRADING_ACCOUNT_ID` when not passed and neither secret is passed.
+    public: Skip resolution and return `None`, for a market-data-only client.
+
+  Raises:
+    AuthError: `public` is false and neither an API key nor a private key was found.
+  """
+  if public:
+    return None
+  prefix = ENV_PREFIXES[env]
+  source: Literal['arguments', 'environment'] = 'arguments'
+  if not api_key and not private_key:
+    source = 'environment'
+    api_key = os.environ.get(f'{prefix}API_KEY')
+    private_key = os.environ.get(f'{prefix}PRIVATE_KEY')
+    trading_account_id = trading_account_id or os.environ.get(
+      f'{prefix}TRADING_ACCOUNT_ID'
+    )
+  if not api_key and not private_key:
+    raise AuthError(
+      f'No GRVT credentials: set {prefix}API_KEY (and {prefix}PRIVATE_KEY to sign orders, '
+      'transfers and withdrawals), pass api_key/private_key, or build with `public=True` '
+      'for market data only.'
+    )
+  return Credentials(
+    api_key=api_key,
+    private_key=private_key,
+    trading_account_id=trading_account_id,
+    source=source,
+  )
+
+
+@dataclass(frozen=True, kw_only=True)
+class SessionState:
+  """One logged-in session."""
+
+  token: str = field(repr=False)
+  """`gravity` cookie value."""
+  account_id: str | None = field(repr=False)
+  """`X-Grvt-Account-Id` header value (an off-chain `ACC:...` id)."""
+  expires_at: float
+  """Unix seconds at which the cookie expires."""
+  funding_account_address: str | None
+  """Funding (main) account address the session belongs to."""
+  sub_account_id: str | None
+  """Trading sub-account id, for a trading-account-level API key."""
+
+  @property
+  def headers(self) -> dict[str, str]:
+    """Headers authenticating one call with this session."""
+    headers = {'Cookie': f'{SESSION_COOKIE}={self.token}'}
+    if self.account_id:
+      headers[ACCOUNT_HEADER] = self.account_id
+    return headers
+
+  def fresh(self) -> bool:
+    """Whether the cookie is valid for at least `REFRESH_BEFORE` more."""
+    return time.time() < self.expires_at - REFRESH_BEFORE.total_seconds()
+
+
+MAX_AGE = re.compile(r'-?[0-9]+')
+"""A valid cookie `Max-Age`: an integer number of seconds (RFC 6265 §5.2.2)."""
+
+
+def cookie_expiry(response: httpx.Response) -> float:
+  """Unix seconds at which the response's `gravity` cookie expires.
+
+  Reads `Max-Age` first, then `Expires`. An attribute that does not parse is ignored, as
+  RFC 6265 has a browser do: a malformed `Max-Age` falls back to `Expires`.
+
+  Raises:
+    ValidationError: The response set no `gravity` cookie, or one with no valid lifetime.
+  """
+  for header in response.headers.get_list('set-cookie'):
+    cookie = SimpleCookie()
+    try:
+      cookie.load(header)
+    except CookieError:
+      continue
+    if (morsel := cookie.get(SESSION_COOKIE)) is None:
+      continue
+    max_age = morsel['max-age'].strip()
+    if MAX_AGE.fullmatch(max_age):
+      return time.time() + int(max_age)
+    if morsel['expires']:
+      try:
+        return parsedate_to_datetime(morsel['expires']).timestamp()
+      except (TypeError, ValueError, OverflowError):
+        pass
+  raise ValidationError('Login response set no gravity cookie with a valid lifetime')
+
+
+def login_failure(payload: Any) -> AuthError:
+  """The error for a login the edge host answered without success (an HTTP `200` whose body
+  says `"status": "failure"`, or one that is not an object).
+
+  Carries `(code, message, body)` when the body names a venue code, else one message.
+
+  Args:
+    payload: The decoded login reply.
+  """
+  if not isinstance(payload, dict):
+    return AuthError(f'Login failed: unexpected reply {payload!r:.500}')
+  message = str(
+    payload.get('message') or payload.get('error') or payload.get('status') or ''
+  )
+  if (code := payload.get('code')) is not None:
+    return AuthError(code, message, payload)
+  return AuthError(f'Login failed: {message or "no reason given"}')
+
+
+@dataclass(kw_only=True)
+class Session(Owned):
+  """Lazily logs in, caches the session and refreshes it ahead of expiry.
+
+  Shared by every authenticated transport of one client (trading HTTP, trading WebSocket,
+  edge), so a single login serves all of them. Concurrent callers wait on one login; the
+  lock is per event loop (`LoopLock`), so a client survives being reused across two
+  `asyncio.run` calls, provided each one enters it with `async with client`: leaving it
+  closes the HTTP clients and sockets, whose pooled connections otherwise stay bound to the
+  first loop and fail in the next one with a raw `RuntimeError`.
+
+  Each transport sharing the session takes one ownership of it while it is owned itself
+  (`Owned.shared`), and the login connection closes when the last owner leaves: `async with
+  client.trading` alone closes it on exit, while an edge block still open keeps it.
+  """
+
+  edge_url: str
+  """Edge host base URL, where the login endpoints live."""
+  api_key: str | None = field(default=None, repr=False)
+  """API key to log in with; preferred over `signer`."""
+  signer: Signer | None = None
+  """Funding-wallet signer to log in with when there is no API key."""
+  http: HttpClient = field(default_factory=HttpClient)
+  """Dedicated client, so the login's `Set-Cookie` never lands in a shared cookie jar."""
+  current: SessionState | None = field(default=None, init=False, repr=False)
+  lock: LoopLock = field(default_factory=LoopLock, init=False, repr=False)
+
+  def connections(self) -> list[Connection]:
+    """The login connection, closed when the last owner leaves."""
+    return [self.http]
+
+  async def state(self) -> SessionState:
+    """The live session, logging in first when there is none or it is about to expire."""
+    async with self.lock:
+      if self.current is None or not self.current.fresh():
+        self.current = await self.login()
+      return self.current
+
+  async def headers(self) -> dict[str, str]:
+    """Headers authenticating one call."""
+    return (await self.state()).headers
+
+  def invalidate(self, state: SessionState):
+    """Forget `state` after the venue rejected it, unless a newer session already replaced it.
+
+    Args:
+      state: The session the rejected call was sent with.
+    """
+    if self.current is state:
+      self.current = None
+
+  async def login(self) -> SessionState:
+    """Log in with the API key, or with a wallet signature when there is no API key.
+
+    Raises:
+      AuthError: The venue rejected the credentials, or there are none to log in with.
+    """
+    if self.api_key:
+      path, body = '/auth/api_key/login', {'api_key': self.api_key}
+    elif self.signer is not None:
+      signature = self.signer.wallet_login()
+      path, body = (
+        '/auth/wallet/login',
+        {'address': self.signer.address, 'signature': signature},
+      )
+    else:
+      raise AuthError('No API key or wallet key to log in with')
+    response = await self.http.request('POST', self.edge_url + path, json=body)
+    payload = check_edge(response)
+    if not isinstance(payload, dict) or payload.get('status', 'success') != 'success':
+      raise login_failure(payload)
+    token = response.cookies.get(SESSION_COOKIE)
+    if not token:
+      raise ValidationError('Login response set no gravity cookie')
+    return SessionState(
+      token=token,
+      account_id=response.headers.get(ACCOUNT_HEADER),
+      expires_at=cookie_expiry(response),
+      funding_account_address=payload.get('funding_account_address'),
+      sub_account_id=payload.get('sub_account_id'),
+    )