SDK changelog: releases of @outcome.xyz/hip4

​

Added

• Readable names in parsed* fields. parsedName, sides[].parsedName, and parsedQuestionName on markets, parsedTitle, parsedQuestion, and outcomes[].parsedName on events, outcomes[].parsedName on prices, and parsedEventTitle, parsedMarketQuestion, and parsedOutcomeName on positions carry the names rendered from Hyperliquid’s template registry (outcomeTemplates), for example "BTC touches 90000 by Nov 1, 00:00 UTC" instead of "template:priceTouch". A template question’s fallback leg is rendered as "Other". If the registry can’t be fetched, the template: prefix is still removed from plain names such as "template:Yes". getParsedSideNameResolver() returns the rendered side names, and getSideNameResolver() keeps returning the wire names. See Fetch markets.
• raw on order results. Hyperliquid’s own message when it rejects the whole placeOrder or placeOrders request, for example User or API Wallet 0x... does not exist.. error stays Exchange returned non-ok status.
• formatOutcomePrice(price) formats a HIP-4 outcome price (number or string) for the order wire. See Utilities.
• HIP4Client.fetchSpotAssetCtxs() returns the asset contexts (24h volume and prices) for every spot asset, outcome side coins included.
• classifyOutcome and classifyAllOutcomes take the template registry as an optional last argument.
• readDeployedOutcome(outcome, question, declared) and parseInstanceDescription(description, declared) take an optional set of declared keyword names to drop the segments of a metadata= tag body.

​

Changed

• fetchMarkets honors sortBy. It was ignored before. "newest" puts the highest outcome ID first, "expiry" puts the soonest event time first (markets without one go last), and "volume" puts the highest 24h volume first (one extra spotMetaAndAssetCtxs request). When you omit sortBy, results stay in catalog order. See Events.
• Limit prices round to the outcome tick. placeOrder and placeOrders round limit-order prices to at most 5 significant figures and at most 5 decimals (a 0.00001 tick) before signing. Previously a price below 0.1 could keep 6 decimals, which the exchange rejects.
• parseInstanceDescription, readDeployedOutcome, and readDeployedOutcomes cut the metadata= routing tag that deployers glue onto a value, so threshold:65000 metadata=category:economics reads as 65000.
• Template-name cache. Refreshing the market or event cache makes one extra outcomeTemplates request, cached for 30 seconds.

​

Fixed

• fetchPositions prices. currentPrice and unrealizedPnl now use the live mid. Spot balances name side coins +<coin> while mids use #<coin>, so the lookup always returned "0".
• The fetchApprovedBuilders documentation now states that an address can approve up to 10 builders, not 3.

​

Coming from 1.3.0-beta.0

• Names. The existing name fields are the names Hyperliquid sends again: name, sides[].name, and questionName on markets, title, question, and outcome name on events, side names on prices, and eventTitle, marketQuestion, and outcomeName on positions. Read the rendered names from the parsed* fields above.
• Order errors. When Hyperliquid rejects a whole placeOrder or placeOrders request, error is Exchange returned non-ok status again. Read Hyperliquid’s message from raw.

​

Changed

• Hyperliquid’s own rejection message. When Hyperliquid rejects a whole placeOrder or placeOrders request, result.error now carries Hyperliquid’s message (for example User or API Wallet 0x... does not exist.) instead of the generic Exchange returned non-ok status.
• Limit prices round to 5 decimals. Before signing, limit-order prices are rounded to at most 5 significant figures and at most 5 decimals (a 0.00001 tick). Previously a price below 0.1 could keep 6 decimals, which the exchange rejects.
• fetchMarkets honors sortBy. It was ignored before. "newest" puts the highest outcome ID first, "expiry" puts the soonest event time first (markets without one go last), and "volume" puts the highest 24h volume first (one extra spotMetaAndAssetCtxs request). When you omit sortBy, results stay in catalog order. See Events.
• Readable names for template markets. fetchMarkets, fetchEvents, fetchEvent, the side names on fetchPositions, and outcomeCreated updates render template markets from Hyperliquid’s template registry (outcomeTemplates), for example "BTC touches 90000 by Nov 1, 00:00 UTC" instead of "template:priceTouch". A template question’s fallback leg is named "Other". If the registry can’t be fetched, the template: prefix is still removed from plain names such as "template:Yes". Refreshing the market or event cache makes one extra outcomeTemplates request, cached for 30 seconds.
• classifyOutcome and classifyAllOutcomes take the template registry as an optional last argument. See Utilities.
• parseInstanceDescription cuts the metadata= routing tag that deployers glue onto a value, and takes an optional set of declared keyword names to drop the tag’s body segments.

​

Added

• formatOutcomePrice(price) formats a HIP-4 outcome price (number or string) for the order wire. formatPrice is unchanged. See Utilities.
• HIP4Client.fetchSpotAssetCtxs() returns the asset contexts (24h volume and prices) for every spot asset, outcome side coins included.

​

Fixed

• fetchPositions prices. currentPrice and unrealizedPnl now use the live mid. Spot balances name side coins +<coin> while mids use #<coin>, so the lookup always returned "0".
• The fetchApprovedBuilders documentation now states that an address can approve up to 10 builders, not 3.

