{"id":51301712,"url":"https://github.com/chainstacklabs/hyperliquid-hip-4","last_synced_at":"2026-06-30T20:30:51.023Z","repository":{"id":368247262,"uuid":"1228312861","full_name":"chainstacklabs/hyperliquid-hip-4","owner":"chainstacklabs","description":"Learning examples and a passive market-maker bot for Hyperliquid HIP-4 outcome markets","archived":false,"fork":false,"pushed_at":"2026-06-29T16:59:31.000Z","size":405,"stargazers_count":8,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-29T18:25:59.534Z","etag":null,"topics":["defi","hip-4","hyperliquid","learning-examples","market-making","prediction-markets"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chainstacklabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-03T21:42:23.000Z","updated_at":"2026-06-29T16:57:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/chainstacklabs/hyperliquid-hip-4","commit_stats":null,"previous_names":["chainstacklabs/hyperliquid-hip-4"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/chainstacklabs/hyperliquid-hip-4","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainstacklabs%2Fhyperliquid-hip-4","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainstacklabs%2Fhyperliquid-hip-4/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainstacklabs%2Fhyperliquid-hip-4/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainstacklabs%2Fhyperliquid-hip-4/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chainstacklabs","download_url":"https://codeload.github.com/chainstacklabs/hyperliquid-hip-4/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chainstacklabs%2Fhyperliquid-hip-4/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34983169,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["defi","hip-4","hyperliquid","learning-examples","market-making","prediction-markets"],"created_at":"2026-06-30T20:30:48.636Z","updated_at":"2026-06-30T20:30:51.010Z","avatar_url":"https://github.com/chainstacklabs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hyperliquid HIP-4 — Learning examples + market-maker bot\n\n\u003e **Built with [Chainstack](https://chainstack.com).** Managed RPC for Hyperliquid — HyperEVM `/evm` (default, hl-node-compliant) and `/nanoreth` (with system transactions) on a single endpoint, plus a subset of HyperCore `/info` queries. Get a private node from the [console](https://console.chainstack.com), browse the [Hyperliquid RPC reference](https://docs.chainstack.com/reference/blockchain-apis), or point your AI agent at the [Chainstack MCP server](https://mcp.chainstack.com) (`get mcp.chainstack.com`) to deploy and manage nodes from your IDE.\n\n---\n\nStandalone Python scripts for every primitive operation on Hyperliquid's\n**HIP-4 outcome markets** (binary prediction / event contracts), plus a small\npassive market-maker bot. Targets testnet by default.\n\n\u003e HIP-4 went live on mainnet 2026-05-02. Currently the only production market\n\u003e is a recurring BTC daily binary; testnet additionally has a HYPE 15-min\n\u003e binary and several validator-deployed test markets including a categorical\n\u003e \"what will Hypurr eat\" question.\n\n## Quick start\n\n```bash\nuv sync\ncp .env.example .env   # then fill in HYPERLIQUID_TESTNET_PRIVATE_KEY + TESTNET_WALLET_ADDRESS\n\n# get USDH for the wallet (HIP-4 settles in USDH, the faucet pays USDC)\nuv run python examples/00_get_usdh.py --amount 50\n\n# explore\nuv run python examples/01_list_outcomes.py\nuv run python examples/02_list_questions.py\nuv run python examples/03_account_state.py\nuv run python examples/04_orderbook_snapshot.py --outcome 5915\n```\n\n## Examples\n\n| # | Script | Purpose |\n|---|---|---|\n| 00 | `00_get_usdh.py` | Buy USDH for USDC on the `@1338` spot pair |\n| 01 | `01_list_outcomes.py` | Enumerate all outcome markets via `outcomeMeta` |\n| 02 | `02_list_questions.py` | List categorical questions and their named legs |\n| 03 | `03_account_state.py` | Show USDC, USDH, and outcome side balances |\n| 04 | `04_orderbook_snapshot.py` | REST top-of-book for both YES and NO sides |\n| 05 | `05_ws_subscribe.py` | Live WebSocket l2Book + trades feed |\n| 06 | `06_place_limit_order.py` | Resting GTC limit order |\n| 07 | `07_cancel_order.py` | Cancel by oid or all opens for a coin |\n| 08 | `08_modify_order.py` | Modify an open order's price/size |\n| 09 | `09_close_position.py` | Cross the book IOC to flatten |\n| 10 | `10_categorical_trade.py` | Trade a single leg of a question |\n| 11 | `11_mint_burn_demo.py` | Explainer of mint/burn/normal-trade fee classes |\n| 12 | `12_wait_for_settlement.py` | Hold to expiry, observe auto-settlement |\n| 13 | `13_split_merge.py` | Explicit `userOutcome` split / merge / negate |\n\n## Bot\n\n```bash\n# market-make BTC daily and HYPE 15-min binaries simultaneously\nuv run python -m bot.market_maker --outcomes 5915,5969 \\\n    --quote-notional 12 --half-spread 0.04 --max-inventory 30 --tick 5\n```\n\nThe bot:\n- Quotes both YES and NO books on each configured outcome.\n- Computes a fair from each book's mid; falls back to `1 - p` from the opposite\n  side when one side has empty bids/asks (common on illiquid outcomes).\n- Sizes orders to a target notional in USDH (defaults to ~$12, just above the\n  $10 server min).\n- Caps inventory per side; once at the cap it stops adding bids on that side.\n- Cancels-and-replaces only when the desired price drifts more than\n  `--repost-threshold`.\n- On Ctrl+C, cancels every open order before exiting.\n\n## Notes on the design (read this first)\n\n### Asset ID encoding\nFor an `outcomeId` and `side` (YES=0, NO=1):\n\n```\nencoding     = 10 * outcomeId + side\nasset_id     = 100_000_000 + encoding\ntrade_coin   = \"#{encoding}\"   # used for l2Book / order placement\nbalance_coin = \"+{encoding}\"   # used in spotClearinghouseState balances\n```\n\n**Two coin string forms exist for the same side asset.** The `#` form is what\nthe `/info` endpoint expects for `l2Book` and what `Exchange.order(...)` takes;\nthe `+` form is what shows up under your account in `spotClearinghouseState`.\nMixing them up will silently fail to find your position. `hl4.outcomes` exposes\n`encode_coin` and `encode_balance_coin` for the two cases.\n\nBTC daily YES (outcome 5915) → trade `#59150`, balance `+59150`, asset_id `100_059_150`.\n\n### SDK doesn't know about HIP-4 yet\n`hyperliquid-python-sdk` (through v0.24.0) has no HIP-4 support. The shared module\n`hl4.client.make_clients()` patches the SDK's `Info` and `Exchange` instances\nby injecting `coin_to_asset` and `name_to_coin` entries for every live outcome\nfetched via `outcomeMeta`. Once injected, normal `Exchange.order(...)` calls\nwork unchanged.\n\n### USDH not USDC\nHIP-4 settles in **USDH** (token id 1452 on testnet). The faucet pays USDC, so\nscript `00_get_usdh.py` swaps USDC → USDH on spot pair `@1338` (~1:1).\n\n### Min notional\nServer enforces a **$10 USDH minimum** per order. Below that you'll get\n`\"Order must have minimum value of 10 USDH\"`.\n\n### Sizes are integer\nOutcome side coins use **integer size precision** on testnet (book sizes show\nas `27.0`, `1024.0` etc.). The bot rounds up to integers; if you place orders\nmanually with fractional sizes you'll get `\"Order has invalid size\"`.\n\n### Price bounds\nOutcome prices are constrained to `0.001 .. 0.999` (probabilities, not raw\nprices). The price tick on the BTC binary is `0.0001` (e.g. `0.4235`); the bot\ndefaults to `0.001` for safety.\n\n### Split / merge: explicit actions AND implicit engine classification\nTwo distinct mechanisms create/destroy shares:\n\n**1. Explicit `userOutcome` actions** (like Polymarket's `splitPosition` /\n`mergePositions`, which earlier HIP-4 builds lacked). Sent as raw L1 actions —\nthe SDK has no helper, so `hl4.outcome_actions` signs them by hand:\n\n| Action | Shape | Effect |\n|---|---|---|\n| split | `{type: userOutcome, splitOutcome: {outcome, amount}}` | lock `amount` USDH → mint `amount` YES + `amount` NO |\n| merge | `{type: userOutcome, mergeOutcome: {outcome, amount\\|null}}` | burn YES+NO pair → release USDH (`null` = max) |\n| negate | `{type: userOutcome, negateOutcome: {question, outcome, amount}}` | burn NO of one named leg → credit YES of every other leg (other named + fallback); unidirectional |\n| merge-question | `{type: userOutcome, mergeQuestion: {question, amount\\|null}}` | burn a complete YES set (1 of every leg) → USDH; the way to unwind a negate / exit a full set without waiting for settlement |\n\nNote: you cannot split a question's **fallback** outcome (`Cannot split\nfallback outcome`). See `examples/13_split_merge.py`.\n\n**2. Implicit engine classification** of orderbook fills — to get YES exposure\nyou place a buy on the YES book; for short-YES you buy NO. The engine labels\neach fill as a side-effect:\n\n| Engine classification | When it happens |\n|---|---|\n| MINT | both counterparties had no prior position |\n| NORMAL | one side opens, the other closes |\n| BURN | both counterparties hold the opposite side and unwind together |\n| SETTLEMENT | at expiry, oracle credits 0 or 1 USDH (`settle_fraction × sz`) |\n\n**Fees are currently zero on outcome markets** (initial testing). See\n`examples/11_mint_burn_demo.py` for the full explainer.\n\n### No claim/redeem call at expiry\nSettlement is automatic — at expiry, USDH credits land in the account. No\nscript needed; `12_wait_for_settlement.py` just polls the balance to show this.\n\n## Disclaimer\n\nThis code is provided **as is**, for educational purposes only, with no\nwarranties of any kind. Nothing here is financial advice. HIP-4 went live\non mainnet days before this was written — the API surface, fee model, and\nmarket roster may shift without notice. You are solely responsible for any\nfunds, keys, or trades involved in running this code. The authors and\nChainstack accept no liability for losses, errors, or any other consequences\narising from its use.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchainstacklabs%2Fhyperliquid-hip-4","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchainstacklabs%2Fhyperliquid-hip-4","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchainstacklabs%2Fhyperliquid-hip-4/lists"}