@livo-build/runtime 0.2.4 → 0.2.6

package/dist/polymarket.js

@@ -0,0 +1,508 @@
+// Polymarket — prediction-market data + order placement on the CLOB, native to
+// the runtime (no @polymarket/clob-client, no ethers). Reads (markets, prices,
+// books) hit the public Gamma + CLOB REST APIs with no auth, so they work in
+// bots AND frontends. Trading signs orders with the runtime's EIP-712 signer and
+// authenticates with Polymarket's two-layer scheme:
+//   L1 — an EIP-712 wallet signature, once, to create/derive API credentials.
+//   L2 — an HMAC-SHA256 (Web Crypto) over each request, using the L1-derived secret.
+//
+// The order struct, contract addresses, amount-rounding, and header construction
+// are ported faithfully from the official @polymarket/clob-client (v5) so signed
+// orders match what their API expects.
+//
+//   import { Polymarket } from "@livo-build/runtime";
+//   const pm = new Polymarket(env);
+//   const markets = await pm.gammaMarkets({ active: true, limit: 5 }); // no key
+//   await pm.placeOrder({ tokenId, side: "BUY", price: 0.55, size: 10 }); // needs a key + USDC
+//
+// Trading needs POLYMARKET_PRIVATE_KEY (falls back to the bot's RELAYER_PRIVATE_KEY)
+// for an EOA whose USDC + allowances live on Polygon. Proxy/Gnosis-Safe funders
+// (signatureType 1/2) are supported via options but you must pass the funder address.
+//
+// CLOB V2 (Apr 28 2026): Polymarket migrated to CTF Exchange V2 + pUSD collateral.
+// ⚠️ V2 ORDER SIGNING IS NOT YET CORRECTLY IMPLEMENTED HERE, so trading is GATED OFF
+// (data reads work). Inspecting the official @polymarket/client showed V2 differs from
+// V1 in ways we could not verify from this build env (Polymarket is network-blocked
+// here): the Order struct changed (added timestamp/metadata(bytes32)/builder(bytes32);
+// removed taker/expiration/nonce/feeRateBps), the order-domain `version` is "2"/"3"
+// (not "1"), and deposit/Safe funders use ERC-7739 (TypedDataSign) + CREATE2 deposit
+// wallets. The correct path is to WRAP the official @polymarket/client SDK (it handles
+// all of this) — see docs/POLYMARKET-V2-IMPLEMENTATION.md. The V2 contract addresses +
+// the corrected struct are captured below for that work. { allowLegacyV1: true } enables
+// the deprecated V1 path (testnet/legacy only — rejected on production).
+import { signTypedData } from "./eip712.js";
+import { privateKeyToAddress } from "./tx.js";
+const CLOB_HOST = "https://clob.polymarket.com";
+const GAMMA_HOST = "https://gamma-api.polymarket.com";
+const DATA_HOST = "https://data-api.polymarket.com";
+// Per-chain CTF Exchange contracts (the order EIP-712 verifyingContract).
+//
+// V2 (default): the CLOB V2 exchanges from the official @polymarket/client config
+// (Polygon mainnet). Collateral is pUSD (0xC011…2DFB). V1 (legacy, allowLegacyV1):
+// the deprecated CTF Exchange the old clob-client used — no longer accepted on
+// production, kept only for legacy/testnet experiments.
+const CONTRACTS_V2 = {
+    137: { exchange: "0xE111180000d2663C0091e4f400237545B87B996B", negRiskExchange: "0xe2222d279d744050d28e00520010520000310F59" },
+};
+const CONTRACTS_V1 = {
+    137: { exchange: "0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E", negRiskExchange: "0xC5d563A36AE78145C45a50134d48A1215220f80a" },
+    80002: { exchange: "0xdFE02Eb6733538f8Ea35D585af8DE5958AD99E40", negRiskExchange: "0xC5d563A36AE78145C45a50134d48A1215220f80a" },
+};
+// pUSD — the V2 collateral on Polygon (6 decimals, 1:1 USDC). Fund your signer with
+// this (or wrap USDC.e→pUSD via the collateral adapter) + approve the exchange.
+const PUSD_COLLATERAL = "0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB";
+const COLLATERAL_DECIMALS = 6;
+const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+const L1_MESSAGE = "This message attests that I control the given wallet";
+// EIP-712 Order struct (Polymarket CTF Exchange v1).
+const ORDER_TYPES = {
+    Order: [
+        { name: "salt", type: "uint256" },
+        { name: "maker", type: "address" },
+        { name: "signer", type: "address" },
+        { name: "taker", type: "address" },
+        { name: "tokenId", type: "uint256" },
+        { name: "makerAmount", type: "uint256" },
+        { name: "takerAmount", type: "uint256" },
+        { name: "expiration", type: "uint256" },
+        { name: "nonce", type: "uint256" },
+        { name: "feeRateBps", type: "uint256" },
+        { name: "side", type: "uint8" },
+        { name: "signatureType", type: "uint8" },
+    ],
+};
+// Tick-size → decimal-place config, ported from clob-client's ROUNDING_CONFIG.
+const ROUNDING = {
+    "0.1": { price: 1, size: 2, amount: 3 },
+    "0.01": { price: 2, size: 2, amount: 4 },
+    "0.001": { price: 3, size: 2, amount: 5 },
+    "0.0001": { price: 4, size: 2, amount: 6 },
+};
+// ---- rounding helpers (ported from clob-client utilities.ts) ----
+function decimalPlaces(num) {
+    if (Number.isInteger(num))
+        return 0;
+    const arr = num.toString().split(".");
+    return arr.length <= 1 ? 0 : arr[1].length;
+}
+function roundNormal(num, d) {
+    if (decimalPlaces(num) <= d)
+        return num;
+    return Math.round((num + Number.EPSILON) * 10 ** d) / 10 ** d;
+}
+function roundDown(num, d) {
+    if (decimalPlaces(num) <= d)
+        return num;
+    return Math.floor(num * 10 ** d) / 10 ** d;
+}
+function roundUp(num, d) {
+    if (decimalPlaces(num) <= d)
+        return num;
+    return Math.ceil(num * 10 ** d) / 10 ** d;
+}
+// parseUnits(value, 6) without a bignum lib — value is a positive decimal string/number.
+function parseUnits6(value) {
+    const [whole, frac = ""] = value.toString().split(".");
+    const fracPadded = (frac + "000000").slice(0, COLLATERAL_DECIMALS);
+    const combined = `${whole}${fracPadded}`.replace(/^0+(?=\d)/, "");
+    return combined === "" ? "0" : combined;
+}
+// getOrderRawAmounts, ported from clob-client order-builder/helpers.ts.
+function rawAmounts(side, size, price, cfg) {
+    const rawPrice = roundNormal(price, cfg.price);
+    if (side === "BUY") {
+        const rawTakerAmt = roundDown(size, cfg.size);
+        let rawMakerAmt = rawTakerAmt * rawPrice;
+        if (decimalPlaces(rawMakerAmt) > cfg.amount) {
+            rawMakerAmt = roundUp(rawMakerAmt, cfg.amount + 4);
+            if (decimalPlaces(rawMakerAmt) > cfg.amount)
+                rawMakerAmt = roundDown(rawMakerAmt, cfg.amount);
+        }
+        return { sideInt: 0, makerAmount: parseUnits6(rawMakerAmt), takerAmount: parseUnits6(rawTakerAmt) };
+    }
+    const rawMakerAmt = roundDown(size, cfg.size);
+    let rawTakerAmt = rawMakerAmt * rawPrice;
+    if (decimalPlaces(rawTakerAmt) > cfg.amount) {
+        rawTakerAmt = roundUp(rawTakerAmt, cfg.amount + 4);
+        if (decimalPlaces(rawTakerAmt) > cfg.amount)
+            rawTakerAmt = roundDown(rawTakerAmt, cfg.amount);
+    }
+    return { sideInt: 1, makerAmount: parseUnits6(rawMakerAmt), takerAmount: parseUnits6(rawTakerAmt) };
+}
+function randomSalt() {
+    // Mirrors clob-client's generateOrderSalt: a positive integer that survives a
+    // JSON round-trip (the POST body sends salt as a JS number).
+    return Math.floor(Math.random() * 9_000_000_000_000) + 1;
+}
+function base64ToBytes(b64) {
+    const clean = b64.replace(/-/g, "+").replace(/_/g, "/").replace(/[^A-Za-z0-9+/=]/g, "");
+    const bin = atob(clean);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+function bytesToBase64(bytes) {
+    let bin = "";
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin);
+}
+// Gamma returns clobTokenIds/outcomes as JSON-encoded strings (e.g. '["123","456"]').
+function safeJsonArray(v) {
+    if (Array.isArray(v))
+        return v;
+    if (typeof v === "string") {
+        try {
+            const p = JSON.parse(v);
+            return Array.isArray(p) ? p : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    return [];
+}
+export class Polymarket {
+    /** Polygon chain id this client signs for. */
+    chainId;
+    /** The signer's address (null when no key is configured → read-only). */
+    address;
+    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 =
+            options.privateKey ?? env?.[keySecret] ?? env?.RELAYER_PRIVATE_KEY;
+        this.address = this.privateKey ? privateKeyToAddress(this.privateKey) : null;
+        this.creds =
+            options.creds ??
+                (env?.POLYMARKET_API_KEY && env?.POLYMARKET_SECRET && env?.POLYMARKET_PASSPHRASE
+                    ? {
+                        key: env.POLYMARKET_API_KEY,
+                        secret: env.POLYMARKET_SECRET,
+                        passphrase: env.POLYMARKET_PASSPHRASE,
+                    }
+                    : undefined);
+    }
+    // ---- public market data (no key) ----
+    /** Gamma markets — the rich, searchable market catalog. Pass query params (e.g. { active: true, limit: 10 }). */
+    async gammaMarkets(query = {}) {
+        const qs = new URLSearchParams(Object.entries(query).map(([k, v]) => [k, String(v)])).toString();
+        return this.getJson(`${GAMMA_HOST}/markets${qs ? `?${qs}` : ""}`);
+    }
+    /** A single Gamma market by id. */
+    async gammaMarket(id) {
+        return this.getJson(`${GAMMA_HOST}/markets/${id}`);
+    }
+    /** CLOB markets (paginated; pass a cursor to page). */
+    async markets(cursor = "") {
+        return this.getJson(`${this.host}/markets${cursor ? `?next_cursor=${encodeURIComponent(cursor)}` : ""}`);
+    }
+    /** Order book for an outcome token. */
+    async book(tokenId) {
+        return this.getJson(`${this.host}/book?token_id=${tokenId}`);
+    }
+    /** Best price for a token on a side. */
+    async price(tokenId, side) {
+        const j = (await this.getJson(`${this.host}/price?token_id=${tokenId}&side=${side.toLowerCase()}`));
+        return Number(j.price ?? 0);
+    }
+    /** Midpoint price for a token. */
+    async midpoint(tokenId) {
+        const j = (await this.getJson(`${this.host}/midpoint?token_id=${tokenId}`));
+        return Number(j.mid ?? 0);
+    }
+    /** Minimum tick size for a token (e.g. "0.01"). */
+    async tickSize(tokenId) {
+        const j = (await this.getJson(`${this.host}/tick-size?token_id=${tokenId}`));
+        return String(j.minimum_tick_size ?? "0.01");
+    }
+    /** Whether a token's market is a neg-risk market. */
+    async negRisk(tokenId) {
+        const j = (await this.getJson(`${this.host}/neg-risk?token_id=${tokenId}`));
+        return Boolean(j.neg_risk);
+    }
+    /** Last traded price for a token. */
+    async lastTradePrice(tokenId) {
+        const j = (await this.getJson(`${this.host}/last-trade-price?token_id=${tokenId}`));
+        return Number(j.price ?? 0);
+    }
+    /** Bid/ask spread for a token. */
+    async spread(tokenId) {
+        return this.getJson(`${this.host}/spread?token_id=${tokenId}`);
+    }
+    /** Historical price points for charting a token. */
+    async priceHistory(tokenId, opts = {}) {
+        const p = new URLSearchParams({ market: tokenId });
+        if (opts.startTs && opts.endTs) {
+            p.set("startTs", String(opts.startTs));
+            p.set("endTs", String(opts.endTs));
+        }
+        else {
+            p.set("interval", opts.interval ?? "1d");
+        }
+        if (opts.fidelity)
+            p.set("fidelity", String(opts.fidelity));
+        return this.getJson(`${this.host}/prices-history?${p.toString()}`);
+    }
+    /**
+     * 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},…].
+     */
+    async resolveMarket(slugOrId) {
+        let market;
+        if (/^0x[0-9a-fA-F]+$/.test(slugOrId)) {
+            const arr = (await this.getJson(`${GAMMA_HOST}/markets?condition_ids=${slugOrId}`));
+            market = Array.isArray(arr) ? arr[0] : undefined;
+        }
+        else if (/^\d+$/.test(slugOrId)) {
+            market = (await this.getJson(`${GAMMA_HOST}/markets/${slugOrId}`));
+        }
+        else {
+            const arr = (await this.getJson(`${GAMMA_HOST}/markets?slug=${encodeURIComponent(slugOrId)}`));
+            market = Array.isArray(arr) ? arr[0] : undefined;
+        }
+        if (!market)
+            return null;
+        const ids = safeJsonArray(market.clobTokenIds);
+        const outcomes = safeJsonArray(market.outcomes);
+        return {
+            question: String(market.question ?? ""),
+            conditionId: market.conditionId,
+            slug: market.slug,
+            negRisk: Boolean(market.negRisk),
+            tokens: ids.map((id, i) => ({ outcome: String(outcomes[i] ?? `#${i}`), tokenId: String(id) })),
+        };
+    }
+    /** The collateral token address to fund/approve (pUSD on V2; USDC.e on legacy V1). */
+    get collateralToken() {
+        return this.legacyV1 ? undefined : PUSD_COLLATERAL;
+    }
+    /** A user's open positions (holdings) from the public data API (default: the signer). */
+    async positions(user) {
+        const who = user ?? this.address;
+        if (!who)
+            throw new Error("Polymarket: pass a user address, or configure a key.");
+        return this.getJson(`${DATA_HOST}/positions?user=${who}`);
+    }
+    // ---- auth ----
+    /** Ensure API credentials exist (derive existing, else create). Cached on the instance. */
+    async ensureCreds() {
+        this.assertTradingEnabled();
+        if (this.creds)
+            return this.creds;
+        this.creds = await this.deriveOrCreateApiKey();
+        return this.creds;
+    }
+    // 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)
+        // 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.
+        for (const [path, method] of [
+            ["/auth/derive-api-key", "GET"],
+            ["/auth/api-key", "POST"],
+        ]) {
+            try {
+                const headers = await this.l1Headers(0);
+                const res = await fetch(`${this.host}${path}`, { method, headers });
+                if (!res.ok)
+                    continue;
+                const j = (await res.json());
+                if (j.apiKey && j.secret && j.passphrase)
+                    return { key: j.apiKey, secret: j.secret, passphrase: j.passphrase };
+            }
+            catch {
+                /* try the next */
+            }
+        }
+        throw new Error("Polymarket: could not derive or create API credentials (is the signer funded/registered?).");
+    }
+    // ---- trading ----
+    /** Build, sign, and submit an order. Returns the CLOB response JSON. */
+    async placeOrder(params) {
+        const signer = this.requireSigner();
+        const creds = await this.ensureCreds();
+        const tickSize = params.tickSize ?? (await this.tickSize(params.tokenId));
+        const cfg = ROUNDING[tickSize];
+        if (!cfg)
+            throw new Error(`Polymarket: unsupported tick size "${tickSize}"`);
+        const negRisk = params.negRisk ?? (await this.negRisk(params.tokenId));
+        const contracts = this.contracts[this.chainId];
+        if (!contracts) {
+            throw new Error(`Polymarket: no ${this.legacyV1 ? "V1" : "V2"} exchange contracts for chainId ${this.chainId}` +
+                (this.legacyV1 ? "" : " (V2 is on Polygon mainnet 137; for testnet use { allowLegacyV1: true } on Amoy)"));
+        }
+        const verifyingContract = negRisk ? contracts.negRiskExchange : contracts.exchange;
+        const { sideInt, makerAmount, takerAmount } = rawAmounts(params.side, params.size, params.price, cfg);
+        const signatureType = params.signatureType ?? 0;
+        const maker = params.funder ?? signer;
+        const salt = randomSalt();
+        const message = {
+            salt: String(salt),
+            maker,
+            signer,
+            taker: ZERO_ADDRESS,
+            tokenId: params.tokenId,
+            makerAmount,
+            takerAmount,
+            expiration: String(params.expiration ?? 0),
+            nonce: String(params.nonce ?? 0),
+            feeRateBps: String(params.feeRateBps ?? 0),
+            side: sideInt,
+            signatureType,
+        };
+        const signature = signTypedData({
+            domain: { name: "Polymarket CTF Exchange", version: "1", chainId: this.chainId, verifyingContract },
+            types: ORDER_TYPES,
+            primaryType: "Order",
+            message,
+            privateKey: this.privateKey,
+        });
+        const payload = {
+            order: {
+                salt,
+                maker,
+                signer,
+                taker: ZERO_ADDRESS,
+                tokenId: params.tokenId,
+                makerAmount,
+                takerAmount,
+                side: params.side,
+                expiration: message.expiration,
+                nonce: message.nonce,
+                feeRateBps: message.feeRateBps,
+                signatureType,
+                signature,
+            },
+            owner: creds.key,
+            orderType: params.orderType ?? "GTC",
+        };
+        const body = JSON.stringify(payload);
+        const headers = await this.l2Headers("POST", "/order", body);
+        const res = await fetch(`${this.host}/order`, {
+            method: "POST",
+            headers: { ...headers, "content-type": "application/json" },
+            body,
+        });
+        return res.json();
+    }
+    /** Cancel one order by id. */
+    async cancelOrder(orderId) {
+        await this.ensureCreds();
+        const body = JSON.stringify({ orderID: orderId });
+        const headers = await this.l2Headers("DELETE", "/order", body);
+        const res = await fetch(`${this.host}/order`, {
+            method: "DELETE",
+            headers: { ...headers, "content-type": "application/json" },
+            body,
+        });
+        return res.json();
+    }
+    /** Cancel all of the signer's open orders. */
+    async cancelAll() {
+        await this.ensureCreds();
+        const headers = await this.l2Headers("DELETE", "/cancel-all");
+        const res = await fetch(`${this.host}/cancel-all`, { method: "DELETE", headers });
+        return res.json();
+    }
+    /** The signer's open orders (L2-authed). */
+    async openOrders() {
+        await this.ensureCreds();
+        const headers = await this.l2Headers("GET", "/data/orders");
+        const res = await fetch(`${this.host}/data/orders`, { method: "GET", headers });
+        return res.json();
+    }
+    /**
+     * 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.
+     */
+    async balances(tokenId) {
+        await this.ensureCreds();
+        const headers = await this.l2Headers("GET", "/balance-allowance");
+        const qs = tokenId ? `?asset_type=CONDITIONAL&token_id=${tokenId}` : "?asset_type=COLLATERAL";
+        const res = await fetch(`${this.host}/balance-allowance${qs}`, { method: "GET", headers });
+        return res.json();
+    }
+    // ---- header construction ----
+    async l1Headers(nonce) {
+        const signer = this.requireSigner();
+        const ts = Math.floor(Date.now() / 1000);
+        const signature = signTypedData({
+            domain: { name: "ClobAuthDomain", version: "1", chainId: this.chainId },
+            types: {
+                ClobAuth: [
+                    { name: "address", type: "address" },
+                    { name: "timestamp", type: "string" },
+                    { name: "nonce", type: "uint256" },
+                    { name: "message", type: "string" },
+                ],
+            },
+            primaryType: "ClobAuth",
+            message: { address: signer, timestamp: String(ts), nonce, message: L1_MESSAGE },
+            privateKey: this.privateKey,
+        });
+        return { POLY_ADDRESS: signer, POLY_SIGNATURE: signature, POLY_TIMESTAMP: String(ts), POLY_NONCE: String(nonce) };
+    }
+    async l2Headers(method, path, body) {
+        const signer = this.requireSigner();
+        const creds = await this.ensureCreds();
+        const ts = Math.floor(Date.now() / 1000);
+        const message = `${ts}${method}${path}${body ?? ""}`;
+        const key = await crypto.subtle.importKey("raw", base64ToBytes(creds.secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+        const sigBuf = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(message));
+        const sig = bytesToBase64(new Uint8Array(sigBuf)).replace(/\+/g, "-").replace(/\//g, "_");
+        return {
+            POLY_ADDRESS: signer,
+            POLY_SIGNATURE: sig,
+            POLY_TIMESTAMP: String(ts),
+            POLY_API_KEY: creds.key,
+            POLY_PASSPHRASE: creds.passphrase,
+        };
+    }
+    requireSigner() {
+        if (!this.address || !this.privateKey) {
+            throw new Error("Polymarket: trading needs a signing key — set the POLYMARKET_PRIVATE_KEY secret (or rely on the bot's RELAYER_PRIVATE_KEY).");
+        }
+        return this.address;
+    }
+    async getJson(url) {
+        const res = await fetch(url, { headers: { accept: "application/json" } });
+        if (!res.ok)
+            throw new Error(`Polymarket: ${res.status} ${res.statusText} for ${url}`);
+        return res.json();
+    }
+}

package/dist/polymarket.test.d.ts

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

package/dist/polymarket.test.js

@@ -0,0 +1,121 @@
+// Polymarket order math + auth header construction must match the official
+// @polymarket/clob-client. The maker/taker amounts below are GOLDEN values
+// produced by running clob-client's getOrderRawAmounts + viem parseUnits(…,6)
+// (see the helper in the PR notes) — if our ported rounding drifts, orders get
+// rejected on-chain, so we pin them exactly.
+import { describe, expect, it, vi } from "vitest";
+import { Polymarket } from "./polymarket.js";
+// A funded test EOA (well-known hardhat key #1). Never holds real funds.
+const PK = "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d";
+// Reach the private rawAmounts via a placeOrder dry-run: stub fetch and capture
+// the POST /order body.
+function clientWithCapturedOrder() {
+    const calls = [];
+    const fetchMock = vi.fn(async (url, init = {}) => {
+        calls.push({ url, init });
+        if (url.endsWith("/auth/derive-api-key") || url.endsWith("/auth/api-key")) {
+            return new Response(JSON.stringify({ apiKey: "k", secret: btoa("topsecret"), passphrase: "p" }), { status: 200 });
+        }
+        if (url.includes("/order"))
+            return new Response(JSON.stringify({ success: true, orderID: "0xabc" }), { status: 200 });
+        return new Response("{}", { status: 200 });
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    // allowLegacyV1: exercise the (V1) order-signing math/headers directly. V2 signing
+    // isn't implemented yet (gated), so the amount/HMAC unit tests run on the V1 path —
+    // the rounding + HMAC are identical across versions.
+    return { pm: new Polymarket({ POLYMARKET_PRIVATE_KEY: PK }, { allowLegacyV1: true }), calls };
+}
+const GOLDEN = [
+    { side: "BUY", size: 10, price: 0.55, tickSize: "0.01", makerAmount: "5500000", takerAmount: "10000000" },
+    { side: "SELL", size: 10, price: 0.55, tickSize: "0.01", makerAmount: "10000000", takerAmount: "5500000" },
+    { side: "BUY", size: 33.333, price: 0.123, tickSize: "0.001", makerAmount: "4099590", takerAmount: "33330000" },
+    { side: "SELL", size: 7.5, price: 0.4, tickSize: "0.1", makerAmount: "7500000", takerAmount: "3000000" },
+    { side: "BUY", size: 100, price: 0.99, tickSize: "0.0001", makerAmount: "99000000", takerAmount: "100000000" },
+];
+describe("Polymarket order amounts match clob-client golden values", () => {
+    for (const g of GOLDEN) {
+        it(`${g.side} ${g.size} @ ${g.price} (tick ${g.tickSize})`, async () => {
+            const { pm, calls } = clientWithCapturedOrder();
+            await pm.placeOrder({
+                tokenId: "123456789",
+                side: g.side,
+                price: g.price,
+                size: g.size,
+                tickSize: g.tickSize,
+                negRisk: false,
+            });
+            const orderCall = calls.find((c) => c.url.endsWith("/order") && c.init.method === "POST");
+            expect(orderCall).toBeTruthy();
+            const body = JSON.parse(orderCall.init.body);
+            expect(body.order.makerAmount).toBe(g.makerAmount);
+            expect(body.order.takerAmount).toBe(g.takerAmount);
+            expect(body.order.side).toBe(g.side);
+            expect(body.order.signature).toMatch(/^0x[0-9a-f]{130}$/);
+            expect(body.owner).toBe("k");
+            vi.unstubAllGlobals();
+        });
+    }
+});
+describe("Polymarket V2 trading gate", () => {
+    it("placeOrder throws (V2 not implemented) unless allowLegacyV1", async () => {
+        vi.stubGlobal("fetch", vi.fn(async () => new Response("{}", { status: 200 })));
+        const pm = new Polymarket({ POLYMARKET_PRIVATE_KEY: PK }); // V2 default
+        await expect(pm.placeOrder({ tokenId: "1", side: "BUY", price: 0.5, size: 2, tickSize: "0.01", negRisk: false })).rejects.toThrow(/V2/);
+        vi.unstubAllGlobals();
+    });
+    it("exposes pUSD collateral on V2, none on legacy V1", () => {
+        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 () => {
+        const market = {
+            question: "Will it rain tomorrow?",
+            conditionId: "0xabc",
+            slug: "will-it-rain",
+            negRisk: false,
+            clobTokenIds: JSON.stringify(["111", "222"]),
+            outcomes: JSON.stringify(["Yes", "No"]),
+        };
+        vi.stubGlobal("fetch", vi.fn(async () => new Response(JSON.stringify([market]), { status: 200 })));
+        const pm = new Polymarket({});
+        const r = await pm.resolveMarket("will-it-rain");
+        expect(r?.question).toBe("Will it rain tomorrow?");
+        expect(r?.tokens).toEqual([
+            { outcome: "Yes", tokenId: "111" },
+            { outcome: "No", tokenId: "222" },
+        ]);
+        vi.unstubAllGlobals();
+    });
+    it("lastTradePrice parses the price as a number", async () => {
+        vi.stubGlobal("fetch", vi.fn(async () => new Response(JSON.stringify({ price: "0.42" }), { status: 200 })));
+        const pm = new Polymarket({});
+        expect(await pm.lastTradePrice("111")).toBe(0.42);
+        vi.unstubAllGlobals();
+    });
+});
+describe("Polymarket L2 HMAC headers", () => {
+    it("signs timestamp+method+path+body with the base64 secret (url-safe)", async () => {
+        const { pm, calls } = clientWithCapturedOrder();
+        await pm.placeOrder({ tokenId: "1", side: "BUY", price: 0.5, size: 2, tickSize: "0.01", negRisk: false });
+        const orderCall = calls.find((c) => c.url.endsWith("/order") && c.init.method === "POST");
+        const h = orderCall.init.headers;
+        expect(h.POLY_API_KEY).toBe("k");
+        expect(h.POLY_PASSPHRASE).toBe("p");
+        expect(h.POLY_SIGNATURE).toBeTruthy();
+        expect(h.POLY_SIGNATURE).not.toMatch(/[+/]/); // url-safe base64
+        vi.unstubAllGlobals();
+    });
+});

package/dist/telegram.d.ts

@@ -67,5 +67,36 @@ export declare class Telegram {
         command: string;
         description: string;
     }>): Promise<void>;
+    private api;
+    /** Parse a `chat_join_request` update (a user asking to join a join-request chat). */
+    joinRequest(update: Record<string, unknown>): ChatJoinRequest | null;
+    /** Admit a pending join request. */
+    approveJoinRequest(chatId: number | string, userId: number): Promise<unknown>;
+    /** Reject a pending join request. */
+    declineJoinRequest(chatId: number | string, userId: number): Promise<unknown>;
+    /** Remove (ban) a member — the "boot" when they no longer qualify. */
+    banMember(chatId: number | string, userId: number, opts?: {
+        untilDate?: number;
+        revokeMessages?: boolean;
+    }): Promise<unknown>;
+    /** Lift a ban so a re-qualified user can rejoin (does NOT add them back). */
+    unbanMember(chatId: number | string, userId: number, opts?: {
+        onlyIfBanned?: boolean;
+    }): Promise<unknown>;
+    /** Create an invite link. With createsJoinRequest, joins need bot approval (the gate). */
+    createInviteLink(chatId: number | string, opts?: {
+        name?: string;
+        createsJoinRequest?: boolean;
+        expireDate?: number;
+    }): Promise<string>;
+    /** A member's status in a chat ("member" | "left" | "kicked" | "administrator" | "creator" | "restricted"). */
+    memberStatus(chatId: number | string, userId: number): Promise<string | null>;
+}
+export interface ChatJoinRequest {
+    chatId: number;
+    userId: number;
+    username?: string;
+    from: Record<string, unknown>;
+    raw: Record<string, unknown>;
 }
 export {};