get_freshness
Read-onlyIdempotent
Check data freshness for a coin across orderbook, trades, funding, open interest, and liquidations. Displays last update time and current lag for each data type.
Instructions
Get data freshness for a coin across all data types (orderbook, trades, funding, OI, liquidations). Shows when each data type was last updated and current lag.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| coin | Yes | Coin/market symbol, e.g. 'BTC', 'ETH', 'SOL' |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Result data object |
Implementation Reference
- src/index.ts:603-610 (registration)Tool registration for 'get_freshness' using the registerCurrentTool helper pattern. Registered under Hyperliquid section (// 13. Freshness).
// 13. Freshness registerCurrentTool( "get_freshness", "Get data freshness for a coin across all data types (orderbook, trades, funding, OI, liquidations). Shows when each data type was last updated and current lag.", (coin) => api().hyperliquid.freshness(coin), CoinParam, normalizeHLCoin ); - src/index.ts:373-384 (handler)The registerCurrentTool helper function (Pattern 2) acts as the handler factory. It wraps the SDK call api().hyperliquid.freshness(coin) inside a standard handler that normalizes the input coin, calls the SDK, and formats the response as a single object.
function registerCurrentTool( name: string, description: string, sdkCall: (coin: string) => Promise<unknown>, coinSchema: z.ZodString, normFn: (coin: string) => string ): void { registerTool(name, description, { coin: coinSchema }, ObjectOutputSchema, async (params) => { const data = await sdkCall(normFn(params.coin)); return formatResponse(data); }); } - src/index.ts:53-55 (schema)Input schema: CoinParam defines the 'coin' parameter as a string (e.g., 'BTC', 'ETH', 'SOL') which is the sole input to get_freshness.
const CoinParam = z .string() .describe("Coin/market symbol, e.g. 'BTC', 'ETH', 'SOL'"); - src/index.ts:139-141 (schema)Output schema: ObjectOutputSchema defines the return type as a single object ({ data: ... }), used by get_freshness since it returns a current snapshot.
const ObjectOutputSchema: ZodRawShape = { data: z.record(z.unknown()).describe("Result data object"), }; - src/index.ts:296-328 (helper)Helper: normalizeHLCoin converts the coin symbol to uppercase, used as the normalization function in the get_freshness registration.
function normalizeHLCoin(coin: string): string { return coin.toUpperCase(); } function normalizeHip3Coin(coin: string): string { return coin; // Case-sensitive } // HIP-4 path encoding: the canonical form is the bare numeric `0`, `1`, `42`. // The legacy `#0` / `%230` forms are still accepted by the API. We normalize to // the bare form when possible (avoids URL-fragment ambiguity entirely). function normalizeHip4Coin(coin: string): string { const trimmed = String(coin).trim(); if (/^\d+$/.test(trimmed)) return trimmed; const stripped = trimmed.replace(/^(#|%23)/i, ""); if (/^\d+$/.test(stripped)) return stripped; // Unknown shape — fall back to URL-encoding the original. return encodeURIComponent(trimmed); } function normalizeLighterCoin(coin: string): string { return coin.toUpperCase(); } function normalizeSpotCoin(coin: string): string { return coin.toUpperCase(); } // --------------------------------------------------------------------------- // G. Tool Registration Helpers // --------------------------------------------------------------------------- function registerTool(