@livo-build/runtime 0.2.5 → 0.2.12

package/dist/hyperliquid.js

@@ -25,6 +25,35 @@ import { keccak_256 } from "@noble/hashes/sha3";
 import { localAccount } from "./eip712.js";
 import { privateKeyToAddress } from "./tx.js";
 import { bytesToHex, concatBytes, hexToBytes } from "./hex.js";
+/** Parse a Hyperliquid clearinghouse position into a clean PositionInfo. */
+export function parseHlPosition(p) {
+    const szi = Number(p.szi);
+    return {
+        coin: p.coin,
+        size: Math.abs(szi),
+        side: szi > 0 ? "long" : szi < 0 ? "short" : "flat",
+        entryPx: Number(p.entryPx ?? 0),
+        positionValue: Number(p.positionValue ?? 0),
+        unrealizedPnl: Number(p.unrealizedPnl ?? 0),
+        returnOnEquity: Number(p.returnOnEquity ?? 0),
+        leverage: Number(p.leverage?.value ?? 0),
+        liquidationPx: p.liquidationPx != null ? Number(p.liquidationPx) : null,
+        marginUsed: Number(p.marginUsed ?? 0),
+    };
+}
+/** Parse an L2 book into a best bid/offer + mid + spread. */
+export function parseBbo(book) {
+    const bidPx = book.levels?.[0]?.[0]?.px;
+    const askPx = book.levels?.[1]?.[0]?.px;
+    const bid = bidPx != null ? Number(bidPx) : null;
+    const ask = askPx != null ? Number(askPx) : null;
+    return {
+        bid,
+        ask,
+        mid: bid != null && ask != null ? (bid + ask) / 2 : null,
+        spread: bid != null && ask != null ? ask - bid : null,
+    };
+}
 function truthy(v) {
     return v === true || v === 1 || v === "1" || v === "true";
 }
@@ -206,6 +235,47 @@ export class Hyperliquid {
         const startTime = opts.startTime ?? endTime - (opts.lookbackMs ?? 24 * 60 * 60 * 1000);
         return this._info.candleSnapshot({ coin, interval, startTime, endTime });
     }
