orcalayer

Official Python client for the OrcaLayer API — Polymarket whale and market analytics: wallet P&L, open positions, smart-whale leaderboard, market search and real-time whale alerts.

Install

pip install orcalayer

Requires Python 3.10+. Single dependency: httpx.

Quickstart

Three lines to a first result — no API key needed for public endpoints:

from orcalayer import OrcaLayer

ol = OrcaLayer()
print(ol.leaderboard(limit=5))

Anonymous access is limited to 200 requests/min per IP, and wallet endpoints (wallet_overview, wallet_positions) additionally to 300 requests/day per IP. With a Premium API key (get one here) you get 600 req/min, no daily cap, and access to Premium endpoints such as whale alerts:

ol = OrcaLayer(api_key="sk_orca_...")
alerts = ol.whale_alerts(minutes=30, min_usd=1000)

Methods

All methods return the JSON response as a plain dict, exactly as the API sends it. Full field reference: orcalayer.com/docs.

Examples

Runnable scripts in examples/ — each is self-contained and runs against the live API:

Behavior notes

• Rate limits: on HTTP 429 the client reads Retry-After and retries with exponential backoff (default 3 attempts). Disable with OrcaLayer(retry_on_rate_limit=False). A Retry-After beyond 5 minutes signals the anonymous daily cap rather than a burst — the client then raises RateLimitError immediately instead of retrying.
• Transient 502 responses are retried once automatically.
• Premium endpoints without a key raise PremiumRequiredError with a link to pricing — no network call is made.
• A rejected key on a public endpoint (HTTP 401/403) does not fail the call: the client retries once anonymously against the public surface (lower rate limits) and logs a one-time warning. Premium-only endpoints (whale_alerts) still raise AuthenticationError. So a bad, expired or non-Premium key never breaks a call that works without one.
• Overall retry budget: OrcaLayer(max_total_seconds=N) caps the total time spent sleeping across a single call's retries — a back-off that would exceed the budget raises the pending typed error instead of blocking. Unset (the default) means no cap, so a worst-case 202 + 429 + 502 chain can sleep for minutes; set it when you need a bounded call.
• Wallet overview freshness: responses include as_of (data timestamp) and degraded (heavy side-stats timed out, core stats still present).
• Cold heavy wallets answer HTTP 202 while their stats are computed server-side. The client retries once automatically after the server's Retry-After interval; if the wallet is still not ready it raises WalletComputingError (carrying retry_after) so a 202 body is never mistaken for wallet data.

Errors

All exceptions inherit from orcalayer.OrcaLayerError, so one except catches everything:

from orcalayer import OrcaLayer, OrcaLayerError, RateLimitError

ol = OrcaLayer()
try:
    data = ol.wallet_overview("0x...")
except RateLimitError as e:
    print(f"rate limited, retry in {e.retry_after:.0f}s")
except OrcaLayerError as e:
    print(f"request failed: {e}")

The package ships type hints (py.typed).

License

MIT. See LICENSE.

Data is provided for informational purposes only and is not financial advice.