id,language,oracle,category,name,description,code,imports_or_contract,notes
1,clarity,pyth,setup,mainnet-contract,"Pyth Oracle V4 mainnet contract","SP1CGXWEAMG6P6FT04W66NVGJ7PQWMDAC19R7PJ0Y.pyth-oracle-v4","Mainnet: SP1CGXWEAMG6P6FT04W66NVGJ7PQWMDAC19R7PJ0Y.pyth-oracle-v4","Storage: pyth-storage-v4; Decoder: pyth-pnau-decoder-v3; Wormhole: wormhole-core-v4"
2,clarity,pyth,setup,testnet-contract,"Pyth Oracle V4 testnet contract","STR738QQX1PVTM6WTDF833Z18T8R0ZB791TCNEFM.pyth-oracle-v4","Testnet: STR738QQX1PVTM6WTDF833Z18T8R0ZB791TCNEFM.pyth-oracle-v4","Same trait contract names as mainnet (pyth-storage-v4 etc)"
3,clarity,pyth,read,decode-price-feeds,"Decode VAA bytes to extract price info","(contract-call? .pyth-oracle-v4 decode-price-feeds vaa-buffer trait-tuple)","SP1CGXWEAMG6P6FT04W66NVGJ7PQWMDAC19R7PJ0Y.pyth-oracle-v4","Returns price ema-price conf ema-conf expo publish-time; Read-only no fee"
4,clarity,pyth,write,verify-and-update-price-feeds,"Verify VAA signatures and update on-chain prices","(contract-call? .pyth-oracle-v4 verify-and-update-price-feeds vaa-buffer trait-tuple)","SP1CGXWEAMG6P6FT04W66NVGJ7PQWMDAC19R7PJ0Y.pyth-oracle-v4","Costs 1 STX fee; Updates stored price feeds; Verifies Wormhole signatures"
5,clarity,pyth,read,read-price-feed,"Read stored on-chain price for a feed ID","(contract-call? .pyth-oracle-v4 read-price-feed feed-id-buffer storage-trait)","SP1CGXWEAMG6P6FT04W66NVGJ7PQWMDAC19R7PJ0Y.pyth-oracle-v4","Returns stored price data; Must be updated first via verify-and-update"
6,clarity,pyth,read,get-price,"Get current price value for a feed","(contract-call? .pyth-oracle-v4 get-price feed-id-buffer storage-trait)","SP1CGXWEAMG6P6FT04W66NVGJ7PQWMDAC19R7PJ0Y.pyth-oracle-v4","Returns (ok {price ema-price conf ema-conf expo publish-time prev-publish-time})"
7,clarity,pyth,trait,trait-tuple,"Build trait tuple for Pyth calls","(tuple (pyth-storage-contract (contract-principal .pyth-storage-v4)) (pyth-decoder-contract (contract-principal .pyth-pnau-decoder-v3)) (wormhole-core-contract (contract-principal .wormhole-core-v4)))","Trait implementor contracts","Required for all Pyth contract calls; Use same address as oracle contract"
8,clarity,pyth,feed-id,btc-usd-feed,"BTC/USD price feed ID","0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43","Pyth mainnet feed ID","Use bufferCV(hexToBuff(feedId)) in contract calls"
9,clarity,pyth,feed-id,stx-usd-feed,"STX/USD price feed ID","0xec7a775f46379b5e943c3526b1c8d54cd49749176b0b98e02dde68d1bd335c17","Pyth mainnet feed ID","Primary feed for STX price oracle"
10,clarity,pyth,feed-id,eth-usd-feed,"ETH/USD price feed ID","0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace","Pyth mainnet feed ID","Standard Ethereum price feed"
11,clarity,pyth,feed-id,usdc-usd-feed,"USDC/USD price feed ID","0xeaa020c61cc479712813461ce153894a96a6c00b21ed0cfc2798d1f9a9e9c94a","Pyth mainnet feed ID","Stablecoin price feed"
12,javascript,pyth,decode,decode-price-call,"Call decode-price-feeds from JS","const { request } = await import('@stacks/connect'); const vaa = bufferCV(hexToBuff(vaaHex)); const traits = tupleCV({...traitTuple}); await request('stx_callContract' {contract: `${addr}.${name}` functionName: 'decode-price-feeds' functionArgs: [vaa traits].map(cvToHex) network})","import { bufferCV tupleCV cvToHex } from '@stacks/transactions'; import { request } from '@stacks/connect'","Returns decoded price data; Read-only transaction"
13,javascript,pyth,update,verify-update-call,"Call verify-and-update-price-feeds from JS","const { request } = await import('@stacks/connect'); const vaa = bufferCV(hexToBuff(vaaHex)); const traits = tupleCV({...traitTuple}); const pc = Pc.principal(userAddr).willSendLte(1000000).ustx(); await request('stx_callContract' {contract: `${addr}.${name}` functionName: 'verify-and-update-price-feeds' functionArgs: [vaa traits].map(cvToHex) postConditions: [pc] network})","import { bufferCV tupleCV cvToHex Pc } from '@stacks/transactions'; import { request } from '@stacks/connect'","Requires 1 STX fee; Add post-condition for safety"
14,javascript,pyth,read,read-price-call,"Call read-price-feed from JS","const { request } = await import('@stacks/connect'); const feedId = bufferCV(hexToBuff(feedIdHex)); const storage = contractPrincipalCV(address 'pyth-storage-v4'); await request('stx_callContract' {contract: `${addr}.${name}` functionName: 'read-price-feed' functionArgs: [feedId storage].map(cvToHex) network})","import { bufferCV contractPrincipalCV cvToHex } from '@stacks/transactions'; import { request } from '@stacks/connect'","Read stored price; Must be updated first"
15,javascript,pyth,read,get-price-call,"Call get-price from JS","const { request } = await import('@stacks/connect'); const feedId = bufferCV(hexToBuff(feedIdHex)); const storage = contractPrincipalCV(address 'pyth-storage-v4'); await request('stx_callContract' {contract: `${addr}.${name}` functionName: 'get-price' functionArgs: [feedId storage].map(cvToHex) network})","import { bufferCV contractPrincipalCV cvToHex } from '@stacks/transactions'; import { request } from '@stacks/connect'","Returns current price with all metadata"
16,javascript,pyth,util,hex-to-buffer,"Convert hex string to buffer for Pyth calls","function hexToBuff(hexWith0x) { const h = hexWith0x.startsWith('0x') ? hexWith0x.slice(2) : hexWith0x; return Buffer.from(h 'hex') }","import { Buffer } from 'buffer'","Required to convert feed IDs and VAA hex to buffers"
17,javascript,pyth,util,trait-tuple-builder,"Build trait tuple for contract calls","function traitTuple(network) { const addr = getContractAddress(network); return tupleCV({ 'pyth-storage-contract': contractPrincipalCV(addr 'pyth-storage-v4') 'pyth-decoder-contract': contractPrincipalCV(addr 'pyth-pnau-decoder-v3') 'wormhole-core-contract': contractPrincipalCV(addr 'wormhole-core-v4') }) }","import { tupleCV contractPrincipalCV } from '@stacks/transactions'","Use same address as oracle contract; Required for decode and verify calls"
18,api,pyth,hermes,fetch-latest-vaa,"Fetch latest VAA from Hermes API","const feedId = '0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43'; const url = `https://hermes.pyth.network/api/latest_vaas?ids[]=${encodeURIComponent(feedId)}`; const res = await fetch(url); const vaas = await res.json(); const vaaHex = base64ToHex(vaas[0])","fetch or axios","Returns base64-encoded VAA; Convert to hex before using in contract calls"
19,api,pyth,hermes,hermes-client-sdk,"Use Hermes client SDK to fetch VAA","import { HermesClient } from '@pythnetwork/hermes-client'; const hermes = new HermesClient('https://hermes.pyth.network'); const vaas = await hermes.getLatestVaas({ids: [feedId]}); const vaaHex = base64ToHex(vaas[0])","npm install @pythnetwork/hermes-client","SDK handles VAA fetching; Still need to convert base64 to hex"
20,javascript,pyth,util,base64-to-hex,"Convert base64 VAA to hex","function base64ToHex(b64) { const binStr = atob(b64); let hex = '0x'; for (let i = 0; i < binStr.length; i++) { hex += (binStr.charCodeAt(i) & 0xff).toString(16).padStart(2 '0') } return hex }","Native JavaScript","Required to convert Hermes VAA response to hex for contract calls"
21,javascript,pyth,parse,parse-price-result,"Parse price data from contract result","function parsePriceFromResult(repr) { const tupleMatch = repr.match(/\(ok \((?:tuple|list.*tuple) \(([\s\S]*?)\)\)\)/); if (!tupleMatch) return null; const content = tupleMatch[1]; return { price: parseInt(content.match(/price (\d+|u\d+)/)?.[1] || 0) emaPrice: parseInt(content.match(/ema-price (\d+)/)?.[1] || 0) conf: parseInt(content.match(/conf u(\d+)/)?.[1] || 0) emaConf: parseInt(content.match(/ema-conf u(\d+)/)?.[1] || 0) expo: parseInt(content.match(/expo (-?\d+)/)?.[1] || 0) publishTime: parseInt(content.match(/publish-time u(\d+)/)?.[1] || 0) } }","None","Parse transaction result repr string to extract price data"
22,javascript,pyth,calc,calculate-actual-price,"Calculate actual price from price data","function calculateActualPrice(priceData) { return priceData.emaPrice / Math.pow(10 Math.abs(priceData.expo)) }","None","Formula: ema-price / 10^|expo|; Expo is typically -8 so divide by 10^8"
23,javascript,pyth,parse,parse-update-event,"Parse price from verify-and-update event","function parsePriceUpdateEvent(events) { for (const event of events) { if (event.event_type === 'smart_contract_log' && event.contract_log) { const repr = event.contract_log.value.repr; if (repr.includes('action \"updated\"') && repr.includes('type \"price-feed\"')) { const dataMatch = repr.match(/data \(tuple ([\s\S]*?)\)\)/); if (dataMatch) { return parsePriceFromResult(`(ok (tuple ${dataMatch[1]}))`); } } } } return null }","None","Extract price data from contract log events after verify-and-update"
24,api,pyth,hiro,fetch-transaction-result,"Fetch and parse transaction from Hiro API","async function getTxResult(txId network) { const baseUrl = network === 'mainnet' ? 'https://api.mainnet.hiro.so' : 'https://api.testnet.hiro.so'; const res = await fetch(`${baseUrl}/extended/v1/tx/${txId}`); const tx = await res.json(); if (tx.tx_status === 'success' && tx.tx_result?.repr) { return parsePriceFromResult(tx.tx_result.repr) } return null }","fetch or axios","Wait ~10s after tx submit for indexing; Parse result to get price data"
25,clarity,pyth,example,full-oracle-integration,"Complete price oracle integration example","(define-read-only (get-btc-price) (let ((feed-id 0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43)) (match (contract-call? 'SP1CGXWEAMG6P6FT04W66NVGJ7PQWMDAC19R7PJ0Y.pyth-oracle-v4 get-price feed-id 'SP1CGXWEAMG6P6FT04W66NVGJ7PQWMDAC19R7PJ0Y.pyth-storage-v4) success (ok (get ema-price success)) error (err u404))))","Pyth oracle contract","Read-only function to get BTC price; Returns ema-price or error"
26,javascript,pyth,example,full-update-flow,"Complete flow to update price on-chain","// 1. Fetch VAA from Hermes; const hermes = new HermesClient('https://hermes.pyth.network'); const vaas = await hermes.getLatestVaas({ids: [feedId]}); const vaaHex = base64ToHex(vaas[0]); // 2. Update price on-chain; const { request } = await import('@stacks/connect'); const tx = await request('stx_callContract' {...}); // 3. Wait and fetch result; setTimeout(async () => { const result = await getTxResult(tx.txid 'mainnet'); const price = calculateActualPrice(result) } 10000)","Multiple imports","Complete workflow: fetch VAA update on-chain parse result calculate price"
27,javascript,pyth,feeds,price-feed-constants,"Common Pyth price feed IDs","const PRICE_FEEDS = { BTC_USD: '0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43' STX_USD: '0xec7a775f46379b5e943c3526b1c8d54cd49749176b0b98e02dde68d1bd335c17' ETH_USD: '0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace' USDC_USD: '0xeaa020c61cc479712813461ce153894a96a6c00b21ed0cfc2798d1f9a9e9c94a' BNB_USD: '0x2f95862b045670cd22bee3114c39763a4a08beeb663b145d283c31d7d1101c4f' LINK_USD: '0x8ac0c70fff57e9aefdf5edf44b51d62c2d433653cbb2cf5cc06bb115af04d221' }","None","Mainnet feed IDs; Find more at pyth.network/price-feeds"
28,javascript,pyth,wallet,connect-for-oracle,"Connect wallet for oracle transactions","import { connect isConnected getLocalStorage } from '@stacks/connect'; const appDetails = { name: 'My Pyth App' icon: window.location.origin + '/icon.png' }; const response = await connect(); const stxAddress = response.addresses.stx[0].address","npm install @stacks/connect","Required for verify-and-update transactions (read-only calls work without wallet)"
29,api,pyth,hermes,hermes-endpoints,"Pyth Hermes API endpoints","// Latest VAA: https://hermes.pyth.network/api/latest_vaas?ids[]={feedId}; // Latest price updates: https://hermes.pyth.network/api/latest_price_feeds?ids[]={feedId}; // All feed IDs: https://hermes.pyth.network/api/price_feed_ids","Hermes REST API","Free API; No authentication required; Mainnet production endpoint"
30,clarity,pyth,price-calc,price-calculation,"Price calculation in Clarity","(define-read-only (calculate-price (price-data (tuple (ema-price int) (expo int)))) (let ((ema (get ema-price price-data)) (exp (get expo price-data))) (if (< exp 0) (/ ema (pow u10 (to-uint (- 0 exp)))) (* ema (pow u10 (to-uint exp))))))","None","Convert raw price with exponent; Handle negative exponents (most common)"
