@pythnetwork/hermes-client 1.0.0

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2023 Pyth Contributors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,89 @@
+# Hermes Client
+
+[Pyth Network](https://pyth.network/) provides real-time pricing data in a variety of asset classes, including cryptocurrency, equities, FX and commodities.
+These prices are available either via HTTP or Streaming from [Hermes](/apps/hermes).
+This library is a client for interacting with Hermes, allowing your application to consume Pyth real-time prices in on- and off-chain Javascript/Typescript applications.
+
+## Installation
+
+### npm
+
+```
+$ npm install --save @pythnetwork/hermes-client
+```
+
+### Yarn
+
+```
+$ yarn add @pythnetwork/hermes-client
+```
+
+## Quickstart
+
+Typical usage of the connection is along the following lines:
+
+```typescript
+const connection = new HermesClient("https://hermes.pyth.network", {}); // See Hermes endpoints section below for other endpoints
+
+const priceIds = [
+  // You can find the ids of prices at https://pyth.network/developers/price-feed-ids
+  "0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43", // BTC/USD price id
+  "0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace", // ETH/USD price id
+];
+
+// Get price feeds
+const priceFeeds = await connection.getPriceFeeds("btc", "crypto");
+console.log(priceFeeds);
+
+// Latest price updates
+const priceUpdates = await connection.getLatestPriceUpdates(priceIds);
+console.log(priceUpdates);
+```
+
+`HermesClient` also allows subscribing to real-time price updates over a Server-Sent Events (SSE) connection:
+
+```typescript
+// Streaming price updates
+const eventSource = await connection.getStreamingPriceUpdates(priceIds);
+
+eventSource.onmessage = (event) => {
+  console.log("Received price update:", event.data);
+};
+
+eventSource.onerror = (error) => {
+  console.error("Error receiving updates:", error);
+  eventSource.close();
+};
+
+await sleep(5000);
+
+// To stop listening to the updates, you can call eventSource.close();
+console.log("Closing event source.");
+eventSource.close();
+```
+
+### On-chain Applications
+
+On-chain applications will need to submit the price updates returned by Hermes to the Pyth contract on their blockchain.
+By default, these updates are returned as binary data and is serialized as either a base64 string or a hex string depending on the chosen encoding. This binary data will need to be submitted to the Pyth contract.
+
+### 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:
+
+```bash
+npm run example -- \
+  --endpoint https://hermes.pyth.network \
+  --price-ids \
+    0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43 \
+    0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace
+```
+
+## Hermes endpoints
+
+Pyth offers a free public endpoint at [https://hermes.pyth.network](https://hermes.pyth.network). However, it is
+recommended to obtain a private endpoint from one of the Hermes RPC providers for more reliability. You can find more
+information about Hermes RPC providers
+[here](https://docs.pyth.network/documentation/pythnet-price-feeds/hermes#public-endpoint).

package/lib/HermesClient.d.ts

@@ -0,0 +1,107 @@
+import EventSource from "eventsource";
+import { schemas } from "./zodSchemas";
+import { z } from "zod";
+export type AssetType = z.infer<typeof schemas.AssetType>;
+export type BinaryPriceUpdate = z.infer<typeof schemas.BinaryPriceUpdate>;
+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 UnixTimestamp = number;
+export type DurationInSeconds = number;
+export type HexString = string;
+export type DurationInMs = number;
+export type HermesClientConfig = {
+    timeout?: DurationInMs;
+    /**
+     * Number of times a HTTP request will be retried before the API returns a failure. Default: 3.
+     *
+     * The connection uses exponential back-off for the delay between retries. However,
+     * it will timeout regardless of the retries at the configured `timeout` time.
+     */
+    httpRetries?: number;
+};
+export declare class HermesClient {
+    private baseURL;
+    private timeout;
+    private httpRetries;
+    /**
+     * Constructs a new Connection.
+     *
+     * @param endpoint endpoint URL to the price service. Example: https://website/example/
+     * @param config Optional HermesClientConfig for custom configurations.
+     */
+    constructor(endpoint: string, config?: HermesClientConfig);
+    private httpRequest;
+    /**
+     * Fetch the set of available price feeds.
+     * This endpoint can be filtered by asset type and query string.
+     * This will throw an error if there is a network problem or the price service returns a non-ok response.
+     *
+     * @param options Optional parameters:
+     *        - query: String to filter the price feeds. If provided, the results will be filtered to all price feeds whose symbol contains the query string. Query string is case insensitive. Example: "bitcoin".
+     *        - filter: String to filter the price feeds by asset type. Possible values are "crypto", "equity", "fx", "metal", "rates". Filter string is case insensitive.
+     *
+     * @returns Array of PriceFeedMetadata objects.
+     */
+    getPriceFeeds(options?: {
+        query?: string;
+        filter?: string;
+    }): Promise<PriceFeedMetadata[]>;
+    /**
+     * Fetch the latest price updates 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 parsed price update 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 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.
+     *
+     * @returns PriceUpdate object containing the latest updates.
+     */
+    getLatestPriceUpdates(ids: HexString[], options?: {
+        encoding?: EncodingType;
+        parsed?: boolean;
+    }): Promise<PriceUpdate>;
+    /**
+     * Fetch the price updates for a set of price feed IDs at a given timestamp.
+     * This endpoint can be customized by specifying the encoding type and whether the results should also return the parsed price update.
+     * This will throw an error if there is a network problem or the price service returns a non-ok response.
+     *
+     * @param publishTime Unix timestamp in seconds.
+     * @param ids Array of hex-encoded price feed IDs for which updates are requested.
+     * @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.
+     *
+     * @returns PriceUpdate object containing the updates at the specified timestamp.
+     */
+    getPriceUpdatesAtTimestamp(publishTime: UnixTimestamp, ids: HexString[], options?: {
+        encoding?: EncodingType;
+        parsed?: boolean;
+    }): Promise<PriceUpdate>;
+    /**
+     * Fetch streaming price updates for a set of price feed IDs.
+     * This endpoint can be customized by specifying the encoding type, whether the results should include parsed updates,
+     * and if unordered updates or only benchmark updates are allowed.
+     * 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.
+     * @returns An EventSource instance for receiving streaming updates.
+     */
+    getPriceUpdatesStream(ids: HexString[], options?: {
+        encoding?: EncodingType;
+        parsed?: boolean;
+        allow_unordered?: boolean;
+        benchmarks_only?: boolean;
+    }): Promise<EventSource>;
+    private appendUrlSearchParams;
+}
+//# sourceMappingURL=HermesClient.d.ts.map

package/lib/HermesClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HermesClient.d.ts","sourceRoot":"","sources":["../src/HermesClient.ts"],"names":[],"mappings":"AAAA,OAAO,WAAW,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,OAAO,CAAC,SAAS,CAAC,CAAC;AAC1D,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAC1E,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,OAAO,CAAC,YAAY,CAAC,CAAC;AAChE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAC1E,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,OAAO,CAAC,YAAY,CAAC,CAAC;AAChE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,OAAO,CAAC,WAAW,CAAC,CAAC;AAK9D,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC;AACnC,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC;AACvC,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAC/B,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC,MAAM,MAAM,kBAAkB,GAAG;IAE/B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,WAAW,CAAS;IAE5B;;;;;OAKG;gBACS,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,kBAAkB;YAM3C,WAAW;IAqCzB;;;;;;;;;;OAUG;IACG,aAAa,CAAC,OAAO,CAAC,EAAE;QAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAWhC;;;;;;;;;;;OAWG;IACG,qBAAqB,CACzB,GAAG,EAAE,SAAS,EAAE,EAChB,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,EAAE,YAAY,CAAC;QACxB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,GACA,OAAO,CAAC,WAAW,CAAC;IAavB;;;;;;;;;;;;OAYG;IACG,0BAA0B,CAC9B,WAAW,EAAE,aAAa,EAC1B,GAAG,EAAE,SAAS,EAAE,EAChB,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,EAAE,YAAY,CAAC;QACxB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,GACA,OAAO,CAAC,WAAW,CAAC;IAavB;;;;;;;;;;;;;;OAcG;IACG,qBAAqB,CACzB,GAAG,EAAE,SAAS,EAAE,EAChB,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,EAAE,YAAY,CAAC;QACxB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;KAC3B,GACA,OAAO,CAAC,WAAW,CAAC;IAavB,OAAO,CAAC,qBAAqB;CAU9B"}

package/lib/HermesClient.js

@@ -0,0 +1,149 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HermesClient = void 0;
+const eventsource_1 = __importDefault(require("eventsource"));
+const zodSchemas_1 = require("./zodSchemas");
+const DEFAULT_TIMEOUT = 5000;
+const DEFAULT_HTTP_RETRIES = 3;
+class HermesClient {
+    baseURL;
+    timeout;
+    httpRetries;
+    /**
+     * Constructs a new Connection.
+     *
+     * @param endpoint endpoint URL to the price service. Example: https://website/example/
+     * @param config Optional HermesClientConfig for custom configurations.
+     */
+    constructor(endpoint, config) {
+        this.baseURL = endpoint;
+        this.timeout = config?.timeout ?? DEFAULT_TIMEOUT;
+        this.httpRetries = config?.httpRetries ?? DEFAULT_HTTP_RETRIES;
+    }
+    async httpRequest(url, schema, options, retries = this.httpRetries, backoff = 100 + Math.floor(Math.random() * 100), // Adding randomness to the initial backoff to avoid "thundering herd" scenario where a lot of clients that get kicked off all at the same time (say some script or something) and fail to connect all retry at exactly the same time too
+    externalAbortController) {
+        const controller = externalAbortController ?? new AbortController();
+        const { signal } = controller;
+        options = { ...options, signal }; // Merge any existing options with the signal
+        // Set a timeout to abort the request if it takes too long
+        const timeout = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            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 data = await response.json();
+            return schema.parse(data);
+        }
+        catch (error) {
+            clearTimeout(timeout);
+            if (retries > 0 &&
+                !(error instanceof Error && error.name === "AbortError")) {
+                // Wait for a backoff period before retrying
+                await new Promise((resolve) => setTimeout(resolve, backoff));
+                return this.httpRequest(url, schema, options, retries - 1, backoff * 2); // Exponential backoff
+            }
+            throw error;
+        }
+    }
+    /**
+     * Fetch the set of available price feeds.
+     * This endpoint can be filtered by asset type and query string.
+     * This will throw an error if there is a network problem or the price service returns a non-ok response.
+     *
+     * @param options Optional parameters:
+     *        - query: String to filter the price feeds. If provided, the results will be filtered to all price feeds whose symbol contains the query string. Query string is case insensitive. Example: "bitcoin".
+     *        - filter: String to filter the price feeds by asset type. Possible values are "crypto", "equity", "fx", "metal", "rates". Filter string is case insensitive.
+     *
+     * @returns Array of PriceFeedMetadata objects.
+     */
+    async getPriceFeeds(options) {
+        const url = new URL("/v2/price_feeds", this.baseURL);
+        if (options) {
+            this.appendUrlSearchParams(url, options);
+        }
+        return await this.httpRequest(url.toString(), zodSchemas_1.schemas.PriceFeedMetadata.array());
+    }
+    /**
+     * Fetch the latest price updates 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 parsed price update 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 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.
+     *
+     * @returns PriceUpdate object containing the latest updates.
+     */
+    async getLatestPriceUpdates(ids, options) {
+        const url = new URL(`${this.baseURL}/v2/updates/price/latest`);
+        for (const id of ids) {
+            url.searchParams.append("ids[]", id);
+        }
+        if (options) {
+            this.appendUrlSearchParams(url, options);
+        }
+        return this.httpRequest(url.toString(), zodSchemas_1.schemas.PriceUpdate);
+    }
+    /**
+     * Fetch the price updates for a set of price feed IDs at a given timestamp.
+     * This endpoint can be customized by specifying the encoding type and whether the results should also return the parsed price update.
+     * This will throw an error if there is a network problem or the price service returns a non-ok response.
+     *
+     * @param publishTime Unix timestamp in seconds.
+     * @param ids Array of hex-encoded price feed IDs for which updates are requested.
+     * @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.
+     *
+     * @returns PriceUpdate object containing the updates at the specified timestamp.
+     */
+    async getPriceUpdatesAtTimestamp(publishTime, ids, options) {
+        const url = new URL(`${this.baseURL}/v2/updates/price/${publishTime}`);
+        for (const id of ids) {
+            url.searchParams.append("ids[]", id);
+        }
+        if (options) {
+            this.appendUrlSearchParams(url, options);
+        }
+        return this.httpRequest(url.toString(), zodSchemas_1.schemas.PriceUpdate);
+    }
+    /**
+     * Fetch streaming price updates for a set of price feed IDs.
+     * This endpoint can be customized by specifying the encoding type, whether the results should include parsed updates,
+     * and if unordered updates or only benchmark updates are allowed.
+     * 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.
+     * @returns An EventSource instance for receiving streaming updates.
+     */
+    async getPriceUpdatesStream(ids, options) {
+        const url = new URL("/v2/updates/price/stream", this.baseURL);
+        ids.forEach((id) => {
+            url.searchParams.append("ids[]", id);
+        });
+        if (options) {
+            this.appendUrlSearchParams(url, options);
+        }
+        return new eventsource_1.default(url.toString());
+    }
+    appendUrlSearchParams(url, params) {
+        Object.entries(params).forEach(([key, value]) => {
+            if (value !== undefined) {
+                url.searchParams.append(key, String(value));
+            }
+        });
+    }
+}
+exports.HermesClient = HermesClient;

package/lib/examples/HermesClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HermesClient.d.ts","sourceRoot":"","sources":["../../src/examples/HermesClient.ts"],"names":[],"mappings":""}

package/lib/examples/HermesClient.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const yargs_1 = __importDefault(require("yargs"));
+const helpers_1 = require("yargs/helpers");
+const HermesClient_1 = require("../HermesClient");
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+const argv = (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
+    .option("endpoint", {
+    description: "Endpoint URL for the price service. e.g: https://endpoint/example",
+    type: "string",
+    required: true,
+})
+    .option("price-ids", {
+    description: "Space separated price feed ids (in hex without leading 0x) to fetch." +
+        " e.g: f9c0172ba10dfa4d19088d...",
+    type: "array",
+    required: true,
+})
+    .help()
+    .alias("help", "h")
+    .parserConfiguration({
+    "parse-numbers": false,
+})
+    .parseSync();
+async function run() {
+    const connection = new HermesClient_1.HermesClient(argv.endpoint);
+    const priceIds = argv.priceIds;
+    // Get price feeds
+    const priceFeeds = await connection.getPriceFeeds({
+        query: "btc",
+        filter: "crypto",
+    });
+    console.log(priceFeeds);
+    // Latest price updates
+    const priceUpdates = await connection.getLatestPriceUpdates(priceIds);
+    console.log(priceUpdates);
+    // Streaming price updates
+    const eventSource = await connection.getPriceUpdatesStream(priceIds);
+    eventSource.onmessage = (event) => {
+        console.log("Received price update:", event.data);
+    };
+    eventSource.onerror = (error) => {
+        console.error("Error receiving updates:", error);
+        eventSource.close();
+    };
+    await sleep(5000);
+    // To stop listening to the updates, you can call eventSource.close();
+    console.log("Closing event source.");
+    eventSource.close();
+}
+run();