+    /** Recent public trades for a coin. */
+    async recentTrades(coin) {
+        return this._info.recentTrades({ coin });
+    }
+    /** Best bid/offer + mid + spread for a coin (parsed from the L2 book). */
+    async bbo(coin) {
+        return parseBbo((await this.book(coin)));
+    }
+    /** All open positions as clean PositionInfo[] (default: the signer's account). */
+    async positionsList(user) {
+        const s = (await this.positions(user));
+        return (s.assetPositions ?? []).map((ap) => parseHlPosition(ap.position));
+    }
+    /** A single open position for a coin, or null if flat. */
+    async position(coin, user) {
+        return (await this.positionsList(user)).find((p) => p.coin === coin) ?? null;
+    }
+    /** Current hourly funding rate for a coin (fraction, e.g. 0.0000125). */
+    async fundingRate(coin) {
+        return (await this.assetCtx(coin)).funding;
+    }
+    /** Historical funding rates for a coin (default: the last 7 days). */
+    async fundingHistory(coin, opts = {}) {
+        const endTime = opts.endTime ?? Date.now();
+        const startTime = opts.startTime ?? endTime - (opts.lookbackMs ?? 7 * 24 * 60 * 60 * 1000);
+        return this._info.fundingHistory({ coin, startTime, endTime });
+    }
+    /** Funding payments paid/received by an account (default signer; last 7 days). */
+    async userFunding(opts = {}, user) {
+        const endTime = opts.endTime ?? Date.now();
+        const startTime = opts.startTime ?? endTime - (opts.lookbackMs ?? 7 * 24 * 60 * 60 * 1000);
+        return this._info.userFunding({ user: this.requireUser(user), startTime, endTime });
+    }
+    /** Predicted next funding rates across venues (no key). */
+    async predictedFundings() {
+        return this._info.predictedFundings();
+    }
+    /** Portfolio history (PnL/account-value time series) for an account (default: the signer). */
+    async portfolio(user) {
+        return this._info.portfolio({ user: this.requireUser(user) });
+    }
     // ---- trading (key required) ----
     /** Raw order passthrough (the @nktkas `order` shape) for full control. */
     async order(params) {
@@ -281,10 +351,134 @@ export class Hyperliquid {
     async cancel(coin, oid) {
         return this.exchange.cancel({ cancels: [{ a: await this.assetId(coin), o: oid }] });
     }
+    /** Cancel a resting order by its client order id (cloid). */
+    async cancelByCloid(coin, cloid) {
+        return this.exchange.cancelByCloid({ cancels: [{ asset: await this.assetId(coin), cloid }] });
+    }
+    /** Cancel ALL resting orders (optionally only for one coin). Returns the count cancelled. */
+    async cancelAll(coin) {
+        const orders = (await this.openOrders());
+        const targets = coin ? orders.filter((o) => o.coin === coin) : orders;
+        if (!targets.length)
+            return { cancelled: 0 };
+        const cancels = await Promise.all(targets.map(async (o) => ({ a: await this.assetId(o.coin), o: o.oid })));
+        await this.exchange.cancel({ cancels });
+        return { cancelled: targets.length };
+    }
+    /** Modify a resting limit order in place (new size/price/side). */
+    async modifyOrder(oid, coin, isBuy, size, price, opts = {}) {
+        const { id, szDecimals } = await this.lookup(coin);
+        return this.exchange.modify({
+            oid,
+            order: {
+                a: id,
+                b: isBuy,
+                p: formatPrice(price),
+                s: formatSize(size, szDecimals),
+                r: opts.reduceOnly ?? false,
+                t: { limit: { tif: opts.tif ?? "Gtc" } },
+            },
+        });
+    }
+    /**
+     * Place a trigger order (stop / take-profit). `triggerPx` is the activation price;
+     * `tpsl` is "sl" (stop) or "tp". Market trigger by default (fills at market once
+     * armed); reduce-only by default (closing). `isBuy` is the side that executes —
+     * to protect a LONG use isBuy=false (sell), for a SHORT use isBuy=true (buy).
+     */
+    async trigger(coin, isBuy, size, triggerPx, opts) {
+        const { id, szDecimals } = await this.lookup(coin);
+        return this.exchange.order({
+            orders: [
+                {
+                    a: id,
+                    b: isBuy,
+                    p: formatPrice(opts.price ?? triggerPx),
+                    s: formatSize(size, szDecimals),
+                    r: opts.reduceOnly ?? true,
+                    t: { trigger: { isMarket: opts.isMarket ?? true, triggerPx: formatPrice(triggerPx), tpsl: opts.tpsl } },
+                },
+            ],
+            grouping: "na",
+        });
+    }
+    /** Stop-loss trigger (reduce-only market by default). See `trigger` for `isBuy`. */
+    stopLoss(coin, isBuy, size, triggerPx, opts = {}) {
+        return this.trigger(coin, isBuy, size, triggerPx, { ...opts, tpsl: "sl" });
+    }
+    /** Take-profit trigger (reduce-only market by default). See `trigger` for `isBuy`. */
+    takeProfit(coin, isBuy, size, triggerPx, opts = {}) {
+        return this.trigger(coin, isBuy, size, triggerPx, { ...opts, tpsl: "tp" });
+    }
+    /** Dead-man's switch: auto-cancel all orders at `timeMs` (epoch) unless re-armed. Omit to clear. */
+    async scheduleCancel(timeMs) {
+        return this.exchange.scheduleCancel(timeMs ? { time: timeMs } : {});
+    }
+    /** Move USDC from spot into the perp wallet (margin top-up; not a withdrawal). */
+    async transferToPerp(usd) {
+        return this.exchange.usdClassTransfer({ amount: String(usd), toPerp: true });
+    }
+    /** Move USDC from the perp wallet back to spot. */
+    async transferToSpot(usd) {
+        return this.exchange.usdClassTransfer({ amount: String(usd), toPerp: false });
+    }
     /** 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 });
     }
+    /**
+     * Place a TWAP order — slice `size` evenly over `minutes` (5–1440) to reduce impact.
+     * `randomize` jitters slice timing. Returns the @nktkas response (incl. the TWAP id).
+     */
+    async twap(coin, isBuy, size, minutes, opts = {}) {
+        const { id, szDecimals } = await this.lookup(coin);
+        return this.exchange.twapOrder({
+            twap: { a: id, b: isBuy, s: formatSize(size, szDecimals), r: opts.reduceOnly ?? false, m: minutes, t: opts.randomize ?? false },
+        });
+    }
+    /** Cancel a running TWAP by its id (from the `twap()` response). */
+    async cancelTwap(coin, twapId) {
+        return this.exchange.twapCancel({ a: await this.assetId(coin), t: twapId });
+    }
+    // ---- sub-accounts (isolate strategies under one master) ----
+    /** Create a named sub-account (1–16 chars). Returns its address. */
+    async createSubAccount(name) {
+        return this.exchange.createSubAccount({ name });
+    }
+    /** List sub-accounts for an address (default: the signer). */
+    async subAccounts(user) {
+        return this._info.subAccounts({ user: this.requireUser(user) });
+    }
+    /** Move USDC from the master into a sub-account (`usd` in dollars). */
+    async transferToSubAccount(subAccount, usd) {
+        return this.exchange.subAccountTransfer({ subAccountUser: subAccount, isDeposit: true, usd: Math.round(usd * 1e6) });
+    }
+    /** Move USDC from a sub-account back to the master (`usd` in dollars). */
+    async transferFromSubAccount(subAccount, usd) {
+        return this.exchange.subAccountTransfer({ subAccountUser: subAccount, isDeposit: false, usd: Math.round(usd * 1e6) });
+    }
+    // ---- vaults (deposit into / withdraw from a Hyperliquid vault) ----
+    /** Deposit USDC into a vault (`usd` in dollars). */
+    async vaultDeposit(vault, usd) {
+        return this.exchange.vaultTransfer({ vaultAddress: vault, isDeposit: true, usd: Math.round(usd * 1e6) });
+    }
+    /** Withdraw USDC from a vault (`usd` in dollars). */
+    async vaultWithdraw(vault, usd) {
+        return this.exchange.vaultTransfer({ vaultAddress: vault, isDeposit: false, usd: Math.round(usd * 1e6) });
+    }
+    /** Vault details + your equity in it (public read; pass a user or use the signer). */
+    async vaultDetails(vault, user) {
+        return this._info.vaultDetails({ vaultAddress: vault, user: (user ?? this.address ?? undefined) });
+    }
+    // ---- account info ----
+    /** Your fee schedule + 14-day volume (default: the signer). */
+    async userFees(user) {
+        return this._info.userFees({ user: this.requireUser(user) });
+    }
+    /** Status of a single order by its oid (resting/filled/canceled). */
+    async orderStatus(oid, user) {
+        return this._info.orderStatus({ user: this.requireUser(user), oid });
+    }
     // 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() {

package/dist/hyperliquid.test.js

@@ -1,7 +1,7 @@
 // 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 { Hyperliquid, parseHlPosition, parseBbo } from "./hyperliquid.js";
 import { localAccount } from "./eip712.js";
 const SECRET = "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d";
 const MASTER = "0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826";
@@ -29,3 +29,19 @@ describe("Hyperliquid agent-wallet delegation", () => {
         expect(() => bare.agentKey("user-1")).toThrow(/agent secret/i);
     });
 });
