# Pyth Aptos JS

[Pyth](https://pyth.network/) provides real-time pricing data in a variety of asset classes, including cryptocurrency, equities, FX and commodities. This library allows you to use these real-time prices on Aptos networks.

## Installation

### npm

```
$ npm install --save @pythnetwork/pyth-aptos-js
```

### Yarn

```
$ yarn add @pythnetwork/pyth-aptos-js
```

## Quickstart

Pyth stores prices off-chain to minimize gas fees, which allows us to offer a wider selection of products and faster update times.
See [On-Demand Updates](https://docs.pyth.network/consume-data/on-demand) for more information about this approach.
To use Pyth prices on chain,
they must be fetched from an off-chain price service. The `AptosPriceServiceConnection` class can be used to interact with these services,
providing a way to fetch these prices directly in your code. The following example wraps an existing RPC provider and shows how to obtain
Pyth prices and submit them to the network:

```typescript
const connection = new AptosPriceServiceConnection(
  "https://xc-testnet.pyth.network"
); // See Price Service endpoints section below for other endpoints

const priceIds = [
  // You can find the ids of prices at https://pyth.network/developers/price-feed-ids#aptos-testnet
  "0xf9c0172ba10dfa4d19088d94f5bf61d3b54d5bd7483a322a982e1373ee8ea31b", // BTC/USD price id in testnet
  "0xca80ba6dc32e08d06f1aa886011eed1d77c77be9eb761cc10d72b7d0a2fd57a6", // ETH/USD price id in testnet
];

// In order to use Pyth prices in your protocol you need to submit the price update data to Pyth contract in your target
// chain. `getPriceUpdateData` creates the update data which can be submitted to your contract. Then your contract should
// call the Pyth Contract with this data.
const priceUpdateData = await connection.getPriceFeedsUpdateData(priceIds);

// Create a transaction and submit to your contract using the price update data
const client = new AptosClient(endpoint);
let result = await client.generateSignSubmitWaitForTransaction(
  sender,
  new TxnBuilderTypes.TransactionPayloadEntryFunction(
    TxnBuilderTypes.EntryFunction.natural(
      "0x..::your_module",
      "do_something",
      [],
      [priceUpdateData]
    )
  )
);
```

`your_module::do_something` should then call `pyth::update_price_feeds` before querying the data using `pyth::get_price`:

```move
module example::your_module {
    use pyth::pyth;
    use pyth::price_identifier;
    use aptos_framework::coin;

    public fun do_something(user: &signer, pyth_update_data: vector<vector<u8>>) {
        // First update the Pyth price feeds. The user pays the fee for the update.
        let coins = coin::withdraw(user, pyth::get_update_fee(pyth_update_data));

        pyth::update_price_feeds(pyth_update_data, coins);

        // Now we can use the prices which we have just updated
        let btc_usd_price_id = price_identifier::from_byte_vec(
            x"e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43");
        let price = pyth::get_price(btc_usd_price_id);

    }
}
```

We strongly recommend reading our guide which explains [how to work with Pyth price feeds](https://docs.pyth.network/consume-data/best-practices).

### Off-chain prices

Many applications additionally need to display Pyth prices off-chain, for example, in their frontend application.
The `AptosPriceServiceConnection` provides two different ways to fetch the current Pyth price.
The code blocks below assume that the `connection` and `priceIds` objects have been initialized as shown above.
The first method is a single-shot query:

```typescript
// `getLatestPriceFeeds` returns a `PriceFeed` for each price id. It contains all information about a price and has
// utility functions to get the current and exponentially-weighted moving average price, and other functionality.
const priceFeeds = await connection.getLatestPriceFeeds(priceIds);
// Get the price if it is not older than 60 seconds from the current time.
console.log(priceFeeds[0].getPriceNoOlderThan(60)); // Price { conf: '1234', expo: -8, price: '12345678' }
// Get the exponentially-weighted moving average price if it is not older than 60 seconds from the current time.
console.log(priceFeeds[1].getEmaPriceNoOlderThan(60));
```

The object also supports a streaming websocket connection that allows you to subscribe to every new price update for a given feed.
This method is useful if you want to show continuously updating real-time prices in your frontend:

```typescript
// Subscribe to the price feeds given by `priceId`. The callback will be invoked every time the requested feed
// gets a price update.
connection.subscribePriceFeedUpdates(priceIds, (priceFeed) => {
  console.log(
    `Received update for ${priceFeed.id}: ${priceFeed.getPriceNoOlderThan(60)}`
  );
});

// When using the subscription, make sure to close the websocket upon termination to finish the process gracefully.
setTimeout(() => {
  connection.closeWebSocket();
}, 60000);
```

### Example

[This example](./src/examples/AptosRelay.ts) shows how to update prices on an Aptos network. It does the following:

1. Fetches update data from the Price Service for the given price feeds.
2. Calls the Pyth Aptos contract with the update data.

You can run this example with `npm run example-relay`. A full command that updates BTC and ETH prices on the BNB Chain testnet network looks like this:

```bash
export APTOS_KEY = "0x...";
npm run example-relay -- --endpoint https://xc-testnet.pyth.network --price-ids 0xf9c0172ba10dfa4d19088d94f5bf61d3b54d5bd7483a322a982e1373ee8ea31b 0xca80ba6dc32e08d06f1aa886011eed1d77c77be9eb761cc10d72b7d0a2fd57a6 --full-node https://fullnode.testnet.aptoslabs.com/v1 --pyth-contract 0xaa706d631cde8c634fe1876b0c93e4dec69d0c6ccac30a734e9e257042e81541
```

## Price Service endpoints

We provide public endpoints for the price service, although it is strongly recommended to host your own instance.

| Aptos Network | Price Service URL               |
| ------------- | ------------------------------- |
| Testnet       | https://xc-testnet.pyth.network |
| Mainnet       | https://xc-mainnet.pyth.network |
