@livo-build/runtime 0.2.3 → 0.2.5

package/dist/hyperliquid.js

@@ -0,0 +1,350 @@
+// Hyperliquid — perps/spot trading + market data, batteries-included for bots.
+//
+// Wraps the well-maintained @nktkas/hyperliquid SDK (Worker-safe, self-contained
+// — bundles its own msgpack) and signs with the runtime's own EIP-712 signer via
+// a viem-account-shaped adapter (localAccount), so NO viem/ethers in the bundle.
+// Reads (prices, books, positions) need no key; trading reads HYPERLIQUID_PRIVATE_KEY
+// (falling back to the bot's managed RELAYER_PRIVATE_KEY) and is opt-in by virtue
+// of a key being present. Mainnet by default; set HYPERLIQUID_TESTNET=1 for testnet.
+//
+//   import { Hyperliquid } from "@livo-build/runtime";
+//   const hl = new Hyperliquid(env);
+//   await hl.mid("BTC");                  // crypto perp price, no key
+//   await hl.mid("xyz:TSLA");            // equity perp price (builder dex), no key
+//   await hl.marketBuy("BTC", 0.001);    // needs a funded key
+//
+// IMPORTANT — equities/commodities/FX (TSLA, AAPL, NVDA, GOLD, BRENTOIL, EUR…) are
+// NOT on the main perp dex; they live on Hyperliquid's HIP-3 BUILDER-DEPLOYED perp
+// dexes, addressed as "<dex>:<symbol>" (e.g. "xyz:TSLA"). A bare allMids/l2Book on
+// the main dex returns null for them. This helper resolves builder-dex names for you
+// (mid/book/orders accept "xyz:TSLA"); `findAsset("TSLA")` discovers the full name and
+// `dexs()` lists the deployed dexes. `hl.info` / `hl.exchange` expose the raw clients.
+import { ExchangeClient, HttpTransport, InfoClient } from "@nktkas/hyperliquid";
+import { SymbolConverter } from "@nktkas/hyperliquid/utils";
+import { keccak_256 } from "@noble/hashes/sha3";
+import { localAccount } from "./eip712.js";
+import { privateKeyToAddress } from "./tx.js";
+import { bytesToHex, concatBytes, hexToBytes } from "./hex.js";
+function truthy(v) {
+    return v === true || v === 1 || v === "1" || v === "true";
+}
+// Round to ≤5 significant figures — Hyperliquid's price precision rule.
+function formatPrice(px) {
+    if (px === 0)
+        return "0";
+    return String(Number(px.toPrecision(5)));
+}
+function formatSize(size, szDecimals) {
+    return size.toFixed(szDecimals);
+}
+// The builder-dex prefix of a coin name ("xyz:TSLA" → "xyz"), or undefined for a
+// main-dex perp / spot symbol.
+function dexOf(coin) {
+    const i = coin.indexOf(":");
+    return i > 0 ? coin.slice(0, i) : undefined;
+}
+export class Hyperliquid {
+    /** True when pointed at testnet. */
+    testnet;
+    /** The signer's address (null when no key is configured → read-only). */
+    address;
+    env;
+    transport;
+    _info;
+    privateKey;
+    dexOption;
+    agentSecret;
+    // When set (via forUser), reads default to this account instead of the signer —
+    // because in agent/delegation mode the signer is the agent, not the account owner.
+    readAddressOverride;
+    _exchange;
+    _converter;
+    _meta;
+    constructor(env, options = {}) {
+        this.env = env;
+        this.testnet = options.testnet ?? truthy(env?.HYPERLIQUID_TESTNET);
+        this.transport = new HttpTransport({ isTestnet: this.testnet });
+        this._info = new InfoClient({ transport: this.transport });
+        this.dexOption = options.dexs ?? true;
+        const keySecret = options.privateKeySecret ?? "HYPERLIQUID_PRIVATE_KEY";
+        this.privateKey =
+            options.privateKey ?? env?.[keySecret] ?? env?.RELAYER_PRIVATE_KEY;
+        this.address = this.privateKey ? localAccount(this.privateKey).address : null;
+        this.agentSecret =
+            options.agentSecret ?? env?.HL_AGENT_SECRET ?? env?.RELAYER_PRIVATE_KEY;
+    }
+    /** Raw @nktkas InfoClient (all read endpoints). */
+    get info() {
+        return this._info;
+    }
+    /** Raw @nktkas ExchangeClient (all signed endpoints). Throws if no key is set. */
+    get exchange() {
+        if (!this._exchange) {
+            if (!this.privateKey) {
+                throw new Error("Hyperliquid: trading needs a signing key — set the HYPERLIQUID_PRIVATE_KEY secret (or rely on the bot's RELAYER_PRIVATE_KEY).");
+            }
+            this._exchange = new ExchangeClient({ transport: this.transport, wallet: localAccount(this.privateKey) });
+        }
+        return this._exchange;
+    }
+    // ---- market data (no key needed) ----
+    /**
+     * All mid prices for a dex, keyed by coin. With no arg → the main perp dex
+     * (e.g. { BTC: "95000.0" }). Pass a builder-dex name for equities/commodities
+     * (e.g. mids("xyz") → { "xyz:TSLA": "399.8", "xyz:GOLD": "4160.3", … }).
+     */
+    async mids(dex) {
+        return (await this._info.allMids(dex ? { dex } : undefined));
+    }
+    /**
+     * Mid price of one coin as a number. Accepts a main-dex perp ("BTC") or a
+     * builder-dex asset ("xyz:TSLA") — the right dex is queried automatically.
+     * Throws if the coin isn't listed (try `findAsset` to resolve a bare ticker).
+     */
+    async mid(coin) {
+        const mids = await this.mids(dexOf(coin));
+        const px = mids[coin];
+        if (px === undefined) {
+            throw new Error(`Hyperliquid: "${coin}" not found${dexOf(coin) ? "" : ' — equities/commodities live on a builder dex, e.g. "xyz:TSLA"; use findAsset("TSLA") to resolve'}`);
+        }
+        return Number(px);
+    }
+    /** L2 order book for a coin (main-dex "BTC" or builder-dex "xyz:TSLA"). */
+    async book(coin) {
+        return this._info.l2Book({ coin });
+    }
+    /** Perp account state (positions, margin, withdrawable) for an address (default: the signer). */
+    async positions(user) {
+        return this._info.clearinghouseState({ user: this.requireUser(user) });
+    }
+    /** Resting open orders for an address (default: the signer). */
+    async openOrders(user) {
+        return this._info.openOrders({ user: this.requireUser(user) });
+    }
+    /** Main perp-dex metadata (universe of coins + szDecimals + maxLeverage). Cached. */
+    async meta() {
+        if (!this._meta)
+            this._meta = this._info.meta();
+        return this._meta;
+    }
+    /** The HIP-3 builder-deployed perp dexes (name + fullName + deployer). */
+    async dexs() {
+        const list = (await this._info.perpDexs());
+        return list.filter((d) => Boolean(d && d.name));
+    }
+    /**
+     * Resolve a bare ticker to its full Hyperliquid coin name. "BTC" → "BTC" (main
+     * dex); "TSLA" → "xyz:TSLA" (a builder dex). Returns null if nothing matches.
+     * Use the result with mid/book/limit/market/etc.
+     */
+    async findAsset(symbol) {
+        if (symbol.includes(":"))
+            return symbol; // already dex-qualified (e.g. "xyz:TSLA")
+        const want = symbol.toUpperCase();
+        const { universe } = await this.meta();
+        const main = universe.find((u) => u.name.toUpperCase() === want);
+        if (main)
+            return main.name;
+        for (const d of await this.dexs()) {
+            try {
+                const m = (await this._info.meta({ dex: d.name }));
+                const hit = m.universe.find((u) => u.name.toUpperCase() === `${d.name}:${want}`.toUpperCase());
+                if (hit)
+                    return hit.name;
+            }
+            catch {
+                /* skip a dex that fails to load */
+            }
+        }
+        return null;
+    }
+    /** The integer asset id Hyperliquid uses in orders for a coin (main, spot, or builder dex). */
+    async assetId(coin) {
+        return (await this.lookup(coin)).id;
+    }
+    /** Perp account summary (value, withdrawable, margin) for an address (default: the signer). */
+    async balance(user) {
+        const s = (await this.positions(user));
+        const m = s.marginSummary ?? {};
+        return {
+            accountValue: Number(m.accountValue ?? 0),
+            withdrawable: Number(s.withdrawable ?? 0),
+            totalMarginUsed: Number(m.totalMarginUsed ?? 0),
+            totalNtlPos: Number(m.totalNtlPos ?? 0),
+        };
+    }
+    /** Spot token balances for an address (default: the signer). */
+    async spotBalances(user) {
+        return this._info.spotClearinghouseState({ user: this.requireUser(user) });
+    }
+    /** Recent fills (trade history) for an address (default: the signer). */
+    async fills(user) {
+        return this._info.userFills({ user: this.requireUser(user) });
+    }
+    /** Live context for a coin — mark/mid/oracle price, funding rate, open interest, 24h volume. */
+    async assetCtx(coin) {
+        const dex = dexOf(coin);
+        const [meta, ctxs] = (await this._info.metaAndAssetCtxs(dex ? { dex } : undefined));
+        const i = meta.universe.findIndex((u) => u.name === coin);
+        if (i < 0)
+            throw new Error(`Hyperliquid: "${coin}" not found`);
+        const c = ctxs[i];
+        return {
+            coin,
+            markPx: Number(c.markPx),
+            midPx: c.midPx == null ? null : Number(c.midPx),
+            oraclePx: Number(c.oraclePx),
+            funding: Number(c.funding),
+            openInterest: Number(c.openInterest),
+            prevDayPx: Number(c.prevDayPx),
+            dayNtlVlm: Number(c.dayNtlVlm),
+        };
+    }
+    /** OHLCV candles for charting. `interval` default "1h"; window defaults to the last 24h. */
+    async candles(coin, interval = "1h", opts = {}) {
+        const endTime = opts.endTime ?? Date.now();
+        const startTime = opts.startTime ?? endTime - (opts.lookbackMs ?? 24 * 60 * 60 * 1000);
+        return this._info.candleSnapshot({ coin, interval, startTime, endTime });
+    }
+    // ---- trading (key required) ----
+    /** Raw order passthrough (the @nktkas `order` shape) for full control. */
+    async order(params) {
+        return this.exchange.order(params);
+    }
+    /** Place a limit order. `price`/`size` are numbers; we format to HL's precision. */
+    async limit(coin, isBuy, size, price, opts = {}) {
+        const { id, szDecimals } = await this.lookup(coin);
+        return this.exchange.order({
+            orders: [
+                {
+                    a: id,
+                    b: isBuy,
+                    p: formatPrice(price),
+                    s: formatSize(size, szDecimals),
+                    r: opts.reduceOnly ?? false,
+                    t: { limit: { tif: opts.tif ?? "Gtc" } },
+                },
+            ],
+            grouping: "na",
+        });
+    }
+    limitBuy(coin, size, price, opts) {
+        return this.limit(coin, true, size, price, opts);
+    }
+    limitSell(coin, size, price, opts) {
+        return this.limit(coin, false, size, price, opts);
+    }
+    /**
+     * Market order — an IOC limit priced `slippage` past the current mid so it
+     * crosses immediately. Returns the @nktkas order response.
+     */
+    async market(coin, isBuy, size, opts = {}) {
+        const slippage = opts.slippage ?? 0.05;
+        const mid = await this.mid(coin);
+        const price = isBuy ? mid * (1 + slippage) : mid * (1 - slippage);
+        const { id, szDecimals } = await this.lookup(coin);
+        return this.exchange.order({
+            orders: [
+                {
+                    a: id,
+                    b: isBuy,
+                    p: formatPrice(price),
+                    s: formatSize(size, szDecimals),
+                    r: opts.reduceOnly ?? false,
+                    t: { limit: { tif: "Ioc" } },
+                },
+            ],
+            grouping: "na",
+        });
+    }
+    marketBuy(coin, size, opts) {
+        return this.market(coin, true, size, opts);
+    }
+    marketSell(coin, size, opts) {
+        return this.market(coin, false, size, opts);
+    }
+    /**
+     * Market-close the entire open position in `coin` (reduce-only). Reads the
+     * current size and crosses the opposite side. No-op (returns closed:false) if flat.
+     */
+    async closePosition(coin, opts = {}) {
+        const state = (await this.positions());
+        const pos = (state.assetPositions ?? []).map((p) => p.position).find((p) => p.coin === coin);
+        const szi = pos ? Number(pos.szi) : 0;
+        if (szi === 0)
+            return { closed: false };
+        // Long (szi > 0) → sell to close; short (szi < 0) → buy to close.
+        const result = await this.market(coin, szi < 0, Math.abs(szi), { reduceOnly: true, slippage: opts.slippage });
+        return { closed: true, side: szi < 0 ? "buy" : "sell", size: Math.abs(szi), result };
+    }
+    /** Cancel a resting order by its order id (oid). */
+    async cancel(coin, oid) {
+        return this.exchange.cancel({ cancels: [{ a: await this.assetId(coin), o: oid }] });
+    }
+    /** Set leverage for a coin (cross by default). */
+    async updateLeverage(coin, leverage, opts = {}) {
+        return this.exchange.updateLeverage({ asset: await this.assetId(coin), isCross: opts.cross ?? true, leverage });
+    }
+    // The @nktkas SymbolConverter resolves asset ids + szDecimals across the main
+    // perp dex, spot, AND HIP-3 builder dexes (so "xyz:TSLA" → its global asset id).
+    symbols() {
+        if (!this._converter) {
+            this._converter = SymbolConverter.create({ transport: this.transport, dexs: this.dexOption });
+        }
+        return this._converter;
+    }
+    async lookup(coin) {
+        const c = await this.symbols();
+        const id = c.getAssetId(coin);
+        const szDecimals = c.getSzDecimals(coin);
+        if (id === undefined || szDecimals === undefined) {
+            throw new Error(`Hyperliquid: "${coin}" not found${dexOf(coin) ? "" : ' — equities/commodities are on a builder dex, e.g. "xyz:TSLA"; use findAsset("TSLA") to resolve'}`);
+        }
+        return { id, szDecimals };
+    }
+    requireUser(user) {
+        // In agent/delegation mode (forUser) reads target the account owner, not the agent.
+        const who = (user ?? this.readAddressOverride ?? this.address);
+        if (!who)
+            throw new Error("Hyperliquid: no address — pass one, or configure a signing key.");
+        return who;
+    }
+    // ---- delegation: agent (API) wallets ----
+    //
+    // Hyperliquid agent/API wallets let a user authorize another key to TRADE on
+    // their account WITHOUT being able to withdraw. The flow ("connect & let the app
+    // act"): (1) the app derives a per-user agent key here (deterministic, never
+    // stored); (2) the USER approves `agentAddress(userId)` once with their OWN wallet
+    // via `approveAgent` (in the frontend with their connected wallet — see
+    // livo://skill/hyperliquid); (3) the backend trades for them with `forUser(...)`.
+    // The agent can place/cancel orders; it can never withdraw their funds.
+    /** The per-user agent PRIVATE key (deterministic from the agent secret + userId; never stored). */
+    agentKey(userId) {
+        if (!this.agentSecret) {
+            throw new Error("Hyperliquid: no agent secret — set HL_AGENT_SECRET (or rely on the bot's RELAYER_PRIVATE_KEY) to derive per-user agent wallets.");
+        }
+        const secretBytes = hexToBytes(this.agentSecret.trim().replace(/^0x/, ""));
+        const seed = concatBytes(secretBytes, new TextEncoder().encode("livo-hl-agent:" + userId));
+        return bytesToHex(keccak_256(seed)); // 32 bytes → a valid secp256k1 key with overwhelming probability
+    }
+    /** The agent ADDRESS the user must approve (show this in your connect/approve UI). */
+    agentAddress(userId) {
+        return privateKeyToAddress(this.agentKey(userId));
+    }
+    /**
+     * A Hyperliquid bound to one end-user: it SIGNS orders with that user's agent key
+     * and READS/attributes to their `master` account. Use after the user has approved
+     * `agentAddress(userId)`. Trading methods (marketBuy/limit/closePosition/cancel/…)
+     * then act on the user's account; positions()/balance() default to `master`.
+     */
+    forUser(userId, master) {
+        const bound = new Hyperliquid(this.env, {
+            privateKey: this.agentKey(userId),
+            testnet: this.testnet,
+            dexs: this.dexOption,
+            agentSecret: this.agentSecret,
+        });
+        bound.readAddressOverride = master;
+        return bound;
+    }
+}

package/dist/hyperliquid.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hyperliquid.test.js

@@ -0,0 +1,31 @@
+// Hyperliquid agent-wallet delegation: per-user agent keys must be deterministic
+// (recomputable, never stored) and the bound client must sign as the agent.
+import { describe, expect, it } from "vitest";
+import { Hyperliquid } from "./hyperliquid.js";
+import { localAccount } from "./eip712.js";
+const SECRET = "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d";
+const MASTER = "0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826";
+describe("Hyperliquid agent-wallet delegation", () => {
+    const hl = new Hyperliquid({ HL_AGENT_SECRET: SECRET });
+    it("derives a deterministic per-user agent key", () => {
+        expect(hl.agentKey("user-1")).toBe(hl.agentKey("user-1")); // stable
+        expect(hl.agentKey("user-1")).not.toBe(hl.agentKey("user-2")); // per-user
+        expect(hl.agentKey("user-1")).toMatch(/^0x[0-9a-f]{64}$/);
+    });
+    it("agentAddress matches the derived key's address", () => {
+        expect(hl.agentAddress("user-1").toLowerCase()).toBe(localAccount(hl.agentKey("user-1")).address.toLowerCase());
+    });
+    it("forUser signs as the agent (not the master)", () => {
+        const bound = hl.forUser("user-1", MASTER);
+        expect(bound.address?.toLowerCase()).toBe(hl.agentAddress("user-1").toLowerCase());
+        expect(bound.address?.toLowerCase()).not.toBe(MASTER.toLowerCase());
+    });
+    it("changing the agent secret changes every agent address (re-approval needed)", () => {
+        const other = new Hyperliquid({}, { agentSecret: "0x" + "11".repeat(32) });
+        expect(other.agentAddress("user-1")).not.toBe(hl.agentAddress("user-1"));
+    });
+    it("throws a clear error when no agent secret is configured", () => {
+        const bare = new Hyperliquid({}, { agentSecret: undefined });
+        expect(() => bare.agentKey("user-1")).toThrow(/agent secret/i);
+    });
+});

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export { multicall, MULTICALL3_ADDRESS } from "./multicall.js";
 export type { MulticallCall, MulticallOptions } from "./multicall.js";
 export { watchLogs } from "./watch.js";
 export type { WatchLogsOptions, WatchLogsResult } from "./watch.js";