+describe("Hyperliquid parsers", () => {
+    it("parseHlPosition normalizes a clearinghouse position (side/size/fields)", () => {
+        const long = parseHlPosition({ coin: "BTC", szi: "0.5", entryPx: "60000", positionValue: "31000", unrealizedPnl: "1000", returnOnEquity: "0.12", leverage: { value: 10 }, liquidationPx: "40000", marginUsed: "3100" });
+        expect(long).toMatchObject({ coin: "BTC", size: 0.5, side: "long", entryPx: 60000, unrealizedPnl: 1000, leverage: 10, liquidationPx: 40000 });
+        const short = parseHlPosition({ coin: "ETH", szi: "-2" });
+        expect(short.side).toBe("short");
+        expect(short.size).toBe(2);
+        expect(short.liquidationPx).toBeNull();
+        expect(parseHlPosition({ coin: "X", szi: "0" }).side).toBe("flat");
+    });
+    it("parseBbo derives bid/ask/mid/spread from the L2 book", () => {
+        const bbo = parseBbo({ levels: [[{ px: "99.5" }], [{ px: "100.5" }]] });
+        expect(bbo).toEqual({ bid: 99.5, ask: 100.5, mid: 100, spread: 1 });
+        expect(parseBbo({ levels: [[], []] })).toEqual({ bid: null, ask: null, mid: null, spread: null });
+    });
+});

