| Name | hl-web3 JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Web3 client for Hyperliquid |
| upload_time | 2025-08-07 09:46:40 |
| maintainer | None |
| docs_url | None |
| author | Yuki |
| requires_python | >=3.10 |
| license | MIT License Copyright (c) 2024 hl-web3-py 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. |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# hl-web3-py
A Python Web3 client library for interacting with the Hyperliquid DEX on both mainnet and testnet.
## Features
- **Trading Operations**: Place and cancel orders on Hyperliquid perpetual markets
- **Account Management**: Query positions, balances, and account information
- **Vault Operations**: Deposit and withdraw from HLP vaults
- **Staking & Delegation**: Stake HYPE tokens and delegate to validators
- **Spot Trading**: Transfer spot tokens and manage spot balances
- **Market Data**: Access real-time pricing, order book, and market information
- **Multi-Network Support**: Works with both Hyperliquid mainnet and testnet
## Installation
```bash
pip install hl-web3
```
For development:
```bash
git clone https://github.com/oneforalone/hl-web3-py
cd hl-web3-py
uv sync
```
## Quick Start
### Environment Setup
Create a `.env` file with your private key:
```bash
PRIVATE_KEY=your_private_key_here
```
### Basic Usage
```python
import asyncio
from hl_web3.info import Info
from hl_web3.exchange import Exchange
from hl_web3.utils.constants import HL_TESTNET_RPC_URL, SCALE_FACTOR
from hl_web3.utils.types import Tif
async def main():
# Initialize info client (read-only)
info = Info(HL_TESTNET_RPC_URL)
# Initialize exchange client (requires private key)
exchange = Exchange(HL_TESTNET_RPC_URL, "your_private_key")
# Get market data
btc_price = await info.get_mark_px(3) # BTC perp asset ID
print(f"BTC Mark Price: ${btc_price / SCALE_FACTOR}")
# Place a limit order
asset = 3 # BTC perp
is_buy = True
price = int(50000 * SCALE_FACTOR) # $50,000
size = int(0.001 * SCALE_FACTOR) # 0.001 BTC
reduce_only = False
time_in_force = Tif.Gtc
client_order_id = 12345
tx = await exchange.place_order(
asset, is_buy, price, size, reduce_only, time_in_force, client_order_id
)
print(f"Order placed: {tx}")
if __name__ == "__main__":
asyncio.run(main())
```
## Core Components
### Info Client
The `Info` class provides read-only access to market data and account information:
```python
from hl_web3.info import Info
info = Info("https://rpc.hyperliquid-testnet.xyz/evm")
# Market data
mark_price = await info.get_mark_px(asset_id)
oracle_price = await info.get_oracle_px(asset_id)
spot_price = await info.get_spot_px(spot_id)
best_bid_offer = await info.get_bbo(asset_id)
# Account information
position = await info.get_user_position(user_address, asset_id)
spot_balance = await info.get_user_spot_balance(user_address, spot_id)
vault_equity = await info.get_user_vault_equity(user_address, vault_address)
withdrawable = await info.get_user_withdrawable(user_address)
# Asset information
perp_info = await info.get_perp_asset_info(asset_id)
spot_info = await info.get_spot_info(spot_id)
token_info = await info.get_token_info(token_id)
```
### Exchange Client
The `Exchange` class enables trading and account management operations:
```python
from hl_web3.exchange import Exchange
exchange = Exchange("https://rpc.hyperliquid-testnet.xyz/evm", private_key)
# Trading
tx = await exchange.place_order(asset, is_buy, price, size, reduce_only, tif, cloid)
tx = await exchange.cancel_order_by_oid(asset, order_id)
tx = await exchange.cancel_order_by_cloid(asset, client_order_id)
# Vault operations
tx = await exchange.vault_transfer(vault_address, is_deposit, usd_amount)
# Staking
tx = await exchange.staking_deposit(hype_amount)
tx = await exchange.staking_withdraw(hype_amount)
tx = await exchange.token_delegate(validator_address, hype_amount, is_undelegate)
# Spot transfers
tx = await exchange.spot_send(destination_address, token_id, amount)
tx = await exchange.send_usd_class_transfer(amount, to_perp)
# API wallet management
tx = await exchange.add_api_wallet(api_address, name)
```
## Supported Networks
### Mainnet
- RPC URL: `https://rpc.hyperliquid.xyz/evm`
- Use `HL_RPC_URL` constant
### Testnet
- RPC URL: `https://rpc.hyperliquid-testnet.xyz/evm`
- Use `HL_TESTNET_RPC_URL` constant
### Connection Types
- HTTPS (recommended)
- WebSocket
- IPC (limited support)
## Data Types
The library includes comprehensive type definitions for all Hyperliquid data structures:
### Trading Types
- `ActionType`: Enum for different action types (LimitOrder, VaultTransfer, etc.)
- `Tif`: Time in Force options (Alo, Gtc, Ioc)
- `AssetType`: Perp or Spot assets
### Account Data
- `Position`: Perpetual position information
- `SpotBalance`: Spot token balances
- `UserVaultEquity`: Vault equity and lock information
- `Delegation`: Staking delegation details
### Market Data
- `PerpAssetInfo`: Perpetual asset metadata
- `SpotInfo`: Spot market information
- `TokenInfo`: Token contract details
- `Bbo`: Best bid/offer prices
## Constants and Scaling
### Price and Size Scaling
- `SCALE_FACTOR = 10**8`: Used for perpetual prices and sizes
- `USD_SCALE_FACTOR = 10**6`: Used for USD amounts
### Example Asset IDs (Testnet)
- BTC Perp: `3`
- BTC Spot: `50`
- BTC Token: `69`
## Testing
The library includes comprehensive tests covering all functionality:
```bash
# Run all tests
pytest
# Run specific test categories
pytest tests/test_info.py # Market data tests
pytest tests/test_exchange.py # Trading tests
pytest tests/test_endpoint.py # Connection tests
pytest tests/test_utils.py # Utility tests
```
### Test Environment
Tests require a `.env` file with:
```bash
PRIVATE_KEY=your_testnet_private_key
```
Some tests are skipped by default due to balance requirements:
- Token delegation tests (require HYPE tokens)
- Staking tests (require HYPE tokens)
## Error Handling
The library provides proper error handling for common scenarios:
- Invalid asset IDs
- Insufficient balances
- Network connectivity issues
- Invalid action types
## Development
### Requirements
- Python 3.10+
- uv (for dependency management)
- web3.py 7.13.0+
- eth-abi 5.2.0+
### Setup
```bash
git clone https://github.com/oneforalone/hl-web3-py
cd hl-web3-py
uv sync
```
### Code Quality
The project uses:
- pre-commit hooks
- pytest for testing
- ruff for linting
- pytest-cov for coverage
## License
MIT License
## Support
For issues and questions:
- GitHub Issues: https://github.com/oneforalone/hl-web3-py/issues
Raw data
{
"_id": null,
"home_page": null,
"name": "hl-web3",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Yuki",
"author_email": "Yuki <oneforalone@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/cf/fd/c626027a836a780bce24f0a538143737284a77fea8c7b1faec3b0836bcd6/hl_web3-0.1.0.tar.gz",
"platform": null,
"description": "# hl-web3-py\n\nA Python Web3 client library for interacting with the Hyperliquid DEX on both mainnet and testnet.\n\n## Features\n\n- **Trading Operations**: Place and cancel orders on Hyperliquid perpetual markets\n- **Account Management**: Query positions, balances, and account information\n- **Vault Operations**: Deposit and withdraw from HLP vaults\n- **Staking & Delegation**: Stake HYPE tokens and delegate to validators\n- **Spot Trading**: Transfer spot tokens and manage spot balances\n- **Market Data**: Access real-time pricing, order book, and market information\n- **Multi-Network Support**: Works with both Hyperliquid mainnet and testnet\n\n## Installation\n\n```bash\npip install hl-web3\n```\n\nFor development:\n\n```bash\ngit clone https://github.com/oneforalone/hl-web3-py\ncd hl-web3-py\nuv sync\n```\n\n## Quick Start\n\n### Environment Setup\n\nCreate a `.env` file with your private key:\n\n```bash\nPRIVATE_KEY=your_private_key_here\n```\n\n### Basic Usage\n\n```python\nimport asyncio\nfrom hl_web3.info import Info\nfrom hl_web3.exchange import Exchange\nfrom hl_web3.utils.constants import HL_TESTNET_RPC_URL, SCALE_FACTOR\nfrom hl_web3.utils.types import Tif\n\nasync def main():\n # Initialize info client (read-only)\n info = Info(HL_TESTNET_RPC_URL)\n\n # Initialize exchange client (requires private key)\n exchange = Exchange(HL_TESTNET_RPC_URL, \"your_private_key\")\n\n # Get market data\n btc_price = await info.get_mark_px(3) # BTC perp asset ID\n print(f\"BTC Mark Price: ${btc_price / SCALE_FACTOR}\")\n\n # Place a limit order\n asset = 3 # BTC perp\n is_buy = True\n price = int(50000 * SCALE_FACTOR) # $50,000\n size = int(0.001 * SCALE_FACTOR) # 0.001 BTC\n reduce_only = False\n time_in_force = Tif.Gtc\n client_order_id = 12345\n\n tx = await exchange.place_order(\n asset, is_buy, price, size, reduce_only, time_in_force, client_order_id\n )\n print(f\"Order placed: {tx}\")\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n## Core Components\n\n### Info Client\n\nThe `Info` class provides read-only access to market data and account information:\n\n```python\nfrom hl_web3.info import Info\n\ninfo = Info(\"https://rpc.hyperliquid-testnet.xyz/evm\")\n\n# Market data\nmark_price = await info.get_mark_px(asset_id)\noracle_price = await info.get_oracle_px(asset_id)\nspot_price = await info.get_spot_px(spot_id)\nbest_bid_offer = await info.get_bbo(asset_id)\n\n# Account information\nposition = await info.get_user_position(user_address, asset_id)\nspot_balance = await info.get_user_spot_balance(user_address, spot_id)\nvault_equity = await info.get_user_vault_equity(user_address, vault_address)\nwithdrawable = await info.get_user_withdrawable(user_address)\n\n# Asset information\nperp_info = await info.get_perp_asset_info(asset_id)\nspot_info = await info.get_spot_info(spot_id)\ntoken_info = await info.get_token_info(token_id)\n```\n\n### Exchange Client\n\nThe `Exchange` class enables trading and account management operations:\n\n```python\nfrom hl_web3.exchange import Exchange\n\nexchange = Exchange(\"https://rpc.hyperliquid-testnet.xyz/evm\", private_key)\n\n# Trading\ntx = await exchange.place_order(asset, is_buy, price, size, reduce_only, tif, cloid)\ntx = await exchange.cancel_order_by_oid(asset, order_id)\ntx = await exchange.cancel_order_by_cloid(asset, client_order_id)\n\n# Vault operations\ntx = await exchange.vault_transfer(vault_address, is_deposit, usd_amount)\n\n# Staking\ntx = await exchange.staking_deposit(hype_amount)\ntx = await exchange.staking_withdraw(hype_amount)\ntx = await exchange.token_delegate(validator_address, hype_amount, is_undelegate)\n\n# Spot transfers\ntx = await exchange.spot_send(destination_address, token_id, amount)\ntx = await exchange.send_usd_class_transfer(amount, to_perp)\n\n# API wallet management\ntx = await exchange.add_api_wallet(api_address, name)\n```\n\n## Supported Networks\n\n### Mainnet\n- RPC URL: `https://rpc.hyperliquid.xyz/evm`\n- Use `HL_RPC_URL` constant\n\n### Testnet\n- RPC URL: `https://rpc.hyperliquid-testnet.xyz/evm`\n- Use `HL_TESTNET_RPC_URL` constant\n\n### Connection Types\n- HTTPS (recommended)\n- WebSocket\n- IPC (limited support)\n\n## Data Types\n\nThe library includes comprehensive type definitions for all Hyperliquid data structures:\n\n### Trading Types\n- `ActionType`: Enum for different action types (LimitOrder, VaultTransfer, etc.)\n- `Tif`: Time in Force options (Alo, Gtc, Ioc)\n- `AssetType`: Perp or Spot assets\n\n### Account Data\n- `Position`: Perpetual position information\n- `SpotBalance`: Spot token balances\n- `UserVaultEquity`: Vault equity and lock information\n- `Delegation`: Staking delegation details\n\n### Market Data\n- `PerpAssetInfo`: Perpetual asset metadata\n- `SpotInfo`: Spot market information\n- `TokenInfo`: Token contract details\n- `Bbo`: Best bid/offer prices\n\n## Constants and Scaling\n\n### Price and Size Scaling\n- `SCALE_FACTOR = 10**8`: Used for perpetual prices and sizes\n- `USD_SCALE_FACTOR = 10**6`: Used for USD amounts\n\n### Example Asset IDs (Testnet)\n- BTC Perp: `3`\n- BTC Spot: `50`\n- BTC Token: `69`\n\n## Testing\n\nThe library includes comprehensive tests covering all functionality:\n\n```bash\n# Run all tests\npytest\n\n# Run specific test categories\npytest tests/test_info.py # Market data tests\npytest tests/test_exchange.py # Trading tests\npytest tests/test_endpoint.py # Connection tests\npytest tests/test_utils.py # Utility tests\n```\n\n### Test Environment\n\nTests require a `.env` file with:\n```bash\nPRIVATE_KEY=your_testnet_private_key\n```\n\nSome tests are skipped by default due to balance requirements:\n- Token delegation tests (require HYPE tokens)\n- Staking tests (require HYPE tokens)\n\n## Error Handling\n\nThe library provides proper error handling for common scenarios:\n\n- Invalid asset IDs\n- Insufficient balances\n- Network connectivity issues\n- Invalid action types\n\n## Development\n\n### Requirements\n- Python 3.10+\n- uv (for dependency management)\n- web3.py 7.13.0+\n- eth-abi 5.2.0+\n\n### Setup\n```bash\ngit clone https://github.com/oneforalone/hl-web3-py\ncd hl-web3-py\nuv sync\n```\n\n### Code Quality\nThe project uses:\n- pre-commit hooks\n- pytest for testing\n- ruff for linting\n- pytest-cov for coverage\n\n## License\n\nMIT License\n\n## Support\n\nFor issues and questions:\n- GitHub Issues: https://github.com/oneforalone/hl-web3-py/issues\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 hl-web3-py 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.",
"summary": "Web3 client for Hyperliquid",
"version": "0.1.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6637955f21d335691fbacd92ae7ede833501bd978a5a780143987d84c8ac7b3c",
"md5": "1646796e30e56fe59a69281ac4bdc8e9",
"sha256": "7a967bf5b0072b99671622468095a5007296e072cc73905ea0bc0d1a80376025"
},
"downloads": -1,
"filename": "hl_web3-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1646796e30e56fe59a69281ac4bdc8e9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 10493,
"upload_time": "2025-08-07T09:46:39",
"upload_time_iso_8601": "2025-08-07T09:46:39.582267Z",
"url": "https://files.pythonhosted.org/packages/66/37/955f21d335691fbacd92ae7ede833501bd978a5a780143987d84c8ac7b3c/hl_web3-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cffdc626027a836a780bce24f0a538143737284a77fea8c7b1faec3b0836bcd6",
"md5": "ba8634851d735c88278def65c29c4131",
"sha256": "aaa2f4a18246eb490109a326e86e8ea21c787150464b0ced73fb8248c7af1d84"
},
"downloads": -1,
"filename": "hl_web3-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "ba8634851d735c88278def65c29c4131",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 8027,
"upload_time": "2025-08-07T09:46:40",
"upload_time_iso_8601": "2025-08-07T09:46:40.858713Z",
"url": "https://files.pythonhosted.org/packages/cf/fd/c626027a836a780bce24f0a538143737284a77fea8c7b1faec3b0836bcd6/hl_web3-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 09:46:40",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "hl-web3"
}
