internet-court/internet-court-skill / vendored/sendaifun/pyth
pyth
VerifiedComplete guide for Pyth Network - decentralized oracle providing real-time price feeds for DeFi. Covers price feed integration, confidence intervals, EMA prices, on-chain CPI, off-chain fetching, and streaming updates for Solana applications.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 11.1 KB |
| SKILL.md | skill md | 15.3 KB |
| docs/troubleshooting.md | markdown | 11.4 KB |
| examples/on-chain/anchor-integration.rs | script | 8.9 KB |
| examples/on-chain/price-validation.rs | script | 12.7 KB |
| examples/price-feeds/fetch-price.ts | script | 3.0 KB |
| examples/price-feeds/multiple-prices.ts | script | 5.7 KB |
| examples/streaming/real-time-updates.ts | script | 9.8 KB |
| resources/api-reference.md | markdown | 13.2 KB |
| resources/program-addresses.md | markdown | 8.2 KB |
| templates/anchor-oracle.rs | script | 13.9 KB |
| templates/pyth-client.ts | script | 14.2 KB |
resources/api-reference.md
View on GitHub# Pyth Network API Reference
Complete API reference for Pyth Network SDKs.
## TypeScript SDKs
### @pythnetwork/hermes-client
The recommended SDK for fetching Pyth prices off-chain.
#### Installation
```bash
npm install @pythnetwork/hermes-client
```
#### HermesClient
```typescript
import { HermesClient } from "@pythnetwork/hermes-client";
const client = new HermesClient(endpoint: string, options?: HermesClientOptions);
```
**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| endpoint | `string` | Yes | Hermes API endpoint URL |
| options | `HermesClientOptions` | No | Client configuration |
**HermesClientOptions:**
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| timeout | `number` | 10000 | Request timeout in ms |
#### Methods
##### getLatestPriceUpdates
Fetch latest price updates for multiple feeds.
```typescript
const updates = await client.getLatestPriceUpdates(
priceIds: string[],
options?: GetLatestPriceUpdatesOptions
): Promise<PriceUpdates>;
```
**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| priceIds | `string[]` | Yes | Array of hex price feed IDs |
| options | `object` | No | Request options |
**Options:**
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| parsed | `boolean` | true | Include parsed price data |
| encoding | `string` | "hex" | Binary data encoding |
**Returns:** `PriceUpdates`
```typescript
interface PriceUpdates {
binary: {
encoding: string;
data: string[];
};
parsed: ParsedPriceUpdate[];
}
interface ParsedPriceUpdate {
id: string;
price: {
price: string;
conf: string;
expo: number;
publish_time: number;
};
ema_price: {
price: string;
conf: string;
expo: number;
publish_time: number;
};
}
```
**Example:**
```typescript
const client = new HermesClient("https://hermes.pyth.network");
const updates = await client.getLatestPriceUpdates([
"0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43",
"0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace",
]);
for (const update of updates.parsed) {
console.log(`Feed: ${update.id}`);
console.log(`Price: ${update.price.price} × 10^${update.price.expo}`);
console.log(`Confidence: ±${update.price.conf}`);
}
```
##### getPriceUpdatesStream
Subscribe to real-time price updates via Server-Sent Events.
```typescript
const eventSource = await client.getPriceUpdatesStream(
priceIds: string[],
options?: StreamOptions
): Promise<EventSource>;
```
**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| priceIds | `string[]` | Yes | Array of hex price feed IDs |
| options | `StreamOptions` | No | Stream configuration |
**StreamOptions:**
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| parsed | `boolean` | true | Include parsed data |
| allowUnordered | `boolean` | false | Allow out-of-order updates |
| benchmarksOnly | `boolean` | false | Only benchmark prices |
**Example:**
```typescript
const eventSource = await client.getPriceUpdatesStream([
"0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43"
], { parsed: true });
eventSource.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log("Price update:", data);
};
eventSource.onerror = (error) => {
console.error("Stream error:", error);
eventSource.close();
};
// Close when done
eventSource.close();
```
---
### @pythnetwork/pyth-solana-receiver
SDK for posting Pyth prices to Solana.
#### Installation
```bash
npm install @pythnetwork/pyth-solana-receiver
```
#### PythSolanaReceiver
```typescript
import { PythSolanaReceiver } from "@pythnetwork/pyth-solana-receiver";
const pythReceiver = new PythSolanaReceiver({
connection: Connection,
wallet: Keypair | Wallet,
});
```
#### Methods
##### newTransactionBuilder
Create a transaction builder for posting price updates.
```typescript
const builder = pythReceiver.newTransactionBuilder(
options?: TransactionBuilderOptions
): PythTransactionBuilder;
```
**TransactionBuilderOptions:**
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| shardId | `number` | 0 | Shard ID for price accounts |
| closeUpdateAccounts | `boolean` | true | Close accounts after use |
##### PythTransactionBuilder Methods
###### addPostPriceUpdates
Add price update instructions to the transaction.
```typescript
await builder.addPostPriceUpdates(
priceUpdateData: string[]
): Promise<void>;
```
**Parameters:**
| Name | Type | Description |
|------|------|-------------|
| priceUpdateData | `string[]` | Binary price update data from Hermes |
###### addPriceConsumerInstructions
Add instructions that consume the price.
```typescript
builder.addPriceConsumerInstructions(
getInstructions: (accounts: PriceAccounts) => TransactionInstruction[]
): void;
```
**Parameters:**
| Name | Type | Description |
|------|------|-------------|
| getInstructions | `function` | Function returning instructions |
**PriceAccounts:**
```typescript
interface PriceAccounts {
priceUpdateAccounts: PublicKey[];
}
```
###### buildVersionedTransactions
Build versioned transactions.
```typescript
const transactions = await builder.buildVersionedTransactions(
options?: BuildOptions
): Promise<VersionedTransaction[]>;
```
**BuildOptions:**
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| computeUnitPriceMicroLamports | `number` | 0 | Priority fee |
| tightComputeBudget | `boolean` | false | Use tight compute budget |
**Example:**
```typescript
import { PythSolanaReceiver } from "@pythnetwork/pyth-solana-receiver";
import { HermesClient } from "@pythnetwork/hermes-client";
const hermesClient = new HermesClient("https://hermes.pyth.network");
const pythReceiver = new PythSolanaReceiver({ connection, wallet });
// Fetch prices
const priceUpdates = await hermesClient.getLatestPriceUpdates([
"0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43"
]);
// Build transaction
const builder = pythReceiver.newTransactionBuilder();
await builder.addPostPriceUpdates(priceUpdates.binary.data);
builder.addPriceConsumerInstructions(({ priceUpdateAccounts }) => {
return [
// Your instruction that uses priceUpdateAccounts[0]
];
});
const transactions = await builder.buildVersionedTransactions({
computeUnitPriceMicroLamports: 50000,
});
// Send transactions
for (const tx of transactions) {
const sig = await connection.sendTransaction(tx);
console.log("Signature:", sig);
}
```
---
## Rust SDK
### pyth-solana-receiver-sdk
SDK for consuming Pyth prices in Solana programs.
#### Installation
Add to `Cargo.toml`:
```toml
[dependencies]
pyth-solana-receiver-sdk = "0.3.0"
anchor-lang = "0.30.1"
```
#### Types
##### PriceUpdateV2
The main account type for price updates.
```rust
use pyth_solana_receiver_sdk::price_update::PriceUpdateV2;
#[derive(Accounts)]
pub struct MyInstruction<'info> {
pub price_update: Account<'info, PriceUpdateV2>,
}
```
**Fields:**
| Field | Type | Description |
|-------|------|-------------|
| write_authority | `Pubkey` | Account authorized to write |
| verification_level | `VerificationLevel` | Price verification level |
| price_message | `PriceFeedMessage` | The price data |
| posted_slot | `u64` | Slot when posted |
##### Price
Price data structure.
```rust
pub struct Price {
pub price: i64, // Price value
pub conf: u64, // Confidence interval
pub exponent: i32, // Scaling exponent
pub publish_time: i64, // Publish timestamp
}
```
#### Methods
##### get_price_no_older_than
Get price with staleness check.
```rust
impl PriceUpdateV2 {
pub fn get_price_no_older_than(
&self,
clock: &Clock,
max_age_secs: u64,
) -> Result<Price>;
}
```
**Parameters:**
| Name | Type | Description |
|------|------|-------------|
| clock | `&Clock` | Solana clock sysvar |
| max_age_secs | `u64` | Maximum age in seconds |
**Returns:** `Result<Price>` - Price or error if too old
**Example:**
```rust
use anchor_lang::prelude::*;
use pyth_solana_receiver_sdk::price_update::PriceUpdateV2;
pub fn use_price(ctx: Context<UsePrice>) -> Result<()> {
let price_update = &ctx.accounts.price_update;
let clock = Clock::get()?;
let price = price_update.get_price_no_older_than(&clock, 60)?;
msg!("Price: {} × 10^{}", price.price, price.exponent);
msg!("Confidence: ±{}", price.conf);
Ok(())
}
```
##### get_price_no_older_than_with_custom_verification
Get price with feed ID verification.
```rust
impl PriceUpdateV2 {
pub fn get_price_no_older_than_with_custom_verification(
&self,
clock: &Clock,
max_age_secs: u64,
feed_id: &FeedId,
expected_owner: &Pubkey,
) -> Result<Price>;
}
```
**Parameters:**
| Name | Type | Description |
|------|------|-------------|
| clock | `&Clock` | Solana clock sysvar |
| max_age_secs | `u64` | Maximum age in seconds |
| feed_id | `&FeedId` | Expected feed ID |
| expected_owner | `&Pubkey` | Expected account owner |
**Example:**
```rust
use pyth_solana_receiver_sdk::price_update::{PriceUpdateV2, get_feed_id_from_hex};
const BTC_USD_FEED: &str = "0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43";
pub fn verified_price(ctx: Context<VerifiedPrice>) -> Result<()> {
let price_update = &ctx.accounts.price_update;
let clock = Clock::get()?;
let feed_id = get_feed_id_from_hex(BTC_USD_FEED)?;
let price = price_update.get_price_no_older_than_with_custom_verification(
&clock,
60,
&feed_id,
&pyth_solana_receiver_sdk::ID,
)?;
Ok(())
}
```
##### get_ema_price_no_older_than
Get EMA price with staleness check.
```rust
impl PriceUpdateV2 {
pub fn get_ema_price_no_older_than(
&self,
clock: &Clock,
max_age_secs: u64,
) -> Result<Price>;
}
```
**Example:**
```rust
let ema_price = price_update.get_ema_price_no_older_than(&clock, 60)?;
msg!("EMA Price: {}", ema_price.price);
```
#### Helper Functions
##### get_feed_id_from_hex
Convert hex string to FeedId.
```rust
use pyth_solana_receiver_sdk::price_update::get_feed_id_from_hex;
let feed_id = get_feed_id_from_hex(
"0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43"
)?;
```
#### Error Codes
| Error | Description |
|-------|-------------|
| `PriceTooOld` | Price exceeds max age |
| `FeedIdMismatch` | Feed ID doesn't match |
| `InvalidOwner` | Account owner invalid |
| `InsufficientVerification` | Verification level too low |
---
## Hermes HTTP API
### Endpoints
Base URL: `https://hermes.pyth.network`
#### GET /v2/updates/price/latest
Fetch latest prices for multiple feeds.
**Query Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| ids[] | `string` | Yes | Price feed IDs (can repeat) |
| encoding | `string` | No | Response encoding (hex/base64) |
| parsed | `boolean` | No | Include parsed data |
**Example:**
```bash
curl "https://hermes.pyth.network/v2/updates/price/latest?ids[]=0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43&parsed=true"
```
**Response:**
```json
{
"binary": {
"encoding": "hex",
"data": ["..."]
},
"parsed": [
{
"id": "e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43",
"price": {
"price": "6789000000000",
"conf": "3500000000",
"expo": -8,
"publish_time": 1705320000
},
"ema_price": {
"price": "6785000000000",
"conf": "3200000000",
"expo": -8,
"publish_time": 1705320000
}
}
]
}
```
#### GET /v2/updates/price/stream
Stream real-time price updates via SSE.
**Query Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| ids[] | `string` | Yes | Price feed IDs |
| parsed | `boolean` | No | Include parsed data |
| allow_unordered | `boolean` | No | Allow out-of-order |
**Example:**
```bash
curl -N "https://hermes.pyth.network/v2/updates/price/stream?ids[]=0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43&parsed=true"
```
---
## Price Calculation
### Converting Fixed-Point to Display
```typescript
function toDisplayPrice(price: string, expo: number): number {
return Number(price) * Math.pow(10, expo);
}
// Example: price="6789000000000", expo=-8
// Result: 67890.00000000 → $67,890.00
```
### Safe Price Bounds
```typescript
function getSafeBounds(price: number, conf: number) {
return {
lower: price - conf,
upper: price + conf,
// 95% confidence interval (2 standard deviations)
lower95: price - 2 * conf,
upper95: price + 2 * conf,
};
}
```
### Confidence Validation
```typescript
function isConfidenceAcceptable(
price: number,
conf: number,
maxRatioBps: number = 200 // 2%
): boolean {
const ratioBps = (conf / Math.abs(price)) * 10000;
return ratioBps <= maxRatioBps;
}
```
---
## Rate Limits
### Public Hermes Endpoint
| Limit Type | Value |
|------------|-------|
| Requests/second | 10 |
| Concurrent connections | 5 |
| Feeds per request | 100 |
> For higher limits, use a dedicated endpoint from a Pyth data provider.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |