@pythnetwork/hermes-client 1.1.0 → 1.3.0

package/README.md

@@ -69,12 +69,15 @@ By default, these updates are returned as binary data and is serialized as eithe
 
 ### Examples
 
-The [HermesClient](./src/examples/HermesClient.ts) example demonstrates both the examples above.
-You can run it with `npm run example`.
-A full command that prints BTC and ETH price feeds, in the testnet network, looks like so:
+The [HermesClient](./src/examples/HermesClient.ts) example demonstrates both the
+examples above. To run the example:
+
+1. Clone [the Pyth monorepo](https://github.com/pyth-network/pyth-crosschain)
+2. In the root of the monorepo, run `pnpm example:hermes-client -- <args>`. For
+   example, to print BTC and ETH price feeds in the testnet network, run:
 
 ```bash
-npm run example -- \
+pnpm example:hermes-client -- \
   --endpoint https://hermes.pyth.network \
   --price-ids \
     0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43 \

package/lib/HermesClient.d.ts

@@ -7,6 +7,7 @@ export type EncodingType = z.infer<typeof schemas.EncodingType>;
 export type PriceFeedMetadata = z.infer<typeof schemas.PriceFeedMetadata>;
 export type PriceIdInput = z.infer<typeof schemas.PriceIdInput>;
 export type PriceUpdate = z.infer<typeof schemas.PriceUpdate>;
+export type TwapsResponse = z.infer<typeof schemas.TwapsResponse>;
 export type PublisherCaps = z.infer<typeof schemas.LatestPublisherStakeCapsUpdateDataResponse>;
 export type UnixTimestamp = number;
 export type DurationInSeconds = number;
@@ -78,12 +79,14 @@ export declare class HermesClient {
      * @param options Optional parameters:
      *        - encoding: Encoding type. If specified, return the price update in the encoding specified by the encoding parameter. Default is hex.
      *        - parsed: Boolean to specify if the parsed price update should be included in the response. Default is false.
+     *        - ignoreInvalidPriceIds: Boolean to specify if invalid price IDs should be ignored instead of returning an error. Default is false.
      *
      * @returns PriceUpdate object containing the latest updates.
      */
     getLatestPriceUpdates(ids: HexString[], options?: {
         encoding?: EncodingType;
         parsed?: boolean;
+        ignoreInvalidPriceIds?: boolean;
     }): Promise<PriceUpdate>;
     /**
      * Fetch the price updates for a set of price feed IDs at a given timestamp.
@@ -95,12 +98,14 @@ export declare class HermesClient {
      * @param options Optional parameters:
      *        - encoding: Encoding type. If specified, return the price update in the encoding specified by the encoding parameter. Default is hex.
      *        - parsed: Boolean to specify if the parsed price update should be included in the response. Default is false.
+     *        - ignoreInvalidPriceIds: Boolean to specify if invalid price IDs should be ignored instead of returning an error. Default is false.
      *
      * @returns PriceUpdate object containing the updates at the specified timestamp.
      */
     getPriceUpdatesAtTimestamp(publishTime: UnixTimestamp, ids: HexString[], options?: {
         encoding?: EncodingType;
         parsed?: boolean;
+        ignoreInvalidPriceIds?: boolean;
     }): Promise<PriceUpdate>;
     /**
      * Fetch streaming price updates for a set of price feed IDs.
@@ -109,12 +114,14 @@ export declare class HermesClient {
      * This will return an EventSource that can be used to listen to streaming updates.
      * If an invalid hex-encoded ID is passed, it will throw an error.
      *
-     *
      * @param ids Array of hex-encoded price feed IDs for which streaming updates are requested.
-     * @param encoding Optional encoding type. If specified, updates are returned in the specified encoding. Default is hex.
-     * @param parsed Optional boolean to specify if the parsed price update should be included in the response. Default is false.
-     * @param allow_unordered Optional boolean to specify if unordered updates are allowed to be included in the stream. Default is false.
-     * @param benchmarks_only Optional boolean to specify if only benchmark prices that are the initial price updates at a given timestamp (i.e., prevPubTime != pubTime) should be returned. Default is false.
+     * @param options Optional parameters:
+     *        - encoding: Encoding type. If specified, updates are returned in the specified encoding. Default is hex.
+     *        - parsed: Boolean to specify if the parsed price update should be included in the response. Default is false.
+     *        - allowUnordered: Boolean to specify if unordered updates are allowed to be included in the stream. Default is false.
+     *        - benchmarksOnly: Boolean to specify if only benchmark prices should be returned. Default is false.
+     *        - ignoreInvalidPriceIds: Boolean to specify if invalid price IDs should be ignored instead of returning an error. Default is false.
+     *
      * @returns An EventSource instance for receiving streaming updates.
      */
     getPriceUpdatesStream(ids: HexString[], options?: {
@@ -122,7 +129,28 @@ export declare class HermesClient {
         parsed?: boolean;
         allowUnordered?: boolean;
         benchmarksOnly?: boolean;
+        ignoreInvalidPriceIds?: boolean;
     }): Promise<EventSource>;
+    /**
+     * Fetch the latest TWAP (time weighted average price) for a set of price feed IDs.
+     * This endpoint can be customized by specifying the encoding type and whether the results should also return the calculated TWAP using the options object.
+     * This will throw an error if there is a network problem or the price service returns a non-ok response.
+     *
+     * @param ids Array of hex-encoded price feed IDs for which updates are requested.
+     * @param window_seconds The time window in seconds over which to calculate the TWAP, ending at the current time.
+     *  For example, a value of 300 would return the most recent 5 minute TWAP. Must be greater than 0 and less than or equal to 600 seconds (10 minutes).
+     * @param options Optional parameters:
+     *        - encoding: Encoding type. If specified, return the TWAP binary data in the encoding specified by the encoding parameter. Default is hex.
+     *        - parsed: Boolean to specify if the calculated TWAP should be included in the response. Default is false.
+     *        - ignoreInvalidPriceIds: Boolean to specify if invalid price IDs should be ignored instead of returning an error. Default is false.
+     *
+     * @returns TwapsResponse object containing the latest TWAPs.
+     */
+    getLatestTwaps(ids: HexString[], window_seconds: number, options?: {
+        encoding?: EncodingType;
+        parsed?: boolean;
+        ignoreInvalidPriceIds?: boolean;
+    }): Promise<TwapsResponse>;
     private appendUrlSearchParams;
 }
 //# sourceMappingURL=HermesClient.d.ts.map

package/lib/HermesClient.d.ts.map

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

package/lib/HermesClient.js

@@ -41,7 +41,8 @@ class HermesClient {
             const response = await fetch(url, options);
             clearTimeout(timeout); // Clear the timeout if the request completes in time
             if (!response.ok) {
-                throw new Error(`HTTP error! status: ${response.status}`);
+                const errorBody = await response.text();
+                throw new Error(`HTTP error! status: ${response.status}${errorBody ? `, body: ${errorBody}` : ""}`);
             }
             const data = await response.json();
             return schema.parse(data);
@@ -102,6 +103,7 @@ class HermesClient {
      * @param options Optional parameters:
      *        - encoding: Encoding type. If specified, return the price update in the encoding specified by the encoding parameter. Default is hex.
      *        - parsed: Boolean to specify if the parsed price update should be included in the response. Default is false.
+     *        - ignoreInvalidPriceIds: Boolean to specify if invalid price IDs should be ignored instead of returning an error. Default is false.
      *
      * @returns PriceUpdate object containing the latest updates.
      */
@@ -111,7 +113,8 @@ class HermesClient {
             url.searchParams.append("ids[]", id);
         }
         if (options) {
-            this.appendUrlSearchParams(url, options);
+            const transformedOptions = (0, utils_1.camelToSnakeCaseObject)(options);
+            this.appendUrlSearchParams(url, transformedOptions);
         }
         return this.httpRequest(url.toString(), zodSchemas_1.schemas.PriceUpdate);
     }
@@ -125,6 +128,7 @@ class HermesClient {
      * @param options Optional parameters:
      *        - encoding: Encoding type. If specified, return the price update in the encoding specified by the encoding parameter. Default is hex.
      *        - parsed: Boolean to specify if the parsed price update should be included in the response. Default is false.
+     *        - ignoreInvalidPriceIds: Boolean to specify if invalid price IDs should be ignored instead of returning an error. Default is false.
      *
      * @returns PriceUpdate object containing the updates at the specified timestamp.
      */
@@ -134,7 +138,8 @@ class HermesClient {
             url.searchParams.append("ids[]", id);
         }
         if (options) {
-            this.appendUrlSearchParams(url, options);
+            const transformedOptions = (0, utils_1.camelToSnakeCaseObject)(options);
+            this.appendUrlSearchParams(url, transformedOptions);
         }
         return this.httpRequest(url.toString(), zodSchemas_1.schemas.PriceUpdate);
     }
@@ -145,12 +150,14 @@ class HermesClient {
      * This will return an EventSource that can be used to listen to streaming updates.
      * If an invalid hex-encoded ID is passed, it will throw an error.
      *
-     *
      * @param ids Array of hex-encoded price feed IDs for which streaming updates are requested.
-     * @param encoding Optional encoding type. If specified, updates are returned in the specified encoding. Default is hex.
-     * @param parsed Optional boolean to specify if the parsed price update should be included in the response. Default is false.
-     * @param allow_unordered Optional boolean to specify if unordered updates are allowed to be included in the stream. Default is false.
-     * @param benchmarks_only Optional boolean to specify if only benchmark prices that are the initial price updates at a given timestamp (i.e., prevPubTime != pubTime) should be returned. Default is false.
+     * @param options Optional parameters:
+     *        - encoding: Encoding type. If specified, updates are returned in the specified encoding. Default is hex.
+     *        - parsed: Boolean to specify if the parsed price update should be included in the response. Default is false.
+     *        - allowUnordered: Boolean to specify if unordered updates are allowed to be included in the stream. Default is false.
+     *        - benchmarksOnly: Boolean to specify if only benchmark prices should be returned. Default is false.
+     *        - ignoreInvalidPriceIds: Boolean to specify if invalid price IDs should be ignored instead of returning an error. Default is false.
+     *
      * @returns An EventSource instance for receiving streaming updates.
      */
     async getPriceUpdatesStream(ids, options) {
@@ -164,6 +171,32 @@ class HermesClient {
         }
         return new eventsource_1.default(url.toString(), { headers: this.headers });
     }
+    /**
+     * Fetch the latest TWAP (time weighted average price) for a set of price feed IDs.
+     * This endpoint can be customized by specifying the encoding type and whether the results should also return the calculated TWAP using the options object.
+     * This will throw an error if there is a network problem or the price service returns a non-ok response.
+     *
+     * @param ids Array of hex-encoded price feed IDs for which updates are requested.
+     * @param window_seconds The time window in seconds over which to calculate the TWAP, ending at the current time.
+     *  For example, a value of 300 would return the most recent 5 minute TWAP. Must be greater than 0 and less than or equal to 600 seconds (10 minutes).
+     * @param options Optional parameters:
+     *        - encoding: Encoding type. If specified, return the TWAP binary data in the encoding specified by the encoding parameter. Default is hex.
+     *        - parsed: Boolean to specify if the calculated TWAP should be included in the response. Default is false.
+     *        - ignoreInvalidPriceIds: Boolean to specify if invalid price IDs should be ignored instead of returning an error. Default is false.
+     *
+     * @returns TwapsResponse object containing the latest TWAPs.
+     */
+    async getLatestTwaps(ids, window_seconds, options) {
+        const url = new URL(`v2/updates/twap/${window_seconds}/latest`, this.baseURL);
+        for (const id of ids) {
+            url.searchParams.append("ids[]", id);
+        }
+        if (options) {
+            const transformedOptions = (0, utils_1.camelToSnakeCaseObject)(options);
+            this.appendUrlSearchParams(url, transformedOptions);
+        }
+        return this.httpRequest(url.toString(), zodSchemas_1.schemas.TwapsResponse);
+    }
     appendUrlSearchParams(url, params) {
         Object.entries(params).forEach(([key, value]) => {
             if (value !== undefined) {

package/lib/examples/HermesClient.js

@@ -48,15 +48,22 @@ async function run() {
     const connection = new HermesClient_1.HermesClient(endpoint, { headers });
     const priceIds = argv.priceIds;
     // Get price feeds
+    console.log(`Price feeds matching "btc" with asset type "crypto":`);
     const priceFeeds = await connection.getPriceFeeds({
         query: "btc",
         filter: "crypto",
     });
     console.log(priceFeeds);
     // Latest price updates
+    console.log(`Latest price updates for price IDs ${priceIds}:`);
     const priceUpdates = await connection.getLatestPriceUpdates(priceIds);
     console.log(priceUpdates);
+    // Get the latest 5 second TWAPs
+    console.log(`Latest 5 second TWAPs for price IDs ${priceIds}`);
+    const twapUpdates = await connection.getLatestTwaps(priceIds, 5);
+    console.log(twapUpdates);
     // Streaming price updates
+    console.log(`Streaming latest prices for price IDs ${priceIds}...`);
     const eventSource = await connection.getPriceUpdatesStream(priceIds, {
         encoding: "hex",
         parsed: true,
@@ -65,6 +72,7 @@ async function run() {
     });
     eventSource.onmessage = (event) => {
         console.log("Received price update:", event.data);
+        const _priceUpdate = JSON.parse(event.data);
     };
     eventSource.onerror = (error) => {
         console.error("Error receiving updates:", error);