grvt.session

Documentation for eth_defi.grvt.session Python module.

HTTP session management for GRVT API.

This module provides session creation with:

  • Browser-like User-Agent header to bypass Cloudflare protection on GRVT endpoints (both edge.grvt.io and market-data.grvt.io return 403 Forbidden when the default python-requests User-Agent is used)

  • Rate limiting that is thread-safe using SQLite backend

  • Retry logic for handling transient errors using exponential backoff

  • Optional API key authentication for private endpoints

Most GRVT vault data is available from public endpoints (market-data.grvt.io) and does not require authentication. Use create_grvt_session() for public access, or pass credentials for authenticated access to private endpoints.

Environment variables (optional, for authenticated endpoints):

  • GRVT_API_KEY: API key provisioned via the GRVT UI

  • GRVT_PRIVATE_KEY: Private key for the Ethereum address linked to the API key

  • GRVT_TRADING_ACCOUNT_ID: Trading account ID

Rate limiting is thread-safe using SQLite backend, so the session can be shared across multiple threads when using joblib.Parallel or similar.

Functions

create_grvt_session([api_url, api_key, ...])

Create a requests Session configured for the GRVT API.
create_grvt_session(api_url=None, api_key=None, private_key=None, trading_account_id=None, retries=5, backoff_factor=0.5, requests_per_second=None, pool_maxsize=32, rate_limit_db_path=PosixPath('/home/runner/.tradingstrategy/grvt/rate-limit.sqlite'), timeout=30.0, authenticate=False)

Create a requests Session configured for the GRVT API.

By default, creates an unauthenticated session suitable for public endpoints (market-data.grvt.io). Set authenticate=True and provide credentials for private endpoints (edge.grvt.io).

The session is configured with:

  • Rate limiting to respect GRVT API throttling (thread-safe via SQLite)

  • Retry logic for handling transient errors using exponential backoff

  • Optional cookie-based authentication via /auth/api_key/login

Example:

from eth_defi.grvt.session import create_grvt_session

# Public session (no auth needed)
session = create_grvt_session()

# Authenticated session
session = create_grvt_session(authenticate=True)
Parameters

  • api_url (Optional[str]) – GRVT API base URL. Falls back to GRVT_API_URL.

  • api_key (Optional[str]) – GRVT API key. Falls back to GRVT_API_KEY env var.

  • private_key (Optional[str]) – GRVT private key. Falls back to GRVT_PRIVATE_KEY env var.

  • trading_account_id (Optional[str]) – GRVT trading account ID. Falls back to GRVT_TRADING_ACCOUNT_ID env var.

  • retries (int) – Maximum number of retry attempts for failed requests.

  • backoff_factor (float) – Backoff factor for exponential retry delays.

  • requests_per_second (Optional[float]) – Maximum requests per second to avoid rate limiting. Falls back to GRVT_DEFAULT_REQUESTS_PER_SECOND.

  • pool_maxsize (int) – Maximum number of connections to keep in the connection pool. Should be at least as large as max_workers when using parallel requests.

  • rate_limit_db_path (pathlib.Path) – Path to SQLite database for storing rate limit state. Using SQLite ensures thread-safe rate limiting across multiple threads.

  • timeout (float) – HTTP request timeout in seconds.

  • authenticate (bool) – If True, authenticate with the GRVT API using credentials. Required for private endpoints like vault_investor_summary.

Returns

Configured requests Session.

Raises

AssertionError – If authenticate=True and required credentials are not provided.

Return type

requests.sessions.Session