@jinn-network/client 0.1.0 → 0.1.1-canary.4a6ed8b2

package/dist/types/prediction.js

@@ -0,0 +1,128 @@
+/**
+ * prediction.v0 — typed intent spec, submission manifest, verdict manifest.
+ *
+ * §4 of spec/2026-04-20-prediction-v0-pis-phase-1-design.md
+ */
+import { z } from 'zod';
+import { WindowSchema } from './desired-state.js';
+const HexStringSchema = z.string().regex(/^0x[0-9a-fA-F]*$/, 'must be a 0x-prefixed hex string');
+const SignatureSchema = z.object({
+    algo: z.literal('secp256k1'),
+    signer: HexStringSchema,
+    hash: HexStringSchema,
+    sig: HexStringSchema,
+});
+const IntentProvenanceSchema = z.object({
+    cid: z.string().min(1),
+    onchainCreationTx: HexStringSchema,
+    onchainCreationBlock: z.number().int(),
+    requestId: HexStringSchema,
+});
+const ParticipantSchema = z.object({
+    safeAddress: HexStringSchema,
+    agentEoa: HexStringSchema,
+});
+// ── Question kinds ────────────────────────────────────────────────────────────
+const ThresholdQuestionSchema = z.object({
+    kind: z.literal('threshold'),
+    operator: z.enum(['GT', 'GTE', 'LT', 'LTE']),
+    threshold: z.string(),
+    resolveTs: z.number().int(),
+});
+const RangeQuestionSchema = z.object({
+    kind: z.literal('range'),
+    lowerBound: z.string(),
+    upperBound: z.string(),
+    resolveTs: z.number().int(),
+});
+// ── Spec + eligibility + intent ────────────────────────────────────────────────
+export const PredictionV0SpecSchema = z.object({
+    kind: z.literal('prediction.v0'),
+    oracle: z.object({
+        venue: z.enum(['chainlink-base-sepolia', 'chainlink-base']),
+        feed: HexStringSchema,
+        feedDescription: z.string(),
+    }),
+    question: z.discriminatedUnion('kind', [ThresholdQuestionSchema, RangeQuestionSchema]),
+});
+export const PredictionV0EligibilitySchema = z.object({
+    maxSubmissionDelayMs: z.number().int().default(60_000),
+});
+export const PredictionV0IntentSchema = z
+    .object({
+    id: z.string(),
+    description: z.string().min(1),
+    window: WindowSchema,
+    spec: PredictionV0SpecSchema,
+    eligibility: PredictionV0EligibilitySchema.default({}),
+})
+    .refine(d => d.window.endTs - d.window.startTs === 3_600_000, {
+    message: 'window must be exactly 1h (endTs - startTs === 3_600_000 ms)',
+    path: ['window'],
+})
+    .refine(d => d.spec.question.resolveTs === d.window.endTs + 900_000, {
+    message: 'resolveTs must equal window.endTs + 900_000 ms (15min)',
+    path: ['spec', 'question', 'resolveTs'],
+});
+// ── Submission manifest ───────────────────────────────────────────────────────
+export const PredictionSubmissionManifestSchema = z.object({
+    schemaVersion: z.literal('prediction.v0.submission.v1'),
+    generatedAt: z.number().int(),
+    intent: IntentProvenanceSchema,
+    restorer: ParticipantSchema,
+    window: WindowSchema,
+    prediction: z.object({
+        probability: z.string().regex(/^(0(\.\d+)?|1(\.0+)?)$/, 'must be a decimal in [0,1]'),
+        submittedAt: z.number().int(),
+        modelId: z.string().min(1),
+    }),
+    oracleSnapshot: z
+        .object({
+        feed: HexStringSchema,
+        roundId: z.string(),
+        answer: z.string(),
+        updatedAt: z.number().int(),
+    })
+        .optional(),
+    rationale: z
+        .array(z.object({
+        ts: z.number().int(),
+        note: z.string(),
+    }))
+        .optional(),
+    signature: SignatureSchema,
+});
+// ── Verdict manifest ──────────────────────────────────────────────────────────
+const CheckSchema = z.object({
+    name: z.string(),
+    status: z.enum(['PASS', 'FAIL', 'SKIP']),
+    detail: z.union([z.string(), z.record(z.unknown())]).optional(),
+});
+export const PredictionVerdictManifestSchema = z.object({
+    schemaVersion: z.literal('prediction.v0.verdict.v1'),
+    generatedAt: z.number().int(),
+    intent: IntentProvenanceSchema,
+    evaluator: ParticipantSchema,
+    window: WindowSchema,
+    verdict: z.enum(['PASS', 'FAIL', 'REJECTED', 'INDETERMINATE']),
+    score: z.string(),
+    scoreBasis: z.literal('brier.v1'),
+    scoreVersion: z.string(),
+    oracleReading: z.object({
+        feed: HexStringSchema,
+        roundId: z.string(),
+        answer: z.string(),
+        updatedAt: z.number().int(),
+        nextRoundUpdatedAt: z.number().int().optional(),
+    }),
+    claimed: z.object({
+        probability: z.string(),
+        submittedAt: z.number().int(),
+        modelId: z.string(),
+        submissionManifestCid: z.string(),
+    }),
+    groundTruth: z.enum(['YES', 'NO']),
+    checks: z.array(CheckSchema),
+    signature: SignatureSchema,
+});
+//# sourceMappingURL=prediction.js.map