package/dist/index.d.ts

@@ -6,6 +6,8 @@ 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 { Signals, signals, DEFAULT_SIGNALS_URL } from "./signals.js";
+export type { SignalsOptions, Market, SignalMatch, Swap, Launch, EngineSnapshot, MarketFilter, } from "./signals.js";
 export { Relayer } from "./relayer.js";
 export { Queue, queue, queueEnvKey } from "./queue.js";
 export type { RelayerOptions } from "./relayer.js";
@@ -14,9 +16,32 @@ export type { WalletOptions, WalletAccount, WalletSendOptions } from "./wallet.j
 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 type { TelegramOptions, BotMessage, SendMessageOptions, ChatJoinRequest } from "./telegram.js";
+export { verifyTelegramInitData, verifyTelegramLoginWidget, parseStartPayload } from "./telegramAuth.js";
+export type { TelegramUser, VerifyOptions } from "./telegramAuth.js";
+export { TelegramLinks, TELEGRAM_LINKS_TABLE } from "./telegramLinks.js";
+export type { TelegramLink } from "./telegramLinks.js";
+export { tokenBalanceOf, meetsGate } from "./gate.js";
+export type { TokenGate } from "./gate.js";
+export { tokenMetadata, ownerOf, tokenURI } from "./reads.js";
+export type { TokenMetadata } from "./reads.js";
+export { resolveUri, fetchTokenMetadata } from "./nft.js";
+export type { NftMetadata, NftAttribute, FetchMetadataOptions } from "./nft.js";
+export { createSiweMessage, verifySiweMessage } from "./siwe.js";
+export type { SiweParams, SiweVerifyResult } from "./siwe.js";
+export { createSession, verifySession } from "./sessions.js";
+export type { SessionOptions } from "./sessions.js";
+export { json, error, withCors, CORS_HEADERS, Router, sse } from "./http.js";
+export type { RouteContext, RouteHandler, SseConnection } from "./http.js";
+export { rateLimit } from "./ratelimit.js";
+export type { KvLike, RateLimitOptions, RateLimitResult } from "./ratelimit.js";
+export { encrypt, decrypt } from "./aes.js";
+export { cached } from "./cache.js";
+export type { CacheOptions } from "./cache.js";
+export { verifyWebhook, signWebhook } from "./webhook.js";
+export type { VerifyWebhookParams, SignatureEncoding } from "./webhook.js";
 export { Hyperliquid } from "./hyperliquid.js";
-export type { HyperliquidOptions, PlaceOrderOptions, MarketOrderOptions, Tif, CandleInterval, CandlesOptions, AssetContext, AccountBalance, } from "./hyperliquid.js";
+export type { HyperliquidOptions, PlaceOrderOptions, MarketOrderOptions, Tif, CandleInterval, CandlesOptions, AssetContext, AccountBalance, PositionInfo, Bbo, } 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";

package/dist/index.js

@@ -10,6 +10,10 @@ 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";
+// Signals — READ client for the shared on-chain signals engine (Signal Radar):
+// live markets, recent swaps, fired matches. Zero-config (defaults to the public
+// engine). The push counterpart is defineWatcher above.
+export { Signals, signals, DEFAULT_SIGNALS_URL } from "./signals.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";
@@ -23,6 +27,18 @@ 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";
+export { verifyTelegramInitData, verifyTelegramLoginWidget, parseStartPayload } from "./telegramAuth.js";
+export { TelegramLinks, TELEGRAM_LINKS_TABLE } from "./telegramLinks.js";
+export { tokenBalanceOf, meetsGate } from "./gate.js";
+export { tokenMetadata, ownerOf, tokenURI } from "./reads.js";
+export { resolveUri, fetchTokenMetadata } from "./nft.js";
+export { createSiweMessage, verifySiweMessage } from "./siwe.js";
+export { createSession, verifySession } from "./sessions.js";
+export { json, error, withCors, CORS_HEADERS, Router, sse } from "./http.js";
+export { rateLimit } from "./ratelimit.js";
+export { encrypt, decrypt } from "./aes.js";
+export { cached } from "./cache.js";
+export { verifyWebhook, signWebhook } from "./webhook.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";

