|
| 1 | +# Hermes Client |
| 2 | + |
| 3 | +[Pyth Network](https://pyth.network/) provides real-time pricing data in a variety of asset classes, including cryptocurrency, equities, FX and commodities. |
| 4 | +These prices are available either via HTTP or Streaming from [Hermes](/apps/hermes). |
| 5 | +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. |
| 6 | + |
| 7 | +## Installation |
| 8 | + |
| 9 | +### npm |
| 10 | + |
| 11 | +``` |
| 12 | +$ npm install --save @pythnetwork/hermes-client |
| 13 | +``` |
| 14 | + |
| 15 | +### Yarn |
| 16 | + |
| 17 | +``` |
| 18 | +$ yarn add @pythnetwork/hermes-client |
| 19 | +``` |
| 20 | + |
| 21 | +## Quickstart |
| 22 | + |
| 23 | +Typical usage of the connection is along the following lines: |
| 24 | + |
| 25 | +```typescript |
| 26 | +const connection = new HermesClient("https://hermes.pyth.network", {}); // See Hermes endpoints section below for other endpoints |
| 27 | + |
| 28 | +const priceIds = [ |
| 29 | + // You can find the ids of prices at https://pyth.network/developers/price-feed-ids |
| 30 | + "0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43", // BTC/USD price id |
| 31 | + "0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace", // ETH/USD price id |
| 32 | +]; |
| 33 | + |
| 34 | +// Get price feeds |
| 35 | +const priceFeeds = await connection.getPriceFeeds("btc", "crypto"); |
| 36 | +console.log(priceFeeds); |
| 37 | + |
| 38 | +// Latest price updates |
| 39 | +const priceUpdates = await connection.getLatestPriceUpdates(priceIds); |
| 40 | +console.log(priceUpdates); |
| 41 | +``` |
| 42 | + |
| 43 | +`HermesClient` also allows subscribing to real-time price updates over a Server-Sent Events (SSE) connection: |
| 44 | + |
| 45 | +```typescript |
| 46 | +// Streaming price updates |
| 47 | +const eventSource = await connection.getStreamingPriceUpdates(priceIds); |
| 48 | + |
| 49 | +eventSource.onmessage = (event) => { |
| 50 | + console.log("Received price update:", event.data); |
| 51 | +}; |
| 52 | + |
| 53 | +eventSource.onerror = (error) => { |
| 54 | + console.error("Error receiving updates:", error); |
| 55 | + eventSource.close(); |
| 56 | +}; |
| 57 | + |
| 58 | +await sleep(5000); |
| 59 | + |
| 60 | +// To stop listening to the updates, you can call eventSource.close(); |
| 61 | +console.log("Closing event source."); |
| 62 | +eventSource.close(); |
| 63 | +``` |
| 64 | + |
| 65 | +### On-chain Applications |
| 66 | + |
| 67 | +On-chain applications will need to submit the price updates returned by Hermes to the Pyth contract on their blockchain. |
| 68 | +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. |
| 69 | + |
| 70 | +### Examples |
| 71 | + |
| 72 | +The [HermesClient](./src/examples/HermesClient.ts) example demonstrates both the examples above. |
| 73 | +You can run it with `npm run example`. |
| 74 | +A full command that prints BTC and ETH price feeds, in the testnet network, looks like so: |
| 75 | + |
| 76 | +```bash |
| 77 | +npm run example -- \ |
| 78 | + --endpoint https://hermes.pyth.network \ |
| 79 | + --price-ids \ |
| 80 | + 0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43 \ |
| 81 | + 0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace |
| 82 | +``` |
| 83 | + |
| 84 | +## Hermes endpoints |
| 85 | + |
| 86 | +Pyth offers a free public endpoint at [https://hermes.pyth.network](https://hermes.pyth.network). However, it is |
| 87 | +recommended to obtain a private endpoint from one of the Hermes RPC providers for more reliability. You can find more |
| 88 | +information about Hermes RPC providers |
| 89 | +[here](https://docs.pyth.network/documentation/pythnet-price-feeds/hermes#public-endpoint). |
0 commit comments