​

Fixed

• Unsubscribing before the WebSocket opens. Calling an unsubscribe function before the socket has opened now removes the queued subscribe message. Previously the cancelled subscription was still sent when the socket opened, so its frames kept arriving on the shared channel (for example, a coarse l2Book overwriting a full-precision book subscribed right after it).
• No duplicate queued subscriptions. Identical subscribe messages are queued once, so a socket that drops before opening and reconnects sends each subscription once.

​

Added

• minOrderNotional option. createHIP4Adapter({ minOrderNotional }) raises the client-side order-notional floor above the protocol MIN_NOTIONAL ($1). A value below MIN_NOTIONAL throws when you create the adapter.
• getMinShares(markPx, minNotional?) takes an optional second parameter for the same purpose. MIN_NOTIONAL itself is unchanged.

​

Changed

• MIN_NOTIONAL lowered from 10 to 1. The Hyperliquid network upgrade lowered the minimum order notional for HIP-4 outcome orders to $1. The SDK’s client-side check follows, and getMinShares(markPx) now returns about a tenth of its previous value.
• Release versions. Versions now use the X.Y.Z-beta.N format, and each release carries a signed npm provenance attestation.

​

Removed

• liquidityRewards module (breaking). The World Cup 2026 campaign it queried is permanently retired - Monarch’s campaign API now returns 410 Gone on every route, for any date. Season s1 was the only registered season, so the whole module is gone: liquidityRewards, LIQUIDITY_REWARDS_CONFIG, LiquidityRewardsError, and every LiquidityRewards* type. See Liquidity Rewards (retired).

​

Added

• outcomeRewards module. Programme-wide totals, one wallet’s earnings, finalized reward periods, and a leaderboard, from the public Outcome liquidity-rewards payouts API. See Outcome Rewards.
  • outcomeRewards.programme() - paid/pending/awarded USDC totals
  • outcomeRewards.wallet(address) - one wallet’s totals and reward rows
  • outcomeRewards.periods({ limit }) - every finalized reward period
  • outcomeRewards.leaderboard({ limit }) - wallets ranked by USDC paid
  • OUTCOME_REWARDS_CONFIG, OutcomeRewardsError, and typed results exported from the main entry point

​

Fixed

• Shared WebSocket subscriptions are now reference-counted. When several consumers subscribe with the same payload (e.g. multiple createPriceFeed instances on the allMids feed), they share one underlying wire subscription. Previously the first consumer to unsubscribe tore down the stream for every remaining subscriber - and the reconnect path never restored it. The wire unsubscribe now fires only when the last subscriber leaves. See Real-time data.
• The returned unsubscribe function is idempotent. Calling it more than once is safe - a second call is a no-op and does not affect other subscribers (React Strict Mode invokes effect cleanups twice).

​

Added

• wallet.sellHype(amount) - sell HYPE on the HYPE/USDC spot market. Size is floored to HYPE’s 2 decimals (ROUND_DOWN) so a sell never exceeds your balance. See Wallet.
• wallet.agentSetAbstraction("u" | "p" | "i") - switch the master account’s abstraction mode ("u" unified account, "p" portfolio margin, "i" disabled) via the approved agent key. See Wallet.
• client.fetchUserNonFundingLedgerUpdates(user) - REST counterpart of the userNonFundingLedgerUpdates channel (deposits, withdrawals, transfers), returned newest-first.
• participantsCount on checkRewards results - total distinct participants for the epoch, independent of the wallet filter. See Liquidity Rewards.
• Exported HYPE_USDC_SPOT_INDEX_MAINNET / HYPE_USDC_SPOT_INDEX_TESTNET constants and HLLedgerUpdate, HLLedgerDelta, HLWebData3, HLClearinghouseState, HLFrontendOrder types from the root entry point.

​

Added

• liquidityRewards module - season-scoped liquidity-reward checks, starting with s1 (World Cup 2026). See Liquidity Rewards.
  • checkEligibility({ subject }) - eligible team and match books per scoring day
  • checkRewards({ wallet, date }) - per-wallet reward scores
  • LIQUIDITY_REWARDS_CONFIG, LiquidityRewardsError, and typed results exported from the main entry point
• quoteToken on outcomes - HLOutcome and HLWsOutcomeSpec carry an optional quoteToken symbol. The field is optional on the wire; SDK fetch helpers (outcomeMeta, settled-outcome lookups, and WebSocket outcomeCreated updates) default it to "USDH" when absent.

​

Added

• createHIP4Adapter() - single entry point for HIP-4 prediction market access on Hyperliquid (events, market data, account state, trading, wallet, auth)
• Typed sub-modules: events, marketData, account, trading, wallet, auth, ramp
• WebSocket subscriptions for prices, order books, fills, and positions (return an unsubscribe function)
• Internal L1 agent + EIP-712 signing - no external crypto dependencies
• Decimal-precision math helpers under lib/precision for safe price/size arithmetic
• Stream helpers: createPriceFeed, createPerpPriceFeed
• Type-only entry point: import type { ... } from "@outcome.xyz/hip4/types"

​

Notes

• Zero runtime dependencies
• Node 18+ required