@candledottv/agent-sdk 0.6.2 → 0.6.3

package/dist/perps-history.d.ts

@@ -0,0 +1,126 @@
+export type PerpsHistoryKind = "fills" | "funding";
+export type PerpsHistoryNetwork = "mainnet" | "testnet";
+/** Hyperliquid's public `/info` endpoint per network. Mirrors `HYPERLIQUID_INFO_URLS`. */
+export declare const PERPS_HISTORY_INFO_URLS: Readonly<Record<PerpsHistoryNetwork, string>>;
+/** Rows a page holds when the caller names no limit. */
+export declare const PERPS_HISTORY_DEFAULT_LIMIT = 100;
+/** The most rows one upstream response carries, and so the largest page: 2,000 fills, 500 funding rows. */
+export declare const PERPS_HISTORY_MAX_LIMIT: Readonly<Record<PerpsHistoryKind, number>>;
+/** The default window: the seven days before `endTime`. */
+export declare const PERPS_HISTORY_DEFAULT_WINDOW_MS: number;
+/** Upstream history requests one call may make before it stops with a resumable cursor. */
+export declare const PERPS_HISTORY_REQUEST_BUDGET = 10;
+/** Hyperliquid serves only an account's 10,000 most recent fills; a cursor chain scans no more. */
+export declare const PERPS_HISTORY_FILL_RETENTION = 10000;
+/** The longest cursor accepted, in characters. */
+export declare const PERPS_HISTORY_MAX_CURSOR_LENGTH = 200000;
+/** How long one upstream request may take. */
+export declare const PERPS_HISTORY_TIMEOUT_MS = 15000;
+export interface PerpsHistoryOptions {
+    /** Inclusive epoch milliseconds. Default: seven days before `endTime`. */
+    startTime?: number;
+    /** Inclusive epoch milliseconds. Default: the first call's clock. */
+    endTime?: number;
+    /** Rows per page. Default 100; at most 2,000 for fills and 500 for funding. */
+    limit?: number;
+    /** `nextCursor` from the previous page. Other options, when given, must match it. */
+    cursor?: string;
+}
+export interface PerpsHistoryWarning {
+    code: "PERPS_HISTORY_RETENTION_LIMIT" | "PERPS_HISTORY_PAGE_BUDGET" | "PERPS_HISTORY_BOUNDARY_LIMIT";
+    message: string;
+}
+/** One fill exactly as Hyperliquid reports it; decimal values stay strings. */
+export type PerpsFillRow = Record<string, unknown> & {
+    coin: string;
+    time: number;
+    tid: number;
+    oid: number;
+    px: string;
+    sz: string;
+    side: string;
+    dir?: string;
+    closedPnl: string;
+    /** Already includes `builderFee`; never subtract the builder fee again. */
+    fee: string;
+    feeToken?: string;
+    builderFee?: string;
+};
+/** One funding payment exactly as Hyperliquid reports it. `delta.usdc` is signed: negative is paid. */
+export type PerpsFundingRow = Record<string, unknown> & {
+    time: number;
+    hash: string;
+    delta: Record<string, unknown> & {
+        coin: string;
+        usdc: string;
+        fundingRate: string;
+        szi: string;
+    };
+};
+interface PageBase {
+    success: true;
+    walletId: string;
+    address: string;
+    network: PerpsHistoryNetwork;
+    source: "hyperliquid";
+    /** When this page was read, epoch milliseconds. */
+    readAt: number;
+    startTime: number;
+    endTime: number;
+    /** Pass back as `cursor` for the next page; null when the window is read to its end. */
+    nextCursor: string | null;
+    hasMore: boolean;
+    /** True when coverage stopped short of the window for a venue or budget limit, not for paging. */
+    truncated: boolean;
+    warnings: PerpsHistoryWarning[];
+}
+export type PerpsFillsPage = PageBase & {
+    fills: PerpsFillRow[];
+};
+export type PerpsFundingPage = PageBase & {
+    funding: PerpsFundingRow[];
+};
+/** A refusal or an upstream failure. `code` is `VALIDATION_FAILED` or `PERPS_UNAVAILABLE`. */
+export declare class PerpsHistoryError extends Error {
+    readonly code: "VALIDATION_FAILED" | "PERPS_UNAVAILABLE";
+    readonly extra: {
+        field?: string;
+        retryable?: boolean;
+        retryAfterMs?: number;
+    };
+    constructor(code: "VALIDATION_FAILED" | "PERPS_UNAVAILABLE", message: string, extra?: {
+        field?: string;
+        retryable?: boolean;
+        retryAfterMs?: number;
+    });
+}
+export type PerpsHistoryFetch = (url: string, init?: RequestInit) => Promise<{
+    ok: boolean;
+    status: number;
+    headers?: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}>;
+export interface PerpsHistoryRequest {
+    kind: PerpsHistoryKind;
+    network: PerpsHistoryNetwork;
+    walletId: string;
+    /** The wallet's EVM address: the Hyperliquid account. */
+    address: string;
+    options?: PerpsHistoryOptions;
+    fetch: PerpsHistoryFetch;
+    now: () => number;
+}
+/**
+ * Read one page. Validation runs before any request, so a bad bound, limit or cursor makes no I/O.
+ * A rate limit, a timeout, a malformed answer or an unreadable market list throws `PERPS_UNAVAILABLE`
+ * and the caller's cursor stays good for a retry; nothing is ever reported as an empty success.
+ */
+export declare function readPerpsHistoryPage(req: PerpsHistoryRequest): Promise<PerpsFillsPage | PerpsFundingPage>;
+/** Money for a table: two decimals, sign kept. JSON keeps the venue's exact strings. */
+export declare function perpsHistoryMoney(value: unknown): string;
+/** The human lines for one page: wallet, UTC window, rows, then how to read the next page. */
+export declare function perpsHistoryLines(page: PerpsFillsPage | PerpsFundingPage, nextHint: (cursor: string) => string): string[];
+export {};
+//# sourceMappingURL=perps-history.d.ts.map

package/dist/perps-history.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@candledottv/agent-sdk",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "TypeScript SDK for the Candle agent rail: typed headless launches, market reads, and webhook verification",
   "type": "module",
   "main": "./dist/index.js",