package/dist/nft.d.ts

@@ -0,0 +1,33 @@
+import type { Chain } from "./chain.js";
+export interface NftAttribute {
+    trait_type?: string;
+    value?: unknown;
+    [k: string]: unknown;
+}
+export interface NftMetadata {
+    name?: string;
+    description?: string;
+    /** Image URL resolved through the gateway (ipfs:// → https). */
+    image?: string;
+    /** The original, unresolved image value from the metadata document. */
+    imageRaw?: string;
+    /** animation_url resolved through the gateway (video/audio/3D media). */
+    animationUrl?: string;
+    attributes?: NftAttribute[];
+    /** The full parsed metadata document. */
+    raw: Record<string, unknown>;
+}
+export interface FetchMetadataOptions {
+    /** IPFS gateway base, trailing slash included. Default "https://ipfs.io/ipfs/". */
+    gateway?: string;
+    /** ERC-1155 reads uri(id) with {id} substitution; default ERC-721 tokenURI(id). */
+    standard?: "erc721" | "erc1155";
+}
+/** Resolve an ipfs:// / ar:// URI to an HTTP(S) URL. http(s)/data URIs pass through. */
+export declare function resolveUri(uri: string, gateway?: string): string;
+/**
+ * Read a token's metadata URI on-chain, resolve + fetch + parse it, and resolve
+ * the embedded image/animation URLs. Returns null if the URI read reverts (e.g.
+ * unminted). Throws if the metadata document itself can't be fetched/parsed.
+ */
+export declare function fetchTokenMetadata(chain: Chain, token: string, tokenId: bigint, opts?: FetchMetadataOptions): Promise<NftMetadata | null>;

package/dist/nft.js

@@ -0,0 +1,72 @@
+// NFT metadata — read a token's metadata URI on-chain, resolve it (ipfs:// →
+// gateway), fetch + parse the JSON, and resolve the embedded media URLs. Works for
+// ERC-721 (tokenURI) and ERC-1155 (uri(id) with {id} substitution). Pairs with the
+// kit's useNFT / <NFTCard>.
+const DEFAULT_GATEWAY = "https://ipfs.io/ipfs/";
+/** Resolve an ipfs:// / ar:// URI to an HTTP(S) URL. http(s)/data URIs pass through. */
+export function resolveUri(uri, gateway = DEFAULT_GATEWAY) {
+    if (!uri)
+        return uri;
+    if (uri.startsWith("ipfs://")) {
+        let rest = uri.slice("ipfs://".length);
+        if (rest.startsWith("ipfs/"))
+            rest = rest.slice("ipfs/".length); // odd ipfs://ipfs/CID form
+        return gateway + rest;
+    }
+    if (uri.startsWith("ar://"))
+        return "https://arweave.net/" + uri.slice("ar://".length);
+    return uri;
+}
+/** ERC-1155 {id} substitution token: lowercase hex, zero-padded to 64 chars. */
+function erc1155IdHex(tokenId) {
+    return tokenId.toString(16).padStart(64, "0");
+}
+async function loadJson(uri) {
+    if (uri.startsWith("data:")) {
+        const comma = uri.indexOf(",");
+        const header = uri.slice(5, comma);
+        const body = uri.slice(comma + 1);
+        const text = header.includes("base64") ? atob(body) : decodeURIComponent(body);
+        return JSON.parse(text);
+    }
+    const res = await fetch(uri);
+    if (!res.ok)
+        throw new Error(`metadata fetch ${res.status} for ${uri}`);
+    return (await res.json());
+}
+/**
+ * Read a token's metadata URI on-chain, resolve + fetch + parse it, and resolve
+ * the embedded image/animation URLs. Returns null if the URI read reverts (e.g.
+ * unminted). Throws if the metadata document itself can't be fetched/parsed.
+ */
+export async function fetchTokenMetadata(chain, token, tokenId, opts = {}) {
+    const gateway = opts.gateway ?? DEFAULT_GATEWAY;
+    const t = token;
+    let uri;
+    try {
+        if (opts.standard === "erc1155") {
+            const raw = (await chain.call(t, "uri(uint256)(string)", [tokenId]));
+            uri = raw?.replace(/\{id\}/g, erc1155IdHex(tokenId));
+        }
+        else {
+            uri = (await chain.call(t, "tokenURI(uint256)(string)", [tokenId]));
+        }
+    }
+    catch {
+        return null;
+    }
+    if (!uri)
+        return null;
+    const doc = await loadJson(resolveUri(uri, gateway));
+    const imageRaw = (doc.image ?? doc.image_url ?? doc.imageUrl);
+    const animationRaw = (doc.animation_url ?? doc.animationUrl);
+    return {
+        name: doc.name,
+        description: doc.description,
+        image: imageRaw ? resolveUri(imageRaw, gateway) : undefined,
+        imageRaw,
+        animationUrl: animationRaw ? resolveUri(animationRaw, gateway) : undefined,
+        attributes: doc.attributes ?? undefined,
+        raw: doc,
+    };
+}

