{"id":28741093,"url":"https://github.com/controlcpluscontrolv/ferrofluid","last_synced_at":"2025-06-16T07:11:03.982Z","repository":{"id":298791284,"uuid":"997082147","full_name":"ControlCplusControlV/ferrofluid","owner":"ControlCplusControlV","description":"An actually good Hyperliquid Rust SDK","archived":false,"fork":false,"pushed_at":"2025-06-12T23:12:27.000Z","size":1742,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-13T00:25:46.394Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ControlCplusControlV.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-05T23:40:47.000Z","updated_at":"2025-06-12T23:12:31.000Z","dependencies_parsed_at":"2025-06-13T00:26:12.390Z","dependency_job_id":"abd2f5be-0a76-47ea-8b0d-a71738474872","html_url":"https://github.com/ControlCplusControlV/ferrofluid","commit_stats":null,"previous_names":["controlcpluscontrolv/ferrofluid"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ControlCplusControlV/ferrofluid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ControlCplusControlV%2Fferrofluid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ControlCplusControlV%2Fferrofluid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ControlCplusControlV%2Fferrofluid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ControlCplusControlV%2Fferrofluid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ControlCplusControlV","download_url":"https://codeload.github.com/ControlCplusControlV/ferrofluid/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ControlCplusControlV%2Fferrofluid/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260116642,"owners_count":22961065,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-16T07:11:03.281Z","updated_at":"2025-06-16T07:11:03.966Z","avatar_url":"https://github.com/ControlCplusControlV.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ferrofluid\n\n![Ferrofluid](ferrofluid-background.png)\n\nA high-performance Rust SDK for the Hyperliquid Protocol, built with a \"thin wrapper, maximum control\" philosophy.\n\n[![Crates.io](https://img.shields.io/crates/v/ferrofluid.svg)](https://crates.io/crates/ferrofluid)\n\n## Features\n\n- 🚀 **High Performance**: Uses `simd-json` for 10x faster JSON parsing than `serde_json`\n- 🔒 **Type-Safe**: Strongly-typed Rust bindings with compile-time guarantees\n- 🎯 **Direct Control**: No hidden retry logic or complex abstractions - you control the flow\n- ⚡ **Fast WebSockets**: Built on `fastwebsockets` for 3-4x performance over `tungstenite`\n- 🛠️ **Builder Support**: Native support for MEV builders with configurable fees\n- 📊 **Complete API Coverage**: Info, Exchange, and WebSocket providers for all endpoints\n\n## Installation\n\nAdd this to your `Cargo.toml`:\n\n```toml\n[dependencies]\nferrofluid = \"0.1.0\"\n```\n\n## Quick Start\n\n### Reading Market Data\n\n```rust\nuse ferrofluid::{InfoProvider, Network};\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    let info = InfoProvider::new(Network::Mainnet);\n    \n    // Get all mid prices\n    let mids = info.all_mids().await?;\n    println!(\"BTC mid price: {}\", mids[\"BTC\"]);\n    \n    // Get L2 order book\n    let book = info.l2_book(\"ETH\").await?;\n    println!(\"ETH best bid: {:?}\", book.levels[0][0]);\n    \n    Ok(())\n}\n```\n\n### Placing Orders\n\n```rust\nuse ferrofluid::{ExchangeProvider, signers::AlloySigner};\nuse alloy::signers::local::PrivateKeySigner;\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    // Setup signer\n    let signer = PrivateKeySigner::random();\n    let hyperliquid_signer = AlloySigner { inner: signer };\n    \n    // Create exchange provider\n    let exchange = ExchangeProvider::mainnet(hyperliquid_signer);\n    \n    // Place an order using the builder pattern\n    let result = exchange.order(0) // BTC perpetual\n        .limit_buy(\"50000\", \"0.001\")\n        .reduce_only(false)\n        .send()\n        .await?;\n        \n    println!(\"Order placed: {:?}\", result);\n    Ok(())\n}\n```\n\n### WebSocket Subscriptions\n\n```rust\nuse ferrofluid::{WsProvider, Network, types::ws::Message};\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    let mut ws = WsProvider::connect(Network::Mainnet).await?;\n    \n    // Subscribe to BTC order book\n    let (_id, mut rx) = ws.subscribe_l2_book(\"BTC\").await?;\n    ws.start_reading().await?;\n    \n    // Handle updates\n    while let Some(msg) = rx.recv().await {\n        match msg {\n            Message::L2Book(book) =\u003e {\n                println!(\"BTC book update: {:?}\", book.data.coin);\n            }\n            _ =\u003e {}\n        }\n    }\n    \n    Ok(())\n}\n```\n\n### Managed WebSocket with Auto-Reconnect\n\nFor production use, consider the `ManagedWsProvider` which adds automatic reconnection and keep-alive:\n\n```rust\nuse ferrofluid::{ManagedWsProvider, WsConfig, Network};\nuse std::time::Duration;\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    // Configure with custom settings\n    let config = WsConfig {\n        ping_interval: Duration::from_secs(30),\n        auto_reconnect: true,\n        exponential_backoff: true,\n        ..Default::default()\n    };\n    \n    let ws = ManagedWsProvider::connect(Network::Mainnet, config).await?;\n    \n    // Subscriptions automatically restore on reconnect\n    let (_id, mut rx) = ws.subscribe_l2_book(\"BTC\").await?;\n    ws.start_reading().await?;\n    \n    // Your subscriptions survive disconnections!\n    while let Some(msg) = rx.recv().await {\n        // Handle messages...\n    }\n    \n    Ok(())\n}\n```\n\n## Examples\n\nThe `examples/` directory contains comprehensive examples:\n\n- `00_symbols.rs` - Working with pre-defined symbols\n- `01_info_types.rs` - Using the Info provider for market data\n- `02_info_provider.rs` - Advanced Info provider usage\n- `03_exchange_provider.rs` - Placing and managing orders\n- `04_websocket.rs` - Real-time WebSocket subscriptions\n- `05_builder_orders.rs` - Using MEV builders for orders\n- `06_basis_trade.rs` - Example basis trading strategy\n- `07_managed_websocket.rs` - WebSocket with auto-reconnect and keep-alive\n\nRun examples with:\n```bash\ncargo run --example 01_info_types\n```\n\n## Architecture\n\nFerrofluid follows a modular architecture:\n\n```\nferrofluid/\n├── providers/\n│   ├── info.rs      // Read-only market data (HTTP)\n│   ├── exchange.rs  // Trading operations (HTTP, requires signer)\n│   └── websocket.rs // Real-time subscriptions\n├── types/\n│   ├── actions.rs   // EIP-712 signable actions\n│   ├── requests.rs  // Order, Cancel, Modify structs\n│   ├── responses.rs // API response types\n│   └── ws.rs        // WebSocket message types\n└── signers/\n    └── signer.rs    // HyperliquidSigner trait\n```\n\n## Performance\n\nFerrofluid is designed for maximum performance:\n\n- **JSON Parsing**: Uses `simd-json` for vectorized parsing\n- **HTTP Client**: Built on `hyper` + `tower` for connection pooling\n- **WebSocket**: Uses `fastwebsockets` for minimal overhead\n- **Zero-Copy**: Minimizes allocations where possible\n\n## Builder Support\n\nNative support for MEV builders with configurable fees:\n\n```rust\nlet exchange = ExchangeProvider::mainnet_builder(signer, builder_address);\n\n// All orders automatically include builder info\nlet order = exchange.order(0)\n    .limit_buy(\"50000\", \"0.001\")\n    .send()\n    .await?;\n    \n// Or specify custom builder fee\nlet result = exchange.place_order_with_builder_fee(\u0026order_request, 10).await?;\n```\n\n## Rate Limiting\n\nBuilt-in rate limiter respects Hyperliquid's limits:\n\n```rust\n// Rate limiting is automatic\nlet result = info.l2_book(\"BTC\").await?; // Uses 1 weight\nlet fills = info.user_fills(address).await?; // Uses 2 weight\n```\n\n## Error Handling\n\nComprehensive error types with `thiserror`:\n\n```rust\nmatch exchange.place_order(\u0026order).await {\n    Ok(status) =\u003e println!(\"Success: {:?}\", status),\n    Err(HyperliquidError::RateLimited { available, required }) =\u003e {\n        println!(\"Rate limited: need {} but only {} available\", required, available);\n    }\n    Err(e) =\u003e println!(\"Error: {}\", e),\n}\n```\n\n## Testing\n\nRun the test suite:\n\n```bash\ncargo test\n```\n\nIntegration tests against testnet:\n```bash\ncargo test --features testnet\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\nBuilt with high-performance crates from the Rust ecosystem:\n- [alloy-rs](https://github.com/alloy-rs/alloy) for Ethereum primitives\n- [hyperliquid-rust-sdk](https://github.com/hyperliquid-dex/hyperliquid-rust-sdk/tree/master)\n- [hyper](https://hyper.rs/) for HTTP\n- [fastwebsockets](https://github.com/littledivy/fastwebsockets) for WebSocket\n- [simd-json](https://github.com/simd-lite/simd-json) for JSON parsing\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontrolcpluscontrolv%2Fferrofluid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcontrolcpluscontrolv%2Fferrofluid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontrolcpluscontrolv%2Fferrofluid/lists"}