package/dist/types/prediction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prediction.js","sourceRoot":"","sources":["../../src/types/prediction.ts"],"names":[],"mappings":"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"}

package/dist/venues/chainlink/client.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Chainlink AggregatorV3 read client.
+ *
+ * §7 of spec/2026-04-20-prediction-v0-pis-phase-1-design.md
+ */
+import type { PublicClient } from 'viem';
+export declare const AGGREGATOR_V3_ABI: readonly [{
+    readonly name: "latestRoundData";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "roundId";
+        readonly type: "uint80";
+    }, {
+        readonly name: "answer";
+        readonly type: "int256";
+    }, {
+        readonly name: "startedAt";
+        readonly type: "uint256";
+    }, {
+        readonly name: "updatedAt";
+        readonly type: "uint256";
+    }, {
+        readonly name: "answeredInRound";
+        readonly type: "uint80";
+    }];
+}, {
+    readonly name: "getRoundData";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "_roundId";
+        readonly type: "uint80";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "roundId";
+        readonly type: "uint80";
+    }, {
+        readonly name: "answer";
+        readonly type: "int256";
+    }, {
+        readonly name: "startedAt";
+        readonly type: "uint256";
+    }, {
+        readonly name: "updatedAt";
+        readonly type: "uint256";
+    }, {
+        readonly name: "answeredInRound";
+        readonly type: "uint80";
+    }];
+}, {
+    readonly name: "decimals";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint8";
+    }];
+}, {
+    readonly name: "description";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "string";
+    }];
+}];
+export interface RoundReading {
+    roundId: bigint;
+    answer: bigint;
+    startedAt: number;
+    updatedAt: number;
+    answeredInRound: bigint;
+    decimals: number;
+}
+/** Scale a raw Chainlink int256 answer to a decimal string. */
+export declare function scaleToDecimal(answer: bigint, decimals: number): string;
+export declare function readChainlinkLatest(feed: `0x${string}`, publicClient: PublicClient): Promise<RoundReading>;
+export declare function readChainlinkRound(feed: `0x${string}`, roundId: bigint, publicClient: PublicClient, decimals: number): Promise<RoundReading>;
+export interface SpanningResult {
+    /** Round R with updatedAt ≤ resolveTs. */
+    round: RoundReading;
+    /** Round R+1 with updatedAt > resolveTs. null if no newer round exists yet. */
+    nextRound: RoundReading | null;
+    /** True iff nextRound exists — then the spanning property is satisfied. */
+    spanning: boolean;
+}
+/**
+ * Find the Chainlink round that "spans" resolveTs: round R where
+ * R.updatedAt ≤ resolveTs < (R+1).updatedAt.
+ *
+ * If the latest round's updatedAt ≤ resolveTs (i.e. no newer round yet),
+ * returns { round: latest, nextRound: null, spanning: false }. Caller should
+ * retry later (availability check will mark SKIP → INDETERMINATE verdict).
+ */
+export declare function oraclePriceAtResolveTs(feed: `0x${string}`, resolveTs: number, publicClient: PublicClient): Promise<SpanningResult>;

package/dist/venues/chainlink/client.js

