@outcome.xyz/hip4 1.0.0-beta

package/LICENSE

@@ -0,0 +1,101 @@
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+---
+
+Parameters
+
+Licensor: Outcome Labs
+
+Licensed Work: @outcome.xyz/hip4 v1.0.0-beta (all prior and subsequent versions included)
+The Licensed Work is (c) 2026 Outcome Labs.
+
+Additional Use Grant: You may make use of the Licensed Work, provided that
+you may not use the Licensed Work for a Production Use.
+
+                      A "Production Use" is any use of the Licensed Work that
+                      makes the Licensed Work available to third parties as
+                      part of a commercial or non-commercial product,
+                      service, or application, including but not limited to:
+                      (a) incorporating the Licensed Work into a product or
+                          service that is offered to third parties;
+                      (b) using the Licensed Work to operate a service
+                          accessible by third parties;
+                      (c) distributing the Licensed Work or derivative works
+                          to third parties.
+
+                      For purposes of clarity, the following are permitted
+                      under this license without a separate commercial
+                      agreement:
+                      (i)   internal evaluation and testing;
+                      (ii)  non-production development and prototyping;
+                      (iii) academic and educational use;
+                      (iv)  personal, non-commercial projects that are not
+                            offered as a service to third parties.
+
+                      Any Production Use requires a separate commercial
+                      license from the Licensor. Contact: support@outcomelabs.xyz
+
+                      A standing perpetual exception to the foregoing
+                      restriction, granted to the Outcome project, its
+                      operating entity Outcome Labs, and the Outcome
+                      open source community, is set out in the file
+                      LICENSE.OUTCOME-EXCEPTION distributed alongside
+                      this License. That exception forms part of the
+                      Licensor's grants under this License.
+
+Change Date: May 19, 2028
+
+Change License: MIT License
+
+---
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo
+of Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED
+ON AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND
+CONDITIONS, EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT,
+AND TITLE.
+
+IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES, WHETHER DIRECT,
+INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, ARISING OUT OF OR
+IN CONNECTION WITH THIS LICENSE OR THE USE OR INABILITY TO USE THE
+LICENSED WORK, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.

package/README.md

