hiero-oracle-kit

Oracle price feed abstraction for Hiero/Hedera agents. Designed for upstreaming as @hiero/oracle-kit.

Install

npm install hiero-oracle-kit ethers @pythnetwork/pyth-evm-js

Quickstart

import { createOracleKit, pyth } from 'hiero-oracle-kit';

const oracle = createOracleKit({ providers: [pyth({ network: 'testnet' })] });
const feed = await oracle.getPriceFeed('ETH/USD');
console.log(feed.price, feed.confidence, feed.ageSeconds);

Supported Feeds

| Pair | Provider | Feed ID | | -------- | -------- | ---------------------------------------------------------------- | | ETH/USD | pyth | ff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace | | BTC/USD | pyth | e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43 | | HBAR/USD | pyth | 3728e591097635310e6341af53db8b7ee42da9b3a8d918f9463ce9cca886dfbd | | LINK/USD | pyth | 8ac0c70fff57e9aefdf5edf44b51d62c2d433653cbb2cf5cc06bb115af04d221 |

API Reference

| Method | Signature | Description | | ----------------- | --------------------------------------------------------- | ---------------------------------- | | createOracleKit | (config: OracleKitConfig) => OracleKit | Creates a configured oracle client | | getPriceFeed | (pair: string) => Promise<PriceFeed> | Fetches one validated feed | | getPriceFeeds | (pairs: string[]) => Promise<PriceFeed[]> | Fetches multiple feeds | | checkCondition | (pair, operator, threshold) => Promise<ConditionResult> | Evaluates a price condition | | listFeeds | () => Promise<FeedMetadata[]> | Lists supported feeds | | isHealthy | () => Promise<HealthStatus> | Runs provider health checks | | asAgentTools | () => AgentTool[] | Returns 3 LLM-ready tools |

Configuration Reference

| Option | Type | Default | Description | | ------------------------ | ---------------------------------------- | ----------- | ---------------------------------- | | providers | OracleProvider[] | required | Ordered provider list | | strategy | 'primary' \| 'fallback' \| 'aggregate' | 'primary' | Provider selection strategy | | maxStalenessSeconds | number | 60 | Maximum feed age before stale | | minConfidence | number | 0.95 | Minimum confidence score | | cacheConfig.enabled | boolean | false | Enables cache path (future module) | | cacheConfig.ttlSeconds | number | 5 | Cache TTL in seconds |

Error Codes

| Code | When thrown | | ---------------------- | ----------------------------------------------- | | PROVIDER_UNAVAILABLE | Provider fails or no provider can serve request | | FEED_NOT_FOUND | Pair is not supported | | FEED_STALE | Feed age exceeds max staleness | | LOW_CONFIDENCE | Confidence is below minimum | | UPDATE_FAILED | On-chain feed update fails | | NETWORK_ERROR | Network call failed or returned invalid payload | | INVALID_CONFIG | Invalid library configuration or operator |

Provider Extension

Implement the OracleProvider interface and return normalized PriceFeed responses. Register your provider instance in the providers array when calling createOracleKit. If you need graceful degradation, set strategy: 'fallback' and order providers by priority.

Contributing

See CONTRIBUTING.md.

License

Apache 2.0 © 2026 alienworld1