Metadata-Version: 2.4
Name: typed-hyperliquid
Version: 1.0.2
Summary: A fully typed, validated async client for the Hyperliquid API.
Author-email: Marcel Claramunt <marcel@tribulnation.com>
License-Expression: GPL-3.0-only
Project-URL: Repository, https://github.com/tribulnation/hyperliquid.git
Project-URL: Documentation, https://hyperliquid.tribulnation.com
Project-URL: Website, https://tribulnation.com
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
Requires-Dist: eth-account
Requires-Dist: msgpack
Dynamic: license-file

# Typed Hyperliquid

[![Hyperliquid](https://app.hyperliquid.xyz/images/logo-privy.svg)](https://app.hyperliquid.xyz/trade)

> A fully typed, validated async client for the Hyperliquid API.

**Use autocomplete instead of documentation.**

```python
from hyperliquid import Info

async with Info.http() as info:
  mids = await info.all_mids()
  print(mids['BTC'])
```

## Why Typed Hyperliquid?

- **🎯 Precise Types**: Strong typing throughout, so your editor can help before runtime does.
- **✅ Automatic Validation**: Catch upstream API changes earlier, where they are easier to debug.
- **⚡ Async First**: Built for concurrent, network-heavy workflows.
- **🔒 Safer Usage**: Typed inputs and explicit errors reduce avoidable mistakes.
- **🎨 Better DX**: Clear routing, sensible defaults, and minimal ceremony.
- **📦 Practical Extras**: HTTP, request-response WS, streams, and exchange actions under one package.

## Package Shape

This package exposes four public entry points:

- `Info` for read-only request-response access to the info endpoint
- `Exchange` for signed exchange actions
- `Streams` for WebSocket subscriptions
- `Hyperliquid` as a convenience bundle of all three

## Installation

```bash
pip install typed-hyperliquid
```

## Quick Start

### Public reads

Use `Info` for request-response reads over HTTP:

```python
from hyperliquid import Info

async with Info.http() as info:
  mids = await info.all_mids()
  book = await info.l2_book('BTC')
  print(mids['BTC'], book['levels'][0][0]['px'])
```

### Public streams

Use `Streams` for subscription workflows:

```python
from hyperliquid import Streams

async with Streams.new() as streams:
  trades = await streams.trades('BTC')
  async for batch in trades:
    print(batch[0]['px'])
    break
```

### Authenticated actions

Hyperliquid auth is wallet-based, not API-key based:

```bash
export HYPERLIQUID_PRIVATE_KEY="your_private_key"
```

```python
from hyperliquid import Hyperliquid

async with Hyperliquid.http() as client:
  result = await client.exchange.noop()
  print(result['status'])
```

## Transport Model

This package intentionally separates Hyperliquid's three usage modes:

- `Info.http()` and `Info.ws()` for read-only request-response calls
- `Exchange.http(wallet)` and `Exchange.ws(wallet)` for signed exchange actions
- `Streams.new()` for subscriptions
- `Hyperliquid.http()` and `Hyperliquid.ws()` as convenience bundles

`Exchange.http()` and `Exchange.ws()` accept either a wallet object or a raw private key. `Hyperliquid.http()` and `Hyperliquid.ws()` also accept those forms, and can additionally read `HYPERLIQUID_PRIVATE_KEY` when no wallet is passed.

## Documentation

> [**Read the docs**](https://hyperliquid.tribulnation.com)