@@ -0,0 +1,130 @@
+export const AGGREGATOR_V3_ABI = [
+    {
+        name: 'latestRoundData',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [],
+        outputs: [
+            { name: 'roundId', type: 'uint80' },
+            { name: 'answer', type: 'int256' },
+            { name: 'startedAt', type: 'uint256' },
+            { name: 'updatedAt', type: 'uint256' },
+            { name: 'answeredInRound', type: 'uint80' },
+        ],
+    },
+    {
+        name: 'getRoundData',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [{ name: '_roundId', type: 'uint80' }],
+        outputs: [
+            { name: 'roundId', type: 'uint80' },
+            { name: 'answer', type: 'int256' },
+            { name: 'startedAt', type: 'uint256' },
+            { name: 'updatedAt', type: 'uint256' },
+            { name: 'answeredInRound', type: 'uint80' },
+        ],
+    },
+    {
+        name: 'decimals',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [],
+        outputs: [{ name: '', type: 'uint8' }],
+    },
+    {
+        name: 'description',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [],
+        outputs: [{ name: '', type: 'string' }],
+    },
+];
+/** Scale a raw Chainlink int256 answer to a decimal string. */
+export function scaleToDecimal(answer, decimals) {
+    if (answer < 0n) {
+        throw new Error(`scaleToDecimal: negative value not supported in v0 (got ${answer})`);
+    }
+    const s = answer.toString();
+    if (decimals === 0)
+        return s;
+    if (s.length <= decimals) {
+        const frac = s.padStart(decimals, '0').replace(/0+$/, '');
+        return frac.length > 0 ? `0.${frac}` : '0';
+    }
+    const intPart = s.slice(0, s.length - decimals);
+    const fracRaw = s.slice(s.length - decimals);
+    const frac = fracRaw.replace(/0+$/, '');
+    return frac.length > 0 ? `${intPart}.${frac}` : intPart;
+}
+export async function readChainlinkLatest(feed, publicClient) {
+    const [latest, decimals] = await Promise.all([
+        publicClient.readContract({
+            address: feed,
+            abi: AGGREGATOR_V3_ABI,
+            functionName: 'latestRoundData',
+        }),
+        publicClient.readContract({
+            address: feed,
+            abi: AGGREGATOR_V3_ABI,
+            functionName: 'decimals',
+        }),
+    ]);
+    const [roundId, answer, startedAt, updatedAt, answeredInRound] = latest;
+    return {
+        roundId,
+        answer,
+        // Chainlink timestamps are SECONDS → convert to ms for consistency with rest of codebase
+        startedAt: Number(startedAt) * 1000,
+        updatedAt: Number(updatedAt) * 1000,
+        answeredInRound,
+        decimals: decimals,
+    };
+}
+export async function readChainlinkRound(feed, roundId, publicClient, decimals) {
+    const round = await publicClient.readContract({
+        address: feed,
+        abi: AGGREGATOR_V3_ABI,
+        functionName: 'getRoundData',
+        args: [roundId],
+    });
+    const [rid, answer, startedAt, updatedAt, answeredInRound] = round;
+    return {
+        roundId: rid,
+        answer,
+        startedAt: Number(startedAt) * 1000,
+        updatedAt: Number(updatedAt) * 1000,
+        answeredInRound,
+        decimals,
+    };
+}
+/**
+ * Find the Chainlink round that "spans" resolveTs: round R where
+ * R.updatedAt ≤ resolveTs < (R+1).updatedAt.
+ *
+ * If the latest round's updatedAt ≤ resolveTs (i.e. no newer round yet),
+ * returns { round: latest, nextRound: null, spanning: false }. Caller should
+ * retry later (availability check will mark SKIP → INDETERMINATE verdict).
+ */
+export async function oraclePriceAtResolveTs(feed, resolveTs, publicClient) {
+    const latest = await readChainlinkLatest(feed, publicClient);
+    // Case A: latest is at-or-before resolveTs → no newer round yet
+    if (latest.updatedAt <= resolveTs) {
+        return { round: latest, nextRound: null, spanning: false };
+    }
+    // Case B: latest is after resolveTs → walk back to find spanning round
+    let nextRound = latest;
+    let cursor = latest.roundId - 1n;
+    while (cursor > 0n) {
+        const r = await readChainlinkRound(feed, cursor, publicClient, latest.decimals);
+        if (r.updatedAt <= resolveTs) {
+            return { round: r, nextRound, spanning: true };
+        }
+        nextRound = r;
+        cursor -= 1n;
+    }
+    // Walked back to round 0 without finding a pre-resolveTs round — oracle is
+    // newer than the window. Surface as not-spanning so caller INDETERMINATE-s.
+    return { round: latest, nextRound: null, spanning: false };
+}
+//# sourceMappingURL=client.js.map