+export { defineWatcher } from "./watcher.js";
+export type { WatcherEnv, WatcherMatch, WatcherScope, WatcherContext, WatcherDefinition, WatcherModule, SubscribeOptions, Confidence, MatchStatus, } from "./watcher.js";
 export { Relayer } from "./relayer.js";
 export { Queue, queue, queueEnvKey } from "./queue.js";
 export type { RelayerOptions } from "./relayer.js";
@@ -13,6 +15,12 @@ export { Indexer, indexer, indexerEnvKey, GraphQLError } from "./indexer.js";
 export type { IndexerOptions } from "./indexer.js";
 export { Telegram } from "./telegram.js";
 export type { TelegramOptions, BotMessage, SendMessageOptions } from "./telegram.js";
+export { Hyperliquid } from "./hyperliquid.js";
+export type { HyperliquidOptions, PlaceOrderOptions, MarketOrderOptions, Tif, CandleInterval, CandlesOptions, AssetContext, AccountBalance, } from "./hyperliquid.js";
+export { Polymarket } from "./polymarket.js";
+export type { PolymarketOptions, PolymarketCreds, PlaceOrderParams, Side, OrderType, SignatureType, PriceInterval, PriceHistoryOptions, MarketOutcome, ResolvedMarket, } from "./polymarket.js";
+export { hashTypedData, signTypedData, localAccount } from "./eip712.js";
+export type { TypedDataDomain, TypedDataField, TypedDataTypes, TypedDataDefinition, ViemTypedDataParams, LocalAccount, } from "./eip712.js";
 export { Store, STORE_TABLE } from "./store.js";
 export type { D1Like } from "./store.js";
 export { log } from "./log.js";
