examples

Hypersdk Examples

This directory contains comprehensive examples demonstrating all major SDK features. Examples are organized by complexity and use case.

Setup

Most examples require a private key set via environment variable:

export PRIVATE_KEY="your_private_key_here"

Or create a .env file in the project root:

PRIVATE_KEY=your_private_key_here

Running Examples

# HyperCore examples
cargo run --example list-markets
cargo run --example send_order
cargo run --example websocket-user-events -- --user 0xYourAddress

# Morpho examples
cargo run --example morpho_highest_apy

# Uniswap examples
cargo run --example uniswap_pools_created

---

HyperCore Examples

Beginner - Market Data & Queries

Start here if you're new to the SDK. These examples show read-only operations.

Example	Description	Requires Key
list-markets	List all perpetual markets with details (leverage, tick size)	No
list-tokens	List all spot tokens with metadata	No
list-hip3	Query HIP-3 DEXes and their perpetual markets	No
websocket	Subscribe to real-time trades, order books, and user events	No (read-only)
websocket-user-events	Subscribe to userEvents, TWAP streams, activeAssetData, and webData2	No (read-only, requires user address)
websocket-candles	Subscribe to real-time candlestick (OHLCV) data for a market	No (read-only)
vault_details	Query vault details and performance metrics	No
user_vault_equities	Query a user's vault deposits	No
user_role	Query an address role (User, Vault, Agent, SubAccount)	No

Try first: cargo run --example list-markets

Intermediate - Trading & Transfers

These examples require a private key and perform state-changing operations.

Example	Description	Requires Key
send_order	Place a single limit order on a perpetual market	Yes
send_usd	Send USDC from perpetual balance to another address	Yes
transfer_to_evm	Transfer assets from HyperCore to HyperEVM	Yes
transfer_from_evm	Transfer assets from HyperEVM to HyperCore	Yes
transfer_to_perps	Move assets from spot to perpetual balance	Yes
transfer_to_spot	Move assets from perpetual to spot balance	Yes
vault_transfer	Deposit or withdraw USDC from a vault	Yes
subaccounts	List subaccounts under a master account	No
approve-agent	Approve an API agent for your account	Yes

Try next: cargo run --example send_order (after funding your testnet account)

Advanced - Multi-Signature & Complex Flows

These examples demonstrate advanced patterns for production systems.

Example	Description	Requires Key
multisig_order	Place orders with multiple signers (vault/custody pattern)	Yes (multiple)
multisig_send_usd	Multi-sig USDC transfer	Yes (multiple)
multisig_send_asset	Multi-sig asset transfer between DEXes	Yes (multiple)
multisig-approve-agent	Approve an API agent for a multisig account	Yes (multiple)
buy_and_transfer	Complex flow: place order, wait for fill, transfer to EVM	Yes
priority-fee-bid	Bid on gossip priority Dutch auction for faster order execution	Yes

Production pattern: See multisig_order for how institutional systems manage custody

---

HyperEVM - Morpho Examples

Morpho is a lending protocol on HyperEVM. These examples show how to query lending rates and vault performance.

Example	Description	Requires Key
morpho_highest_apy	Find vaults with highest APY for yield optimization	No
morpho_supply_apy	Query supply APY for specific markets	No
morpho_borrow_apy	Query borrow APY for specific markets	No
morpho_vault_apy	Get detailed vault APY breakdown	No
morpho_vault_performance	Analyze vault performance metrics over time	No
morpho_create_market_events	Subscribe to new Morpho market creation events	No

Use case: Integrate these into lending aggregators or yield farming bots

cargo run --example morpho_highest_apy

---

HyperEVM - Uniswap Examples

Uniswap V3 integration for querying pools and tracking liquidity positions.

Example	Description	Requires Key
uniswap_pools_created	Monitor new pool creation events	No
uniswap_prjx_flows	Track PRJX token flows and liquidity	No

Use case: Market making bots, liquidity analytics, DEX aggregators

cargo run --example uniswap_pools_created

---

Example Output Samples

list_markets

BTC: max leverage 50x, tick size 1, sz_decimals 5
ETH: max leverage 50x, tick size 0.1, sz_decimals 4
...

websocket

Trade: Buy @ 93231.0 size 0.5
Order book update for BTC: 50 bids, 50 asks
User fill: +0.1 BTC @ 93230.0

morpho_highest_apy

Vault: USDC Optimizer
  Supply APY: 8.45%
  Net APY: 8.23%
  TVL: $1,234,567

---

Common Patterns

Price Rounding

All order prices must be rounded to valid tick sizes:

let client = hypercore::mainnet();
let markets = client.perps().await?;
let btc = markets.iter().find(|m| m.name == "BTC").unwrap();

// Round price to valid tick
let rounded = btc.round_price(dec!(93231.23)); // -> 93231

See send_order.rs for complete example.

Error Handling

All examples use anyhow::Result for simple error propagation:

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Your code here
    Ok(())
}

WebSocket Reconnection

The websocket.rs example shows basic subscription, but production systems should implement:

• Automatic reconnection with exponential backoff
• Subscription state management across reconnects
• Message deduplication

---

Troubleshooting

"Private key not found"

Set the PRIVATE_KEY environment variable or create a .env file.

"Order rejected: price not on tick"

Use market.round_price() to round prices to valid tick sizes before submitting orders.

"Insufficient balance"

Fund your testnet account at: https://app.hyperliquid-testnet.xyz/faucet

"Connection timeout"

Ensure you're using the correct network (mainnet vs testnet). Check hypercore::mainnet() vs hypercore::testnet().

---

Next Steps

1. Start with read-only examples (list_markets, websocket)
2. Get testnet funds from the faucet
3. Try a simple trade with send_order
4. Explore advanced patterns like multi-sig and cross-chain transfers
5. Build your bot using WebSocket subscriptions for real-time data

Documentation

• Full API Documentation
• Hyperliquid Docs
• CLAUDE.md - Developer guide for working with this codebase

Contributing

Found a bug in an example? Have a use case we don't cover? Open an issue or PR!