package/dist/nft.test.d.ts

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

package/dist/nft.test.js

@@ -0,0 +1,44 @@
+import { describe, it, expect } from "vitest";
+import { resolveUri, fetchTokenMetadata } from "./nft.js";
+describe("resolveUri", () => {
+    it("maps ipfs:// (and ipfs://ipfs/) to the gateway, ar:// to arweave, passes http/data through", () => {
+        expect(resolveUri("ipfs://bafyCID/1.json")).toBe("https://ipfs.io/ipfs/bafyCID/1.json");
+        expect(resolveUri("ipfs://ipfs/bafyCID")).toBe("https://ipfs.io/ipfs/bafyCID");
+        expect(resolveUri("ipfs://CID", "https://x.mypinata.cloud/ipfs/")).toBe("https://x.mypinata.cloud/ipfs/CID");
+        expect(resolveUri("ar://TXID")).toBe("https://arweave.net/TXID");
+        expect(resolveUri("https://example.com/1.json")).toBe("https://example.com/1.json");
+        expect(resolveUri("data:application/json,{}")).toBe("data:application/json,{}");
+    });
+});
+// A fake Chain that returns a canned tokenURI/uri string — no network, no RPC.
+function fakeChain(uri) {
+    return { call: async () => uri };
+}
+describe("fetchTokenMetadata", () => {
+    it("reads tokenURI, parses a base64 data: doc, and resolves the ipfs image", async () => {
+        const doc = { name: "Glyph #7", description: "x", image: "ipfs://imgCID/7.png", attributes: [{ trait_type: "Eyes", value: "Laser" }] };
+        const dataUri = "data:application/json;base64," + btoa(JSON.stringify(doc));
+        const m = await fetchTokenMetadata(fakeChain(dataUri), "0xabc", 7n);
+        expect(m?.name).toBe("Glyph #7");
+        expect(m?.image).toBe("https://ipfs.io/ipfs/imgCID/7.png");
+        expect(m?.imageRaw).toBe("ipfs://imgCID/7.png");
+        expect(m?.attributes?.[0]).toEqual({ trait_type: "Eyes", value: "Laser" });
+    });
+    it("parses a plain (url-encoded) data: doc and image_url fallback", async () => {
+        const doc = { name: "B", image_url: "https://cdn/x.png" };
+        const dataUri = "data:application/json," + encodeURIComponent(JSON.stringify(doc));
+        const m = await fetchTokenMetadata(fakeChain(dataUri), "0xabc", 1n);
+        expect(m?.image).toBe("https://cdn/x.png");
+    });
+    it("substitutes {id} (64-hex padded) for ERC-1155 uris before fetching", async () => {
+        // uri(id) returns a template with {id}; we replace it across the whole URI. Here the
+        // literal {id} sits in a plain data: body so the substituted value is observable.
+        const uri = 'data:application/json,{"name":"id-{id}"}';
+        const m = await fetchTokenMetadata(fakeChain(uri), "0xabc", 1n, { standard: "erc1155" });
+        expect(m?.name).toBe("id-0000000000000000000000000000000000000000000000000000000000000001");
+    });
+    it("returns null when the URI read reverts", async () => {
+        const reverting = { call: async () => { throw new Error("revert"); } };
+        expect(await fetchTokenMetadata(reverting, "0xabc", 1n)).toBeNull();
+    });
+});

package/dist/polymarket.d.ts

@@ -38,6 +38,15 @@ export interface PolymarketOptions {
      * reads always work).
      */
     allowLegacyV1?: boolean;