package/dist/venues/chainlink/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/venues/chainlink/client.ts"],"names":[],"mappings":"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"}

package/dist/venues/chainlink/feeds.d.ts

@@ -0,0 +1,8 @@
+/** Known Chainlink AggregatorV3 feeds on Base + Base Sepolia. */
+export declare const BASE_SEPOLIA_FEEDS: {
+    readonly 'ETH / USD': "0x4aDC67696bA383F43DD60A9e78F2C97Fbbfc7cb1";
+    readonly 'BTC / USD': "0x0FB99723Aee6f420beAD13e6bBB79b7E6F034298";
+};
+export declare const BASE_FEEDS: {
+    readonly 'ETH / USD': "0x71041dddad3595F9CEd3DcCFBe3D1F4b0a16Bb70";
+};

package/dist/venues/chainlink/feeds.js

@@ -0,0 +1,9 @@
+/** Known Chainlink AggregatorV3 feeds on Base + Base Sepolia. */
+export const BASE_SEPOLIA_FEEDS = {
+    'ETH / USD': '0x4aDC67696bA383F43DD60A9e78F2C97Fbbfc7cb1',
+    'BTC / USD': '0x0FB99723Aee6f420beAD13e6bBB79b7E6F034298',
+};
+export const BASE_FEEDS = {
+    'ETH / USD': '0x71041dddad3595F9CEd3DcCFBe3D1F4b0a16Bb70',
+};
+//# sourceMappingURL=feeds.js.map

package/dist/venues/chainlink/feeds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feeds.js","sourceRoot":"","sources":["../../../src/venues/chainlink/feeds.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,WAAW,EAAE,4CAAqD;IAClE,WAAW,EAAE,4CAAqD;CAC1D,CAAC;AAEX,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,WAAW,EAAE,4CAAqD;CAC1D,CAAC"}

package/dist/venues/hyperliquid/account-value.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Unified account-value helper.
+ *
+ * Returns a single equity figure that sums perps margin + spot USDC. This
+ * matches HL's `portfolio` endpoint `accountValueHistory` (which also
+ * reports the unified view), so restorer-claimed equity and evaluator-
+ * rederived grid points compare cleanly.
+ *
+ * Non-USDC spot tokens are NOT valued in v0 — their midprice lookup and
+ * safety semantics are out of scope for the first cut of portfolio.v0.
+ */
+import type { HlClearinghouseState, HlSpotClearinghouseState } from './types.js';
+export interface UnifiedAccountValue {
+    /** Sum of perps accountValue + spot USDC balance, as a decimal string. */
+    accountValue: string;
+    /** Perps-only accountValue (marginSummary.accountValue). */
+    perpsAccountValue: string;
+    /** Spot USDC balance (0 if absent). */
+    spotUsdc: string;
+    /** Raw perps payload from HL. */
+    clearinghouseState: HlClearinghouseState;
+    /** Raw spot payload from HL. */
+    spotClearinghouseState: HlSpotClearinghouseState;
+}
+interface HlClientLike {
+    clearinghouseState: (user: string) => Promise<HlClearinghouseState>;
+    spotClearinghouseState: (user: string) => Promise<HlSpotClearinghouseState>;
+}
+export declare function getUnifiedAccountValue(hlClient: HlClientLike, user: string): Promise<UnifiedAccountValue>;
+export {};

package/dist/venues/hyperliquid/account-value.js

@@ -0,0 +1,30 @@
+/**
+ * Unified account-value helper.
+ *
+ * Returns a single equity figure that sums perps margin + spot USDC. This
+ * matches HL's `portfolio` endpoint `accountValueHistory` (which also
+ * reports the unified view), so restorer-claimed equity and evaluator-
+ * rederived grid points compare cleanly.
+ *
+ * Non-USDC spot tokens are NOT valued in v0 — their midprice lookup and
+ * safety semantics are out of scope for the first cut of portfolio.v0.
+ */
+export async function getUnifiedAccountValue(hlClient, user) {
+    const [clearinghouseState, spotClearinghouseState] = await Promise.all([
+        hlClient.clearinghouseState(user),
+        hlClient.spotClearinghouseState(user),
+    ]);
+    const perpsAccountValue = clearinghouseState.marginSummary.accountValue;
+    const usdcBalance = spotClearinghouseState.balances.find((b) => b.coin === 'USDC');
+    const spotUsdc = usdcBalance ? usdcBalance.total : '0';
+    const total = parseFloat(perpsAccountValue) + parseFloat(spotUsdc);
+    const accountValue = String(total);
+    return {
+        accountValue,
+        perpsAccountValue,
+        spotUsdc,
+        clearinghouseState,
+        spotClearinghouseState,
+    };
+}
+//# sourceMappingURL=account-value.js.map