@@ -23,6 +31,8 @@ export { encodeFunctionData, encodeParameters, decodeParameters, decodeFunctionR
 export type { AbiFunction, AbiParameter, ParsedSignature } from "./abi.js";
 export { signTransaction, transactionHashToSign, transactionHash, privateKeyToAddress, toChecksumAddress, } from "./tx.js";
 export type { Eip1559Tx } from "./tx.js";
+export { hashMessage, recoverMessageAddress, verifyMessage } from "./sig.js";
+export type { VerifyMessageParams } from "./sig.js";
 export { eventTopic, encodeFilterTopics, encodeIndexedTopic, decodeLog, parseEventSignature, } from "./events.js";
 export type { AbiEvent, RawLog, DecodedLog } from "./events.js";
 export { bytesToHex, hexToBytes, concatBytes, toBigInt, } from "./hex.js";

package/dist/index.js

@@ -7,6 +7,9 @@ export { Chain, isNonceCollision } from "./chain.js";
 export { multicall, MULTICALL3_ADDRESS } from "./multicall.js";
 // watchLogs — resumable, cursor-persisted event catch-up for keepers.
 export { watchLogs } from "./watch.js";
+// defineWatcher — onMatch primitive for Signal Radar watchers (HTTP-triggered,
+// one subscription-addressed match per request) + ctx.subscribe/cancel.
+export { defineWatcher } from "./watcher.js";
 // Relayer — managed signing for bots (custodied RELAYER_PRIVATE_KEY + optional
 // Convex-serialized nonces). A Chain that defaults to the relayer key.
 export { Relayer } from "./relayer.js";
@@ -20,6 +23,14 @@ export { Wallet, UserWallet } from "./wallet.js";
 export { Indexer, indexer, indexerEnvKey, GraphQLError } from "./indexer.js";
 // Telegram — webhook verification + reply plumbing for bots.
 export { Telegram } from "./telegram.js";
+// Hyperliquid — perps/spot data + trading (wraps @nktkas/hyperliquid; signs with
+// the runtime's EIP-712 signer, no viem/ethers in the bundle).
+export { Hyperliquid } from "./hyperliquid.js";
+// Polymarket — prediction-market data (public, frontend-safe) + CLOB order
+// placement (native EIP-712 + L2 HMAC; no @polymarket/clob-client, no ethers).
+export { Polymarket } from "./polymarket.js";
+// EIP-712 — typed-data hashing/signing + a viem-account-shaped local signer.
+export { hashTypedData, signTypedData, localAccount } from "./eip712.js";
 // Layer 3 — State + utilities.
 export { Store, STORE_TABLE } from "./store.js";
 export { log } from "./log.js";
@@ -28,6 +39,9 @@ export { requireSecret, requireSecrets, getSecret } from "./secret.js";
 // Low-level escape hatches — ABI coding, signing, RLP, hex. Power users only.
 export { encodeFunctionData, encodeParameters, decodeParameters, decodeFunctionResult, functionSelector, functionSignature, functionFromSignature, parseSignature, findFunction, keccak256, } from "./abi.js";
 export { signTransaction, transactionHashToSign, transactionHash, privateKeyToAddress, toChecksumAddress, } from "./tx.js";
+// EIP-191 message verification — prove a user controls an address from a signed
+// message (wallet-link / SIWE login), recovered server-side with no hand-rolled crypto.
+export { hashMessage, recoverMessageAddress, verifyMessage } from "./sig.js";
 export { eventTopic, encodeFilterTopics, encodeIndexedTopic, decodeLog, parseEventSignature, } from "./events.js";
 export { bytesToHex, hexToBytes, concatBytes, toBigInt, } from "./hex.js";
 // Layer 2 — generated contract bindings live in "@livo/runtime/contracts".

package/dist/polymarket.d.ts

@@ -0,0 +1,146 @@
+export type Side = "BUY" | "SELL";
+export type OrderType = "GTC" | "FOK" | "GTD" | "FAK";
+export type PriceInterval = "1m" | "1h" | "6h" | "1d" | "1w" | "max";
+export interface PriceHistoryOptions {
+    /** Coarse window. Default "1d". */
+    interval?: PriceInterval;
+    /** Resolution in minutes per point (e.g. 60). */
+    fidelity?: number;
+    /** Explicit window (unix seconds) — overrides `interval` if both given. */
+    startTs?: number;
+    endTs?: number;
+}
+/** One tradable outcome of a market (the thing you pass as `tokenId`). */
+export interface MarketOutcome {
+    outcome: string;
+    tokenId: string;
+}
+/** A resolved market: its question + the token id for each outcome. */
+export interface ResolvedMarket {
+    question: string;
+    conditionId?: string;
+    slug?: string;
+    negRisk: boolean;
+    tokens: MarketOutcome[];
+}
+/** 0 = EOA, 1 = Polymarket Proxy, 2 = Gnosis Safe (clob-client SignatureType). */
+export type SignatureType = 0 | 1 | 2;
+export interface PolymarketCreds {
+    key: string;
+    secret: string;
+    passphrase: string;
+}
+export interface PolymarketOptions {
+    /**
+     * Enable the deprecated V1 CTF Exchange order path (V2 signing isn't implemented
+     * here yet — see docs/POLYMARKET-V2-IMPLEMENTATION.md). V1 orders are rejected on
+     * production, so this is for testnet/legacy only. Without it, trading throws (data
+     * reads always work).
+     */
+    allowLegacyV1?: boolean;
+    /** Signing key. Default: env.POLYMARKET_PRIVATE_KEY, then env.RELAYER_PRIVATE_KEY. */
+    privateKey?: string;
+    /** Env var name to read the key from. Default: "POLYMARKET_PRIVATE_KEY". */
+    privateKeySecret?: string;
+    /** Polygon chain id. Default 137 (mainnet); 80002 = Amoy testnet. */
+    chainId?: number;
+    /** Pre-provisioned API creds (else POLYMARKET_API_KEY/SECRET/PASSPHRASE, else derived). */
+    creds?: PolymarketCreds;
+    /** Override the CLOB host. */
+    host?: string;
+}
+export interface PlaceOrderParams {
+    /** ERC-1155 outcome token id (the "YES"/"NO" asset). */
+    tokenId: string;
+    side: Side;
+    /** Price per share in USDC, 0–1 (e.g. 0.55). */
+    price: number;
+    /** Number of shares. */
+    size: number;
+    /** Order type. Default "GTC". */
+    orderType?: OrderType;
+    /** Fee rate (bps). Default 0. */
+    feeRateBps?: number;
+    /** Maker nonce. Default 0. */
+    nonce?: number;
+    /** Unix expiration (GTD). Default 0 (none). */
+    expiration?: number;
+    /** Funder address holding the USDC (for proxy/safe). Default: the signer. */
+    funder?: string;
+    /** Signature type. Default 0 (EOA). */
+    signatureType?: SignatureType;
+    /** Tick size ("0.1"|"0.01"|"0.001"|"0.0001"). Default: fetched from the CLOB. */
+    tickSize?: string;
+    /** Whether the market is a neg-risk market. Default: fetched from the CLOB. */
+    negRisk?: boolean;
+}
+interface MinimalEnv {
+    [key: string]: unknown;
+}
+export declare class Polymarket {
+    /** Polygon chain id this client signs for. */
+    readonly chainId: number;
+    /** The signer's address (null when no key is configured → read-only). */
+    readonly address: string | null;
+    private readonly host;
+    private readonly privateKey?;
+    private readonly legacyV1;
+    private readonly contracts;
+    private creds?;
+    constructor(env: MinimalEnv | undefined, options?: PolymarketOptions);
+    /** Gamma markets — the rich, searchable market catalog. Pass query params (e.g. { active: true, limit: 10 }). */
+    gammaMarkets(query?: Record<string, string | number | boolean>): Promise<unknown>;
+    /** A single Gamma market by id. */
+    gammaMarket(id: string | number): Promise<unknown>;
+    /** CLOB markets (paginated; pass a cursor to page). */
+    markets(cursor?: string): Promise<unknown>;
+    /** Order book for an outcome token. */
+    book(tokenId: string): Promise<unknown>;
+    /** Best price for a token on a side. */
+    price(tokenId: string, side: Side): Promise<number>;
+    /** Midpoint price for a token. */
+    midpoint(tokenId: string): Promise<number>;
+    /** Minimum tick size for a token (e.g. "0.01"). */
+    tickSize(tokenId: string): Promise<string>;
+    /** Whether a token's market is a neg-risk market. */
+    negRisk(tokenId: string): Promise<boolean>;
+    /** Last traded price for a token. */
+    lastTradePrice(tokenId: string): Promise<number>;
+    /** Bid/ask spread for a token. */
+    spread(tokenId: string): Promise<unknown>;
+    /** Historical price points for charting a token. */
+    priceHistory(tokenId: string, opts?: PriceHistoryOptions): Promise<unknown>;
+    /**
+     * Resolve a market by slug, numeric Gamma id, or 0x condition id → its question
+     * and the token id for each outcome. THE way to turn "will X happen?" into the
+     * `tokenId` you trade: `(await pm.resolveMarket(slug)).tokens` → [{outcome:"Yes",tokenId},…].
+     */
+    resolveMarket(slugOrId: string): Promise<ResolvedMarket | null>;
+    /** The collateral token address to fund/approve (pUSD on V2; USDC.e on legacy V1). */
+    get collateralToken(): string | undefined;
+    /** A user's open positions (holdings) from the public data API (default: the signer). */
+    positions(user?: string): Promise<unknown>;
+    /** Ensure API credentials exist (derive existing, else create). Cached on the instance. */
+    ensureCreds(): Promise<PolymarketCreds>;
+    private assertTradingEnabled;
+    private deriveOrCreateApiKey;
+    /** Build, sign, and submit an order. Returns the CLOB response JSON. */
+    placeOrder(params: PlaceOrderParams): Promise<unknown>;
+    /** Cancel one order by id. */
+    cancelOrder(orderId: string): Promise<unknown>;
+    /** Cancel all of the signer's open orders. */
+    cancelAll(): Promise<unknown>;
+    /** The signer's open orders (L2-authed). */
+    openOrders(): Promise<unknown>;
+    /**
+     * The signer's USDC collateral balance + exchange allowance (or, with a tokenId,
+     * the conditional-token balance). Check this before trading — orders fail if the
+     * CTF Exchange isn't approved to spend your USDC.e.
+     */
+    balances(tokenId?: string): Promise<unknown>;
+    private l1Headers;
+    private l2Headers;
+    private requireSigner;
+    private getJson;
+}
+export {};