+    /**
+     * Polymarket Builder/Relayer API key that authorizes V2 deposit-wallet deployment
+     * + order placement. On Livo this is a PLATFORM credential (one Livo-held builder
+     * key serving every project), injected as env.POLYMARKET_BUILDER_API_KEY — projects
+     * never set it. Default: env.POLYMARKET_BUILDER_API_KEY. (V2 order placement via
+     * @polymarket/client is not wired yet even when present — see
+     * docs/POLYMARKET-V2-IMPLEMENTATION.md.)
+     */
+    builderApiKey?: string;
     /** 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". */
@@ -85,6 +94,7 @@ export declare class Polymarket {
     private readonly host;
     private readonly privateKey?;
     private readonly legacyV1;
+    private readonly builderApiKey?;
     private readonly contracts;
     private creds?;
     constructor(env: MinimalEnv | undefined, options?: PolymarketOptions);
@@ -122,6 +132,8 @@ export declare class Polymarket {
     positions(user?: string): Promise<unknown>;
     /** Ensure API credentials exist (derive existing, else create). Cached on the instance. */
     ensureCreds(): Promise<PolymarketCreds>;
+    /** True once Livo's platform Polymarket builder key is configured (env.POLYMARKET_BUILDER_API_KEY). */
+    get builderConfigured(): boolean;
     private assertTradingEnabled;
     private deriveOrCreateApiKey;
     /** Build, sign, and submit an order. Returns the CLOB response JSON. */

package/dist/polymarket.js

@@ -171,12 +171,16 @@ export class Polymarket {
     host;
     privateKey;
     legacyV1;
+    builderApiKey;
     contracts;
     creds;
     constructor(env, options = {}) {
         this.chainId = options.chainId ?? Number(env?.POLYMARKET_CHAIN_ID ?? 137);
         this.host = options.host ?? env?.POLYMARKET_CLOB_HOST ?? CLOB_HOST;
         this.legacyV1 = options.allowLegacyV1 ?? (env?.POLYMARKET_ALLOW_LEGACY_V1 === "1" || env?.POLYMARKET_ALLOW_LEGACY_V1 === "true");
+        // Platform-injected Livo builder credential (one key for all projects). Read-only here;
+        // V2 order placement via @polymarket/client isn't wired yet, so this is detection only.
+        this.builderApiKey = options.builderApiKey ?? env?.POLYMARKET_BUILDER_API_KEY;
         this.contracts = this.legacyV1 ? CONTRACTS_V1 : CONTRACTS_V2;
         const keySecret = options.privateKeySecret ?? "POLYMARKET_PRIVATE_KEY";
         this.privateKey =
@@ -306,15 +310,24 @@ export class Polymarket {
     // All trading + L2-auth methods route through ensureCreds, so this one guard covers
     // them. Data reads never call it. V2 order signing isn't correctly implemented yet
     // (see the header note) — gate it rather than submit invalid orders.
+    /** True once Livo's platform Polymarket builder key is configured (env.POLYMARKET_BUILDER_API_KEY). */
+    get builderConfigured() {
+        return Boolean(this.builderApiKey);
+    }
     assertTradingEnabled() {
         if (this.legacyV1)
             return; // deprecated V1 path (testnet/legacy)
-        throw new Error("Polymarket V2 trading isn't available through this helper. Verified live: V2 (Apr 2026) REQUIRES " +
-            "the deposit-wallet flow (a plain EOA maker is rejected: 'use the deposit wallet flow'), and deploying " +
-            "a deposit wallet needs a Polymarket BUILDER or RELAYER API key — a credential Polymarket issues to " +
-            "builders, not something derivable here. The path is to wrap the official @polymarket/client SDK with " +
-            "that key (see docs/POLYMARKET-V2-IMPLEMENTATION.md). Market-DATA reads work without any of this. " +
-            "{ allowLegacyV1: true } enables the deprecated V1 path on testnet only.");
+        // V2 trading needs BOTH (1) Livo's platform builder key and (2) the @polymarket/client
+        // wrap — which isn't wired yet. Message reflects which prerequisite is missing.
+        if (this.builderConfigured) {
+            throw new Error("Polymarket builder key is configured, but V2 order placement via @polymarket/client isn't wired up in " +
+                "this runtime yet (deposit-wallet deploy + EIP-1271 signing) — tracked in docs/POLYMARKET-V2-IMPLEMENTATION.md. " +
+                "Market-DATA reads work. { allowLegacyV1: true } enables the deprecated V1 path on testnet.");
+        }
+        throw new Error("Polymarket V2 trading needs Livo's platform builder key (env.POLYMARKET_BUILDER_API_KEY), which isn't " +
+            "configured. V2 (Apr 2026) requires the deposit-wallet flow — a plain EOA maker is rejected — and deploying " +
+            "a deposit wallet needs a Polymarket Builder/Relayer credential (one Livo-held key serves all projects; see " +
+            "docs/POLYMARKET-V2-IMPLEMENTATION.md). Market-DATA reads work without it. { allowLegacyV1: true } = V1 testnet.");
     }
     async deriveOrCreateApiKey() {
         // Try derive (deterministic) first; fall back to create.

package/dist/polymarket.test.js

@@ -68,6 +68,16 @@ describe("Polymarket V2 trading gate", () => {
         expect(new Polymarket({}).collateralToken).toBe("0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB");
         expect(new Polymarket({}, { allowLegacyV1: true }).collateralToken).toBeUndefined();
     });
+    it("detects the platform builder key and adjusts the gate message", async () => {
+        // No key configured → message points at the missing platform builder key.
+        const noKey = new Polymarket({ POLYMARKET_PRIVATE_KEY: PK });
+        expect(noKey.builderConfigured).toBe(false);
+        await expect(noKey.placeOrder({ tokenId: "1", side: "BUY", price: 0.5, size: 2, tickSize: "0.01", negRisk: false })).rejects.toThrow(/platform builder key/);
+        // Platform key injected (env) → detected; gate now points at the un-wired SDK path.
+        const withKey = new Polymarket({ POLYMARKET_PRIVATE_KEY: PK, POLYMARKET_BUILDER_API_KEY: "blder_test" });
+        expect(withKey.builderConfigured).toBe(true);
+        await expect(withKey.placeOrder({ tokenId: "1", side: "BUY", price: 0.5, size: 2, tickSize: "0.01", negRisk: false })).rejects.toThrow(/isn't wired up/);
+    });
 });
 describe("Polymarket data helpers", () => {
     it("resolveMarket maps Gamma clobTokenIds + outcomes to tradable tokens", async () => {

package/dist/ratelimit.d.ts

@@ -0,0 +1,19 @@
+export interface KvLike {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+}
+export interface RateLimitOptions {
+    /** Max requests allowed in the window. */
+    limit: number;
+    /** Window length in seconds. */
+    windowSeconds: number;
+    /** Key prefix (default "rl"). */
+    prefix?: string;
+}
+export interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+}
+export declare function rateLimit(kv: KvLike, key: string, opts: RateLimitOptions): Promise<RateLimitResult>;

package/dist/ratelimit.js

@@ -0,0 +1,11 @@
+// A KV-backed fixed-window rate limiter for bots / api Workers (e.g. per wallet or
+// per Telegram user). Pass the project's env.KV.
+// Increment the counter for `key`; allow until `limit` is reached within the window.
+export async function rateLimit(kv, key, opts) {
+    const k = `${opts.prefix ?? "rl"}:${key}`;
+    const current = Number((await kv.get(k)) ?? "0");
+    if (current >= opts.limit)
+        return { allowed: false, remaining: 0 };
+    await kv.put(k, String(current + 1), { expirationTtl: opts.windowSeconds });
+    return { allowed: true, remaining: Math.max(0, opts.limit - current - 1) };
+}

package/dist/reads.d.ts

@@ -0,0 +1,12 @@
+import type { Chain } from "./chain.js";
+export interface TokenMetadata {
+    name?: string;
+    symbol?: string;
+    decimals?: number;
+}
+/** ERC-20 name / symbol / decimals (each best-effort — missing fields stay undefined). */
+export declare function tokenMetadata(chain: Chain, token: string): Promise<TokenMetadata>;
+/** Owner of an ERC-721 token id (or null if the read reverts, e.g. unminted). */
+export declare function ownerOf(chain: Chain, token: string, tokenId: bigint): Promise<string | null>;
+/** ERC-721 tokenURI for a token id (or null on revert). */
+export declare function tokenURI(chain: Chain, token: string, tokenId: bigint): Promise<string | null>;