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 |
templates/pyth-client.ts
View on GitHub/**
* Pyth Network Client Template
*
* Production-ready client for fetching and posting Pyth prices.
* Copy this file and customize for your project.
*
* Usage:
* 1. Set your configuration below
* 2. Install dependencies: npm install @pythnetwork/hermes-client @pythnetwork/pyth-solana-receiver @solana/web3.js
* 3. Run with: npx ts-node pyth-client.ts
*/
import { HermesClient } from "@pythnetwork/hermes-client";
import { PythSolanaReceiver } from "@pythnetwork/pyth-solana-receiver";
import {
Connection,
Keypair,
PublicKey,
TransactionInstruction,
VersionedTransaction,
} from "@solana/web3.js";
// ============================================================================
// CONFIGURATION
// ============================================================================
const CONFIG = {
// Hermes API endpoint
hermesEndpoint: "https://hermes.pyth.network",
// Solana connection
solanaRpc: process.env.SOLANA_RPC || "https://api.mainnet-beta.solana.com",
// Default maximum price age in seconds
maxPriceAgeSecs: 60,
// Default maximum confidence ratio (basis points)
maxConfidenceBps: 200, // 2%
// Priority fee in microlamports
priorityFeeMicroLamports: 50000,
};
// ============================================================================
// PRICE FEED IDS
// ============================================================================
export const PRICE_FEEDS = {
// Cryptocurrencies
BTC_USD: "0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43",
ETH_USD: "0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace",
SOL_USD: "0xef0d8b6fda2ceba41da15d4095d1da392a0d2f8ed0c6c7bc0f4cfac8c280b56d",
BNB_USD: "0x2f95862b045670cd22bee3114c39763a4a08beeb663b145d283c31d7d1101c4f",
AVAX_USD: "0x93da3352f9f1d105fdfe4971cfa80e9dd777bfc5d0f683ebb6e1294b92137bb7",
// Stablecoins
USDC_USD: "0xeaa020c61cc479712813461ce153894a96a6c00b21ed0cfc2798d1f9a9e9c94a",
USDT_USD: "0x2b89b9dc8fdf9f34709a5b106b472f0f39bb6ca9ce04b0fd7f2e971688e2e53b",
// Solana Ecosystem
JTO_USD: "0xb43660a5f790c69354b0729a5ef9d50d68f1df92107540210b9cccba1f947cc2",
JUP_USD: "0x0a0408d619e9380abad35060f9192039ed5042fa6f82301d0e48bb52be830996",
BONK_USD: "0x72b021217ca3fe68922a19aaf990109cb9d84e9ad004b4d2025ad6f529314419",
WIF_USD: "0x4ca4beeca86f0d164160323817a4e42b10010a724c2217c6ee41b54cd4cc61fc",
RAY_USD: "0x91568baa8beb53db23eb3fb7f22c6e8bd303d103919e19733f2bb642d3e7987a",
// DeFi
LINK_USD: "0x8ac0c70fff57e9aefdf5edf44b51d62c2d433653cbb2cf5cc06bb115af04d221",
UNI_USD: "0x78d185a741d07edb3412b09008b7c5cfb9bbbd7d568bf00ba737b456ba171501",
AAVE_USD: "0x2b9ab1e972a281585084148ba1389800799bd4be63b957507db1349314e47445",
// Commodities
XAU_USD: "0x765d2ba906dbc32ca17cc11f5310a89e9ee1f6420508c63861f2f8ba4ee34bb2",
XAG_USD: "0xf2fb02c32b055c805e7238d628e5e9dadef274376114eb1f012337cabe93871e",
} as const;
// ============================================================================
// TYPES
// ============================================================================
export interface PriceData {
feedId: string;
price: number;
confidence: number;
confidencePercent: number;
publishTime: Date;
age: number;
emaPrice?: number;
emaConfidence?: number;
}
export interface PriceValidationOptions {
maxAgeSecs?: number;
maxConfidenceBps?: number;
minPrice?: number;
maxPrice?: number;
}
export interface PostPriceOptions {
shardId?: number;
closeUpdateAccounts?: boolean;
computeUnitPriceMicroLamports?: number;
}
// ============================================================================
// PYTH CLIENT
// ============================================================================
export class PythClient {
private hermesClient: HermesClient;
private connection: Connection;
private pythReceiver: PythSolanaReceiver | null = null;
constructor(
options?: {
hermesEndpoint?: string;
solanaRpc?: string;
wallet?: Keypair;
}
) {
this.hermesClient = new HermesClient(
options?.hermesEndpoint || CONFIG.hermesEndpoint
);
this.connection = new Connection(
options?.solanaRpc || CONFIG.solanaRpc,
"confirmed"
);
if (options?.wallet) {
this.pythReceiver = new PythSolanaReceiver({
connection: this.connection,
wallet: options.wallet,
});
}
}
// --------------------------------------------------------------------------
// Price Fetching
// --------------------------------------------------------------------------
/**
* Get latest price for a single feed
*/
async getPrice(feedId: string): Promise<PriceData> {
const prices = await this.getPrices([feedId]);
const price = prices.get(feedId);
if (!price) {
throw new Error(`No price found for feed: ${feedId}`);
}
return price;
}
/**
* Get latest prices for multiple feeds
*/
async getPrices(feedIds: string[]): Promise<Map<string, PriceData>> {
const updates = await this.hermesClient.getLatestPriceUpdates(feedIds, {
parsed: true,
});
const priceMap = new Map<string, PriceData>();
const now = Math.floor(Date.now() / 1000);
for (const update of updates.parsed || []) {
const { price, conf, expo, publish_time } = update.price;
const priceNum = Number(price) * Math.pow(10, expo);
const confNum = Number(conf) * Math.pow(10, expo);
const priceData: PriceData = {
feedId: "0x" + update.id,
price: priceNum,
confidence: confNum,
confidencePercent: (confNum / Math.abs(priceNum)) * 100,
publishTime: new Date(publish_time * 1000),
age: now - publish_time,
};
if (update.ema_price) {
priceData.emaPrice =
Number(update.ema_price.price) * Math.pow(10, update.ema_price.expo);
priceData.emaConfidence =
Number(update.ema_price.conf) * Math.pow(10, update.ema_price.expo);
}
priceMap.set("0x" + update.id, priceData);
}
return priceMap;
}
/**
* Get validated price with checks
*/
async getValidatedPrice(
feedId: string,
options: PriceValidationOptions = {}
): Promise<PriceData> {
const price = await this.getPrice(feedId);
this.validatePrice(price, options);
return price;
}
/**
* Validate a price against criteria
*/
validatePrice(price: PriceData, options: PriceValidationOptions = {}): void {
const maxAge = options.maxAgeSecs ?? CONFIG.maxPriceAgeSecs;
const maxConfBps = options.maxConfidenceBps ?? CONFIG.maxConfidenceBps;
// Check staleness
if (price.age > maxAge) {
throw new Error(
`Price too stale: ${price.age}s old (max: ${maxAge}s)`
);
}
// Check confidence
const confBps = price.confidencePercent * 100;
if (confBps > maxConfBps) {
throw new Error(
`Confidence too high: ${price.confidencePercent.toFixed(2)}% (max: ${maxConfBps / 100}%)`
);
}
// Check bounds
if (options.minPrice !== undefined && price.price < options.minPrice) {
throw new Error(`Price below minimum: ${price.price} < ${options.minPrice}`);
}
if (options.maxPrice !== undefined && price.price > options.maxPrice) {
throw new Error(`Price above maximum: ${price.price} > ${options.maxPrice}`);
}
}
// --------------------------------------------------------------------------
// Binary Data for On-Chain
// --------------------------------------------------------------------------
/**
* Get binary price update data for posting on-chain
*/
async getPriceUpdateData(feedIds: string[]): Promise<string[]> {
const updates = await this.hermesClient.getLatestPriceUpdates(feedIds);
return updates.binary.data;
}
// --------------------------------------------------------------------------
// Posting to Solana
// --------------------------------------------------------------------------
/**
* Build transactions to post price updates to Solana
*/
async buildPostPriceTransactions(
feedIds: string[],
consumerInstructions?: (accounts: { priceUpdateAccounts: PublicKey[] }) => TransactionInstruction[],
options: PostPriceOptions = {}
): Promise<VersionedTransaction[]> {
if (!this.pythReceiver) {
throw new Error("Wallet required for posting prices. Initialize with wallet option.");
}
// Get price update data
const priceUpdateData = await this.getPriceUpdateData(feedIds);
// Build transaction
const builder = this.pythReceiver.newTransactionBuilder({
shardId: options.shardId ?? 0,
closeUpdateAccounts: options.closeUpdateAccounts ?? true,
});
await builder.addPostPriceUpdates(priceUpdateData);
if (consumerInstructions) {
builder.addPriceConsumerInstructions(consumerInstructions);
}
const transactions = await builder.buildVersionedTransactions({
computeUnitPriceMicroLamports:
options.computeUnitPriceMicroLamports ?? CONFIG.priorityFeeMicroLamports,
});
return transactions;
}
/**
* Post price updates to Solana and return signatures
*/
async postPriceUpdates(
feedIds: string[],
consumerInstructions?: (accounts: { priceUpdateAccounts: PublicKey[] }) => TransactionInstruction[],
options: PostPriceOptions = {}
): Promise<string[]> {
const transactions = await this.buildPostPriceTransactions(
feedIds,
consumerInstructions,
options
);
const signatures: string[] = [];
for (const tx of transactions) {
const signature = await this.connection.sendTransaction(tx);
await this.connection.confirmTransaction(signature);
signatures.push(signature);
}
return signatures;
}
// --------------------------------------------------------------------------
// Streaming
// --------------------------------------------------------------------------
/**
* Subscribe to real-time price updates
*/
async subscribePrices(
feedIds: string[],
callback: (prices: Map<string, PriceData>) => void,
options?: { allowUnordered?: boolean }
): Promise<{ close: () => void }> {
const eventSource = await this.hermesClient.getPriceUpdatesStream(feedIds, {
parsed: true,
allowUnordered: options?.allowUnordered ?? false,
});
eventSource.onmessage = (event: MessageEvent) => {
try {
const data = JSON.parse(event.data);
const priceMap = new Map<string, PriceData>();
const now = Math.floor(Date.now() / 1000);
for (const update of data.parsed || []) {
const { price, conf, expo, publish_time } = update.price;
const priceNum = Number(price) * Math.pow(10, expo);
const confNum = Number(conf) * Math.pow(10, expo);
priceMap.set("0x" + update.id, {
feedId: "0x" + update.id,
price: priceNum,
confidence: confNum,
confidencePercent: (confNum / Math.abs(priceNum)) * 100,
publishTime: new Date(publish_time * 1000),
age: now - publish_time,
});
}
callback(priceMap);
} catch (error) {
console.error("Error processing price update:", error);
}
};
return {
close: () => eventSource.close(),
};
}
}
// ============================================================================
// HELPER FUNCTIONS
// ============================================================================
/**
* Convert price to USD string
*/
export function formatUSD(price: number): string {
if (Math.abs(price) >= 1) {
return `$${price.toLocaleString(undefined, { maximumFractionDigits: 2 })}`;
}
return `$${price.toFixed(8)}`;
}
/**
* Get safe price bounds
*/
export function getSafeBounds(
price: number,
confidence: number,
sigmas: number = 1
): { lower: number; mid: number; upper: number } {
const halfWidth = confidence * sigmas;
return {
lower: price - halfWidth,
mid: price,
upper: price + halfWidth,
};
}
/**
* Calculate token value in USD
*/
export function calculateUSDValue(
tokenAmount: number,
tokenDecimals: number,
price: number
): number {
const amount = tokenAmount / Math.pow(10, tokenDecimals);
return amount * price;
}
/**
* Calculate tokens for USD amount
*/
export function calculateTokensForUSD(
usdAmount: number,
tokenDecimals: number,
price: number
): number {
const tokens = usdAmount / price;
return tokens * Math.pow(10, tokenDecimals);
}
// ============================================================================
// EXAMPLE USAGE
// ============================================================================
async function main() {
console.log("=== Pyth Client Template ===\n");
// Create client
const client = new PythClient();
// Fetch single price
console.log("Fetching SOL/USD price...");
const solPrice = await client.getPrice(PRICE_FEEDS.SOL_USD);
console.log(`SOL/USD: ${formatUSD(solPrice.price)}`);
console.log(`Confidence: ±${formatUSD(solPrice.confidence)} (${solPrice.confidencePercent.toFixed(3)}%)`);
console.log(`Age: ${solPrice.age}s\n`);
// Fetch multiple prices
console.log("Fetching multiple prices...");
const prices = await client.getPrices([
PRICE_FEEDS.BTC_USD,
PRICE_FEEDS.ETH_USD,
PRICE_FEEDS.SOL_USD,
]);
for (const [feedId, price] of prices) {
const symbol = Object.entries(PRICE_FEEDS).find(
([_, id]) => id === feedId
)?.[0] || feedId;
console.log(`${symbol}: ${formatUSD(price.price)}`);
}
// Validated price
console.log("\nFetching validated price...");
try {
const validatedPrice = await client.getValidatedPrice(PRICE_FEEDS.BTC_USD, {
maxAgeSecs: 30,
maxConfidenceBps: 100,
});
console.log(`BTC/USD (validated): ${formatUSD(validatedPrice.price)}`);
} catch (error) {
console.log(`Validation failed: ${error}`);
}
// Safe bounds example
console.log("\nSafe price bounds (2-sigma):");
const bounds = getSafeBounds(solPrice.price, solPrice.confidence, 2);
console.log(`SOL/USD: ${formatUSD(bounds.lower)} - ${formatUSD(bounds.upper)}`);
// Value calculation
console.log("\nValue calculation:");
const solAmount = 10 * 1e9; // 10 SOL in lamports
const usdValue = calculateUSDValue(solAmount, 9, solPrice.price);
console.log(`10 SOL = ${formatUSD(usdValue)}`);
}
// Run if executed directly
if (require.main === module) {
main().catch(console.error);
}
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 |