package/dist/venues/hyperliquid/account-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-value.js","sourceRoot":"","sources":["../../../src/venues/hyperliquid/account-value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAyBH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,QAAsB,EACtB,IAAY;IAEZ,MAAM,CAAC,kBAAkB,EAAE,sBAAsB,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACrE,QAAQ,CAAC,kBAAkB,CAAC,IAAI,CAAC;QACjC,QAAQ,CAAC,sBAAsB,CAAC,IAAI,CAAC;KACtC,CAAC,CAAC;IAEH,MAAM,iBAAiB,GAAG,kBAAkB,CAAC,aAAa,CAAC,YAAY,CAAC;IACxE,MAAM,WAAW,GAAG,sBAAsB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;IACnF,MAAM,QAAQ,GAAG,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;IAEvD,MAAM,KAAK,GAAG,UAAU,CAAC,iBAAiB,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IACnE,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAEnC,OAAO;QACL,YAAY;QACZ,iBAAiB;QACjB,QAAQ;QACR,kBAAkB;QAClB,sBAAsB;KACvB,CAAC;AACJ,CAAC"}

package/dist/venues/hyperliquid/client.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Read-only Hyperliquid public API client.
+ *
+ * All endpoints are POST /info with a JSON body. No authentication required.
+ * This client is intentionally read-only — write paths are out of scope.
+ */
+import type { HlAllMidsResponse, HlClearinghouseState, HlMetaResponse, HlPeriodData, HlPortfolioPeriod, HlPortfolioResponse, HlSpotClearinghouseState, HlUserFills, HlUserFillsByTimeResult } from './types.js';
+export declare const HL_MAINNET_BASE_URL = "https://api.hyperliquid.xyz";
+export declare const HL_TESTNET_BASE_URL = "https://api.hyperliquid-testnet.xyz";
+export declare class HyperliquidClient {
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    constructor(baseUrl?: string, timeoutMs?: number);
+    private post;
+    /**
+     * Returns the current clearinghouse (margin) state for a user.
+     * This reflects the LIVE state — there is no historical point-in-time lookup.
+     */
+    clearinghouseState(user: string): Promise<HlClearinghouseState>;
+    /**
+     * Returns the current spot (non-perps) clearinghouse state for a user.
+     * Includes USDC and other spot token balances.
+     */
+    spotClearinghouseState(user: string): Promise<HlSpotClearinghouseState>;
+    /**
+     * Returns recent fills for a user, in descending time order.
+     */
+    userFills(user: string): Promise<HlUserFills>;
+    /**
+     * Returns fills for a user in ascending time order, with optional pagination.
+     *
+     * The HL API silently clamps `startTime` to its retention horizon (typically
+     * ~30 days). When clamping occurs the first fill's `.time` will be greater
+     * than the requested `startTime`. This method detects that and sets
+     * `result.startTimeClamped = true`.
+     *
+     * @param user           Ethereum address of the account.
+     * @param startTime      Start of the window in epoch milliseconds.
+     * @param endTime        Optional end of the window in epoch milliseconds.
+     * @param aggregateByTime Passed directly to the API (default false).
+     */
+    userFillsByTime(user: string, startTime: number, endTime?: number, aggregateByTime?: boolean): Promise<HlUserFillsByTimeResult>;
+    /**
+     * Returns historical account-value snapshots (~140-minute grid) for a user.
+     *
+     * The response is an array of [periodName, periodData] tuples where period
+     * is one of "day", "week", "month", "allTime".
+     */
+    portfolio(user: string): Promise<HlPortfolioResponse>;
+    /**
+     * Fetches the portfolio response and extracts a specific period bucket.
+     * Returns null if the period is not present in the response.
+     */
+    portfolioPeriod(user: string, period: HlPortfolioPeriod): Promise<HlPeriodData | null>;
+    /**
+     * Returns the universe of perpetual markets (metadata).
+     */
+    meta(): Promise<HlMetaResponse>;
+    /**
+     * Returns current mid prices for all assets.
+     */
+    allMids(): Promise<HlAllMidsResponse>;
+}

package/dist/venues/hyperliquid/client.js

@@ -0,0 +1,135 @@
+/**
+ * Read-only Hyperliquid public API client.
+ *
+ * All endpoints are POST /info with a JSON body. No authentication required.
+ * This client is intentionally read-only — write paths are out of scope.
+ */
+export const HL_MAINNET_BASE_URL = 'https://api.hyperliquid.xyz';
+export const HL_TESTNET_BASE_URL = 'https://api.hyperliquid-testnet.xyz';
+export class HyperliquidClient {
+    baseUrl;
+    timeoutMs;
+    constructor(baseUrl = HL_MAINNET_BASE_URL, timeoutMs = 15_000) {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.timeoutMs = timeoutMs;
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    async post(body) {
+        const url = `${this.baseUrl}/info`;
+        const ac = new AbortController();
+        const t = setTimeout(() => ac.abort(), this.timeoutMs);
+        try {
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+                signal: ac.signal,
+            });
+            if (!res.ok) {
+                const excerpt = await res.text().then((t) => t.slice(0, 200));
+                throw new Error(`Hyperliquid API error: HTTP ${res.status} ${res.statusText} — ${excerpt}`);
+            }
+            try {
+                return (await res.json());
+            }
+            catch (err) {
+                throw new Error(`Hyperliquid API error: could not parse JSON response from ${url}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new Error(`Hyperliquid API timeout after ${this.timeoutMs}ms calling ${url}`);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(t);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Public endpoints
+    // -------------------------------------------------------------------------
+    /**
+     * Returns the current clearinghouse (margin) state for a user.
+     * This reflects the LIVE state — there is no historical point-in-time lookup.
+     */
+    async clearinghouseState(user) {
+        return this.post({ type: 'clearinghouseState', user });
+    }
+    /**
+     * Returns the current spot (non-perps) clearinghouse state for a user.
+     * Includes USDC and other spot token balances.
+     */
+    async spotClearinghouseState(user) {
+        return this.post({ type: 'spotClearinghouseState', user });
+    }
+    /**
+     * Returns recent fills for a user, in descending time order.
+     */
+    async userFills(user) {
+        return this.post({ type: 'userFills', user });
+    }
+    /**
+     * Returns fills for a user in ascending time order, with optional pagination.
+     *
+     * The HL API silently clamps `startTime` to its retention horizon (typically
+     * ~30 days). When clamping occurs the first fill's `.time` will be greater
+     * than the requested `startTime`. This method detects that and sets
+     * `result.startTimeClamped = true`.
+     *
+     * @param user           Ethereum address of the account.
+     * @param startTime      Start of the window in epoch milliseconds.
+     * @param endTime        Optional end of the window in epoch milliseconds.
+     * @param aggregateByTime Passed directly to the API (default false).
+     */
+    async userFillsByTime(user, startTime, endTime, aggregateByTime = false) {
+        const body = {
+            type: 'userFillsByTime',
+            user,
+            startTime,
+            aggregateByTime,
+        };
+        if (endTime !== undefined) {
+            body['endTime'] = endTime;
+        }
+        const fills = await this.post(body);
+        // Clamp detection: if the first fill's time is strictly greater than the
+        // requested startTime, HL quietly moved the window forward to its retention
+        // horizon. An empty result is NOT treated as clamped — we can't tell.
+        const startTimeClamped = fills.length > 0 && fills[0] !== undefined && fills[0].time > startTime;
+        return { fills, startTimeClamped };
+    }
+    /**
+     * Returns historical account-value snapshots (~140-minute grid) for a user.
+     *
+     * The response is an array of [periodName, periodData] tuples where period
+     * is one of "day", "week", "month", "allTime".
+     */
+    async portfolio(user) {
+        return this.post({ type: 'portfolio', user });
+    }
+    /**
+     * Fetches the portfolio response and extracts a specific period bucket.
+     * Returns null if the period is not present in the response.
+     */
+    async portfolioPeriod(user, period) {
+        const response = await this.portfolio(user);
+        const entry = response.find(([name]) => name === period);
+        return entry ? entry[1] : null;
+    }
+    /**
+     * Returns the universe of perpetual markets (metadata).
+     */
+    async meta() {
+        return this.post({ type: 'meta' });
+    }
+    /**
+     * Returns current mid prices for all assets.
+     */
+    async allMids() {
+        return this.post({ type: 'allMids' });
+    }
+}
+//# sourceMappingURL=client.js.map