Skip to content

Commit 5a2e4a8

Browse files
cprussincprussin
authored
Merge pull request #1796 from pyth-network/chore-api-reference-refactor
(refactor:api-reference) New text.
2 parents 2c4bc07 + f3d55ab commit 5a2e4a8

25 files changed

+520
-384
lines changed

‎apps/api-reference/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
},
99
"scripts": {
1010
"build": "next build",
11-
"fix": "pnpm fix:format && pnpm fix:lint",
11+
"fix": "pnpm fix:lint && pnpm fix:format",
1212
"fix:format": "prettier --write .",
1313
"fix:lint": "eslint --fix .",
1414
"pull:env": "VERCEL_ORG_ID=team_BKQrg3JJFLxZyTqpuYtIY0rj VERCEL_PROJECT_ID=prj_gbljYVzp0m5EpCuOF6nZpM4WMFM6 vercel env pull",

‎apps/api-reference/src/apis/evm/get-ema-price-no-older-than.ts‎

Lines changed: 33 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -6,28 +6,41 @@ export const getEmaPriceNoOlderThan = readApi<"id" | "age">({
66
summary:
77
"Get the exponentially weighted moving average (EMA) price object with a published timestamp from before than `age` seconds in the past.",
88
description: `
9-
Get the latest exponentially-weighted moving average (EMA) price and confidence
10-
interval for the requested price feed id. The price feed id is a 32-byte id
11-
written as a hexadecimal string; see the [price feed
12-
ids](https://pyth.network/developers/price-feed-ids) page to look up the id for
13-
a given symbol. The returned price and confidence are decimal numbers written
14-
in the form \`a * 10^e\`, where \`e\` is an exponent included in the result.
15-
For example, a price of 1234 with an exponent of -2 represents the number 12.34.
16-
The result also includes a \`publishTime\` which is the unix timestamp for the
17-
price update. The EMA methodology is described in more detail in this [blog
18-
post](https://pythnetwork.medium.com/whats-in-a-name-302a03e6c3e1).
9+
This method returns the latest price object containing **exponentially-weighted moving average** price for the requested price feed ID, if
10+
it has been updated sufficiently recently.
1911
20-
The caller provides an \`age\` argument that specifies how old the price can be.
21-
The call reverts with a \`StalePriceError\` if the on-chain price is from more
22-
than \`age\` seconds in the past (with respect to the current on-chain
23-
timestamp). Call [updatePriceFeeds](updatePriceFeeds) to pull a fresh price
24-
on-chain and solve this problem.
12+
The caller provides an **\`age\`** argument that specifies how old the price can be.
2513
26-
This function reverts with a \`PriceFeedNotFound\` error if the requested feed
27-
id has never received a price update. This error could either mean that the
28-
provided price feed id is incorrect, or (more typically) that this is the first
29-
attempted use of that feed on-chain. In the second case, calling
30-
[updatePriceFeeds](updatePriceFeeds) will solve this problem.
14+
The price object contains the following fields:
15+
1. \`price\`: The latest price of the price feed.
16+
2. \`conf\`: The confidence level of the price feed.
17+
3. \`expo\`: The exponent of the price feed.
18+
4. \`publishtime\`: The time when the price feed was last updated.
19+
20+
Sample \`price\` object:
21+
\`\`\`json
22+
{
23+
price: 123456789n,
24+
conf: 180726074n,
25+
expo: -8,
26+
publishTime: 1721765108n
27+
}
28+
\`\`\`
29+
30+
The \`price\` above is in the format of \`price * 10^expo\`. So, the \`price\` in above
31+
mentioned sample represents the number \`123456789 * 10(-8) = 1.23456789\` in
32+
this case.
33+
34+
### Error Response
35+
36+
The above method can return the following error response:
37+
- \`StalePrice\`: The on-chain price has not been updated within the last
38+
[\`getValidTimePeriod()\`](getValidTimePeriod) seconds. Try calling
39+
[\`updatePriceFeeds()\`](updatePriceFeeds) to update the price feed with the
40+
latest price.
41+
- \`PriceFeedNotFound\`: The requested price feed has never received a price
42+
update or does not exist. Try calling
43+
[\`updatePriceFeeds()\`](updatePriceFeeds) to update the price feed.
3144
`,
3245
parameters: [
3346
{

‎apps/api-reference/src/apis/evm/get-ema-price-unsafe.ts‎

Lines changed: 34 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -6,26 +6,42 @@ export const getEmaPriceUnsafe = readApi<"id">({
66
summary:
77
"Get the **last updated** exponentially weighted moving average (EMA) price object for the requested price feed ID. _Caution: This function may return a price arbitrarily in the past_",
88
description: `
9-
Get the latest exponentially-weighted moving average (EMA) price and confidence
10-
interval for the requested price feed id. The price feed id is a 32-byte id
11-
written as a hexadecimal string; see the [price feed
12-
ids](https://pyth.network/developers/price-feed-ids) page to look up the id for
13-
a given symbol. The returned price and confidence are decimal numbers written
14-
in the form \`a * 10^e\`, where \`e\` is an exponent included in the result.
15-
For example, a price of 1234 with an exponent of -2 represents the number 12.34.
16-
The result also includes a \`publishTime\` which is the unix timestamp for the
17-
price update. The EMA methodology is described in more detail in this [blog
18-
post](https://pythnetwork.medium.com/whats-in-a-name-302a03e6c3e1).
9+
This method returns the price object containing **last updated** exponentially-weighted moving average(EMA) price for the requested price feed ID.
1910
20-
**This function may return a price from arbitrarily far in the past.** It is the
21-
caller's responsibility to check the returned \`publishTime\` to ensure that the
22-
update is recent enough for their use case.
11+
**This function may return a price from arbitrarily far in the past.** It is the
12+
caller's responsibility to check the returned \`publishTime\` to ensure that the
13+
update is recent enough for their use case. If you need the latest price, update the price using [\`updatePriceFeeds()\`](updatePriceFeeds) and then call [\`getEmaPrice()\`](getEmaPrice).
2314
24-
This function reverts with a \`PriceFeedNotFound\` error if the requested feed
25-
id has never received a price update. This error could either mean that the
26-
provided price feed id is incorrect, or (more typically) that this is the first
27-
attempted use of that feed on-chain. In the second case, calling
28-
[updatePriceFeeds](updatePriceFeeds) will solve this problem.
15+
The price object contains the following fields:
16+
1. \`price\`: The latest price of the price feed.
17+
2. \`conf\`: The confidence level of the price feed.
18+
3. \`expo\`: The exponent of the price feed.
19+
4. \`publishtime\`: The time when the price feed was last updated.
20+
21+
Sample \`price\` object:
22+
\`\`\`json
23+
{
24+
price: 123456789n,
25+
conf: 180726074n,
26+
expo: -8,
27+
publishTime: 1721765108n
28+
}
29+
\`\`\`
30+
31+
The \`price\` above is in the format of \`price * 10^expo\`. So, the \`price\` in above
32+
mentioned sample represents the number \`123456789 * 10(-8) = 1.23456789\` in
33+
this case.
34+
35+
### Error Response
36+
37+
The above method can return the following error response:
38+
- \`StalePrice\`: The on-chain price has not been updated within the last
39+
[\`getValidTimePeriod()\`](getValidTimePeriod) seconds. Try calling
40+
[\`updatePriceFeeds()\`](updatePriceFeeds) to update the price feed with the
41+
latest price.
42+
- \`PriceFeedNotFound\`: The requested price feed has never received a price
43+
update or does not exist. Try calling
44+
[\`updatePriceFeeds()\`](updatePriceFeeds) to update the price feed.
2945
`,
3046
parameters: [
3147
{

‎apps/api-reference/src/apis/evm/get-ema-price.ts‎

Lines changed: 29 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -6,31 +6,37 @@ export const getEmaPrice = readApi<"id">({
66
summary:
77
"Get the **latest** exponentially weighted moving average (EMA) price object for the requested price feed ID.",
88
description: `
9-
Get the latest exponentially-weighted moving average (EMA) price and confidence
10-
interval for the requested price feed id. The price feed id is a 32-byte id
11-
written as a hexadecimal string; see the [price feed
12-
ids](https://pyth.network/developers/price-feed-ids) page to look up the id for
13-
a given symbol. The returned price and confidence are decimal numbers written
14-
in the form \`a * 10^e\`, where \`e\` is an exponent included in the result.
15-
For example, a price of 1234 with an exponent of -2 represents the number 12.34.
16-
The result also includes a \`publishTime\` which is the unix timestamp for the
17-
price update. The EMA methodology is described in more detail in this [blog
18-
post](https://pythnetwork.medium.com/whats-in-a-name-302a03e6c3e1).
9+
This method returns the latest price object containing **exponentially-weighted moving average** price for the requested price feed ID.
10+
The \`price\` object contains the following fields:
11+
1. \`price\`: The latest **EMA** price of the price feed.
12+
2. \`conf\`: The confidence level of the price feed.
13+
3. \`expo\`: The exponent of the price feed.
14+
4. \`publishtime\`: The time when the price feed was last updated.
1915
20-
This function reverts with a \`StalePrice\` error if the on-chain price has not
21-
been updated within the last [getValidTimePeriod()](getValidTimePeriod) seconds.
22-
The default valid time period is set to a reasonable default on each chain and
23-
is typically around 1 minute. Call [updatePriceFeeds](updatePriceFeeds) to pull
24-
a fresh price on-chain and solve this problem. If you would like to configure
25-
the valid time period, see [getEmaPriceNoOlderThan](getEmaPriceNoOlderThan). If
26-
you want the latest price regardless of when it was updated, see
27-
[getEmaPriceUnsafe](getEmaPriceUnsafe).
16+
Sample price object:
17+
\`\`\`json
18+
{
19+
price: 123456789n,
20+
conf: 180726074n,
21+
expo: -8,
22+
publishTime: 1721765108n
23+
}
24+
\`\`\`
2825
29-
This function reverts with a \`PriceFeedNotFound\` error if the requested feed
30-
id has never received a price update. This error could either mean that the
31-
provided price feed id is incorrect, or (more typically) that this is the first
32-
attempted use of that feed on-chain. In the second case, calling
33-
[updatePriceFeeds](updatePriceFeeds) will solve this problem.
26+
The \`price\` above is in the format of \`price * 10^expo\`. So, the \`price\` in above
27+
mentioned sample represents the number \`123456789 * 10(-8) = 1.23456789\` in
28+
this case.
29+
30+
### Error Response
31+
32+
The above method can return the following error response:
33+
- \`StalePrice\`: The on-chain price has not been updated within the last
34+
[\`getValidTimePeriod()\`](getValidTimePeriod) seconds. Try calling
35+
[\`updatePriceFeeds()\`](updatePriceFeeds) to update the price feed with the
36+
latest price.
37+
- \`PriceFeedNotFound\`: The requested price feed has never received a price
38+
update or does not exist. Try calling
39+
[\`updatePriceFeeds()\`](updatePriceFeeds) to update the price feed.
3440
`,
3541
parameters: [
3642
{

‎apps/api-reference/src/apis/evm/get-price-no-older-than.ts‎

Lines changed: 33 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -6,27 +6,41 @@ export const getPriceNoOlderThan = readApi<"id" | "age">({
66
summary:
77
"Get the price object with a published timestamp from before than `age` seconds in the past.",
88
description: `
9-
Get the latest price and confidence interval for the requested price feed id, if
10-
it has been updated sufficiently recently. The price feed id is a 32-byte id
11-
written as a hexadecimal string; see the [price feed
12-
ids](https://pyth.network/developers/price-feed-ids) page to look up the id for
13-
a given symbol. The returned price and confidence are decimal numbers written
14-
in the form \`a * 10^e\`, where \`e\` is an exponent included in the result.
15-
For example, a price of 1234 with an exponent of -2 represents the number 12.34.
16-
The result also includes a \`publishTime\` which is the unix timestamp for the
17-
price update.
9+
This method returns the latest price object for the requested price feed ID, if
10+
it has been updated sufficiently recently.
1811
19-
The caller provides an \`age\` argument that specifies how old the price can be.
20-
The call reverts with a \`StalePriceError\` if the on-chain price is from more
21-
than \`age\` seconds in the past (with respect to the current on-chain
22-
timestamp). Call [updatePriceFeeds](updatePriceFeeds) to pull a fresh price
23-
on-chain and solve this problem.
12+
The caller provides an **\`age\`** argument that specifies how old the price can be.
2413
25-
This function reverts with a \`PriceFeedNotFound\` error if the requested feed
26-
id has never received a price update. This error could either mean that the
27-
provided price feed id is incorrect, or (more typically) that this is the first
28-
attempted use of that feed on-chain. In the second case, calling
29-
[updatePriceFeeds](updatePriceFeeds) will solve this problem.
14+
The price object contains the following fields:
15+
1. \`price\`: The latest price of the price feed.
16+
2. \`conf\`: The confidence level of the price feed.
17+
3. \`expo\`: The exponent of the price feed.
18+
4. \`publishtime\`: The time when the price feed was last updated.
19+
20+
Sample \`price\` object:
21+
\`\`\`json
22+
{
23+
price: 123456789n,
24+
conf: 180726074n,
25+
expo: -8,
26+
publishTime: 1721765108n
27+
}
28+
\`\`\`
29+
30+
The \`price\` above is in the format of \`price * 10^expo\`. So, the \`price\` in above
31+
mentioned sample represents the number \`123456789 * 10(-8) = 1.23456789\` in
32+
this case.
33+
34+
### Error Response
35+
36+
The above method can return the following error response:
37+
- \`StalePrice\`: The on-chain price has not been updated within the last
38+
[\`getValidTimePeriod()\`](getValidTimePeriod) seconds. Try calling
39+
[\`updatePriceFeeds()\`](updatePriceFeeds) to update the price feed with the
40+
latest price.
41+
- \`PriceFeedNotFound\`: The requested price feed has never received a price
42+
update or does not exist. Try calling
43+
[\`updatePriceFeeds()\`](updatePriceFeeds) to update the price feed.
3044
`,
3145
parameters: [
3246
{

‎apps/api-reference/src/apis/evm/get-price-unsafe.ts‎

Lines changed: 35 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -6,25 +6,43 @@ export const getPriceUnsafe = readApi<"id">({
66
summary:
77
"Get the **last updated** price object for the requested price feed ID. _Caution: This function may return a price from arbitrarily in the the past_",
88
description: `
9-
Get the latest price and confidence interval for the requested price feed id.
10-
The price feed id is a 32-byte id written as a hexadecimal string; see the
11-
[price feed ids](https://pyth.network/developers/price-feed-ids) page to look up
12-
the id for a given symbol. The returned price and confidence are decimal numbers
13-
written in the form \`a * 10^e\`, where \`e\` is an exponent included in the
14-
result. For example, a price of 1234 with an exponent of -2 represents the
15-
number 12.34. The result also includes a \`publishTime\` which is the unix
16-
timestamp for the price update.
9+
This method returns the price object containing **last updated** price for the requested price feed ID.
1710
18-
**This function may return a price from arbitrarily far in the past.** It is the
19-
caller's responsibility to check the returned \`publishTime\` to ensure that the
20-
update is recent enough for their use case.
11+
**This function may return a price from arbitrarily far in the past.** It is the
12+
caller's responsibility to check the returned \`publishTime\` to ensure that the
13+
update is recent enough for their use case. If you need the latest price, update the price using [\`updatePriceFeeds()\`](updatePriceFeeds) and then call [\`getPrice()\`](getPrice).
2114
22-
This function reverts with a \`PriceFeedNotFound\` error if the requested feed
23-
id has never received a price update. This error could either mean that the
24-
provided price feed id is incorrect, or (more typically) that this is the first
25-
attempted use of that feed on-chain. In the second case, calling
26-
[updatePriceFeeds](updatePriceFeeds) will solve this problem.
27-
`,
15+
The price object contains the following fields:
16+
1. \`price\`: The latest price of the price feed.
17+
2. \`conf\`: The confidence level of the price feed.
18+
3. \`expo\`: The exponent of the price feed.
19+
4. \`publishtime\`: The time when the price feed was last updated.
20+
21+
Sample \`price\` object:
22+
\`\`\`json
23+
{
24+
price: 123456789n,
25+
conf: 180726074n,
26+
expo: -8,
27+
publishTime: 1721765108n
28+
}
29+
\`\`\`
30+
31+
The \`price\` above is in the format of \`price * 10^expo\`. So, the \`price\` in above
32+
mentioned sample represents the number \`123456789 * 10(-8) = 1.23456789\` in
33+
this case.
34+
35+
### Error Response
36+
37+
The above method can return the following error response:
38+
- \`StalePrice\`: The on-chain price has not been updated within the last
39+
[\`getValidTimePeriod()\`](getValidTimePeriod) seconds. Try calling
40+
[\`updatePriceFeeds()\`](updatePriceFeeds) to update the price feed with the
41+
latest price.
42+
- \`PriceFeedNotFound\`: The requested price feed has never received a price
43+
update or does not exist. Try calling
44+
[\`updatePriceFeeds()\`](updatePriceFeeds) to update the price feed.
45+
`,
2846
parameters: [
2947
{
3048
name: "id",

‎apps/api-reference/src/apis/evm/get-price.ts‎

Lines changed: 31 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -5,30 +5,39 @@ export const getPrice = readApi<"id">({
55
name: "getPrice",
66
summary: "Get the **latest** price object for the requested price feed ID.",
77
description: `
8-
Get the latest price and confidence interval for the requested price feed id.
9-
The price feed id is a 32-byte id written as a hexadecimal string; see the
10-
[price feed ids](https://pyth.network/developers/price-feed-ids) page to look up
11-
the id for a given symbol. The returned price and confidence are decimal numbers
12-
written in the form \`a * 10^e\`, where \`e\` is an exponent included in the
13-
result. For example, a price of 1234 with an exponent of -2 represents the
14-
number 12.34. The result also includes a \`publishTime\` which is the unix
15-
timestamp for the price update.
8+
This method returns the latest price object for the requested price feed ID.
169
17-
This function reverts with a \`StalePrice\` error if the on-chain price has not
18-
been updated within the last [getValidTimePeriod()](getValidTimePeriod)
19-
seconds. The default valid time period is set to a reasonable default on each
20-
chain and is typically around 1 minute. Call
21-
[updatePriceFeeds](updatePriceFeeds) to pull a fresh price on-chain and solve
22-
this problem. If you would like to configure the valid time period, see
23-
[getPriceNoOlderThan](getPriceNoOlderThan). If you want the latest price
24-
regardless of when it was updated, see [getPriceUnsafe](getPriceUnsafe).
10+
The price object contains the following fields:
11+
1. \`price\`: The latest price of the price feed.
12+
2. \`conf\`: The confidence level of the price feed.
13+
3. \`expo\`: The exponent of the price feed.
14+
4. \`publishtime\`: The time when the price feed was last updated.
2515
26-
This function reverts with a \`PriceFeedNotFound\` error if the requested feed
27-
id has never received a price update. This error could either mean that the
28-
provided price feed id is incorrect, or (more typically) that this is the first
29-
attempted use of that feed on-chain. In the second case, calling
30-
[updatePriceFeeds](updatePriceFeeds) will solve this problem.
31-
`,
16+
Sample \`price\` object:
17+
\`\`\`json
18+
{
19+
price: 123456789n,
20+
conf: 180726074n,
21+
expo: -8,
22+
publishTime: 1721765108n
23+
}
24+
\`\`\`
25+
26+
The \`price\` above is in the format of \`price * 10^expo\`. So, the \`price\` in above
27+
mentioned sample represents the number \`123456789 * 10(-8) = 1.23456789\` in
28+
this case.
29+
30+
### Error Response
31+
32+
The above method can return the following error response:
33+
- \`StalePrice\`: The on-chain price has not been updated within the last
34+
[\`getValidTimePeriod()\`](getValidTimePeriod) seconds. Try calling
35+
[\`updatePriceFeeds()\`](updatePriceFeeds) to update the price feed with the
36+
latest price.
37+
- \`PriceFeedNotFound\`: The requested price feed has never received a price
38+
update or does not exist. Try calling
39+
[\`updatePriceFeeds()\`](updatePriceFeeds) to update the price feed.
40+
`,
3241
parameters: [
3342
{
3443
name: "id",

0 commit comments

Comments
 (0)