@@ -0,0 +1,224 @@
+<p align="center">
+  <img src="./assets/outcome-icon-light.svg" alt="@outcome.xyz/hip4" />
+</p>
+
+<h1 align="center">@outcome.xyz/hip4</h1>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@outcome.xyz/hip4"><img src="https://img.shields.io/npm/v/@outcome.xyz/hip4.svg" alt="npm version" /></a>
+  <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="zero dependencies" />
+  <img src="https://img.shields.io/npm/l/@outcome.xyz/hip4" alt="license" />
+</p>
+
+---
+
+TypeScript SDK for Hyperliquid HIP-4 prediction markets. Zero runtime dependencies.
+
+## Built for developers
+
+The SDK is structured around a single adapter with typed sub-modules for each domain - events, market data, account state, trading, wallet, and auth. Everything returns typed responses, WebSocket subscriptions return unsubscribe functions, and all signing (L1 agent + EIP-712) is handled internally with no external crypto dependencies.
+
+```bash
+pnpm add @outcome.xyz/hip4
+```
+
+```typescript
+import { createHIP4Adapter } from "@outcome.xyz/hip4";
+
+const hip4 = createHIP4Adapter({ testnet: true });
+await hip4.initialize();
+```
+
+## Examples
+
+- [`auth-eoa.ts`](examples/auth-eoa.ts) - Agent key approval and auth setup
+- [`get-all-markets.ts`](examples/get-all-markets.ts) - Fetch all markets grouped by type
+- [`get-multi-outcome.ts`](examples/get-multi-outcome.ts) - Multi-outcome markets with live prices
+- [`get-recurring-markets.ts`](examples/get-recurring-markets.ts) - Recurring markets with expiry countdowns
+- [`place-limit-order.ts`](examples/place-limit-order.ts) - Limit order with price validation
+- [`place-market-order.ts`](examples/place-market-order.ts) - Market order with FrontendMarket TIF
+- [`stream-prices.ts`](examples/stream-prices.ts) - Stream live prices via WebSocket
+- [`usdh-ramp.ts`](examples/usdh-ramp.ts) - End-to-end USDH on/off-ramp via Coinbase + Across
+
+## API
+
+### `hip4.events`
+
+| Method                           | Description                                                              |
+| -------------------------------- | ------------------------------------------------------------------------ |
+| `fetchEvents(params?)`           | List events. Filters: `category`, `active`, `limit`, `offset`, `query`   |
+| `fetchEvent(eventId)`            | Single event by ID                                                       |
+| `fetchCategories()`              | Available categories                                                     |
+| `fetchMarkets(params?)`          | Typed HIP-4 markets with optional grouping by type or question           |
+| `fetchSettledOutcome(outcomeId)` | Settlement details for a resolved outcome. Returns `null` if not settled |
+
+### `hip4.marketData`
+
+| Method                                            | Description                                   |
+| ------------------------------------------------- | --------------------------------------------- |
+| `fetchOrderBook(marketId, sideIndex?)`            | L2 snapshot                                   |
+| `fetchPrice(marketId)`                            | Both sides, 5s cache                          |
+| `fetchTrades(marketId, limit?)`                   | Recent trades                                 |
+| `fetchCandles(marketId, interval?, start?, end?)` | OHLCV candles                                 |
+| `subscribeOrderBook(marketId, cb)`                | Real-time L2 book                             |
+| `subscribePrice(marketId, cb)`                    | Real-time prices                              |
+| `subscribeTrades(marketId, cb)`                   | Real-time trades                              |
+| `subscribeAllMids(cb)`                            | All mid-prices across every market            |
+| `subscribeActiveAssetCtx(coin, cb)`               | Per-spot-coin context (vol, OI, mark)         |
+| `subscribeSpotAssetCtxs(cb)`                      | Bulk spot-asset context updates               |
+| `subscribePerpAssetCtx(coin, cb)`                 | Per-perp-coin context (mark, oracle, funding) |
+
+### `hip4.account`
+
+| Method                            | Description                                |
+| --------------------------------- | ------------------------------------------ |
+| `fetchPositions(address)`         | Outcome positions with resolved side names |
+| `fetchActivity(address)`          | Fills, last 30 days                        |
+| `fetchBalance(address)`           | Spot balances                              |
+| `fetchOpenOrders(address)`        | Resting orders                             |
+| `subscribePositions(address, cb)` | Polling at 10s                             |
+
+### `hip4.trading`
+
+| Method                  | Description                                                                                                                 |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `placeOrder(params)`    | Place market or limit order. Returns `{ success, orderId?, error? }`                                                        |
+| `placeOrders(params[])` | Batch place orders in a single signed request                                                                               |
+| `modifyOrder(params)`   | Modify a resting order (price and/or size); preserves queue priority on size-only edits                                     |
+| `cancelOrder(params[])` | Cancel one or more resting orders. Returns `HLCancelResponse`                                                               |
+| `scheduleCancel(time)`  | Dead-man's switch - registers a future timestamp at which HL cancels every open order from this agent. Pass `null` to clear |
+| `splitOutcome(params)`  | Split X quote tokens into X Yes + X No shares of one outcome                                                                |
+| `mergeOutcome(params)`  | Merge X paired Yes+No shares back into X quote tokens                                                                       |
+| `mergeQuestion(params)` | Merge X Yes shares from every outcome of a question into X quote tokens                                                     |
+| `negateOutcome(params)` | Convert X No shares of one outcome into X Yes shares of every other outcome in the question                                 |
+
+### `hip4.wallet`
+
+| Method                              | Signing  | Description                     |
+| ----------------------------------- | -------- | ------------------------------- |
+| `setSigner(signer)`                 | -        | Set user wallet for EIP-712 ops |
+| `buyUsdh(amount)`                   | L1 agent | Buy USDH on spot                |
+| `sellUsdh(amount)`                  | L1 agent | Sell USDH on spot               |
+| `transferToSpot(amount)`            | EIP-712  | Perp -> Spot                    |
+| `transferToPerps(amount)`           | EIP-712  | Spot -> Perp                    |
+| `withdraw({ destination, amount })` | EIP-712  | Withdraw to external address    |
+| `usdSend({ destination, amount })`  | EIP-712  | Send to another HL address      |
+
+### `hip4.auth`
+
+| Method                            | Description                                         |
+| --------------------------------- | --------------------------------------------------- |
+| `initAuth(walletAddress, signer)` | Accepts viem `PrivateKeyAccount` or ethers `Signer` |
+| `getAuthStatus()`                 | `"disconnected" \| "pending_approval" \| "ready"`   |
+| `clearAuth()`                     | Reset auth state                                    |
+
+## Market Types
+
+`fetchMarkets()` classifies every HIP-4 outcome into one of four types:
+
+| Type             | Description                                                | Parsed Fields                                                                                  |
+| ---------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `defaultBinary`  | Recurring price markets (BTC > $67250 1d)                  | `underlying`, `targetPrice`, `expiry`, `period`                                                |
+| `labelledBinary` | Standalone binary with custom sides (Hypurr vs Usain Bolt) | Custom side labels                                                                             |
+| `multiOutcome`   | Grouped under a question, with fallback                    | `questionId`, `questionName`, `isFallback`                                                     |
+| `priceBucket`    | Recurring multi-bucket price markets (per-bucket Yes/No)   | `underlying`, `expiry`, `priceThresholds`, `period`, `bucketIndex`, `lowerBound`, `upperBound` |
+
+```typescript
+// Filter by type
+const binaries = await hip4.events.fetchMarkets({ type: "defaultBinary" });
+
+// Group by type
+const grouped = await hip4.events.fetchMarkets({ groupBy: "type" });
+
+// Group multi-outcome by question
+const byQuestion = await hip4.events.fetchMarkets({ groupBy: "question" });
+```
+
+## Configuration
+
+```typescript
+const hip4 = createHIP4Adapter({
+  testnet: true,
+  // Builder fee - collected on every order placed by this adapter
+  builderAddress: "0xYourBuilderAddress",
+  builderFee: 100, // 0.1% (tenths of a basis point, 0–1000)
+  logger: (level, msg, data) => console.log(level, msg, data),
+});
+```
+
+Per-order builder address/fee can also be passed on `placeOrder` to override the adapter-level config.
+
+## Streams
+
+Drop-in price feeds backed by HL's WebSocket. Each takes a callback and returns an unsubscribe function. The snapshot includes the rolling candle history plus the current mid.
+
+```typescript
+import { createPriceFeed, createPerpPriceFeed } from "@outcome.xyz/hip4";
+
+// HIP-4 outcome side (uses sideIndex 0 by default)
+const unsub = createPriceFeed(
+  hip4.marketData,
+  "1758",
+  (snapshot) => console.log(snapshot.currentMid, snapshot.candles),
+  { interval: "1h" },
+);
+unsub();
+```
+
+| Helper                                                     | Use                                                                |
+| ---------------------------------------------------------- | ------------------------------------------------------------------ |
+| `createPriceFeed(marketData, marketId, onSnapshot, opts?)` | Live mid + tick-aggregated candle history for a HIP-4 outcome side |
+| `createPerpPriceFeed(client, coin, onSnapshot, opts?)`     | Same shape for an HL perp coin                                     |
+| `processTick`, `candleBoundaryMs`, `intervalToMs`          | Lower-level candle utilities                                       |
+
+## USDH on/off-ramp (mainnet)
+
+Built-in fiat ↔ USDH ramp via Coinbase + Across. Buy: fiat → Coinbase onramp → USDC (Arbitrum) → Across counterfactual → USDH (HyperCore). Sell: USDH (HyperEVM) → Across swap → USDC (Arbitrum) → Coinbase offramp → fiat. See [`examples/usdh-ramp.ts`](examples/usdh-ramp.ts) for the full flow.
+
+## Orderbook utilities
+
+```typescript
+import {
+  computeTradeCost,
+  computeEstimatedCost,
+  computePotentialReturn,
+} from "@outcome.xyz/hip4";
+
+const cost = computeTradeCost({
+  tokenAmount: 100,
+  orderType: "limit",
+  limitPriceCents: 55, // 0.55 in cents
+});
+// → { estimatedCost, potentialReturn, displayShares }
+```
+
+## Signing
+
+Both Hyperliquid signing flows are implemented from scratch.
+
+**L1 agent signing** (orders, cancels, USDH spot):
+
+1. Sort action keys in canonical order
+2. MessagePack encode
+3. Append nonce as BE u64
+4. Append vault marker byte
+5. Keccak-256 hash -> `connectionId`
+6. EIP-712 sign with `Agent` type on chainId `1337`
+
+**User-signed EIP-712** (transfers, withdrawals, sends):
+
+- Domain: `HyperliquidSignTransaction`, `signatureChainId: 0x66eee`
+- Message filtered to EIP-712 type keys only
+- Requires user wallet, agent keys rejected
+
+## Acknowledgements
+
+Signing implementation inspired by [@nktkas/hyperliquid](https://github.com/nktkas/hyperliquid).
+
+## License
+
+BUSL-1.1
+
+## Builders
+
+Dennis Furrer