Hedera Agent Kit - Pyth Plugin

A Hedera Agent Kit plugin that exposes Pyth Network price feeds via the Hermes API. Use it to pull real-time market data (crypto, FX, equities, commodities) with simple tool calls.

Overview

This plugin registers Pyth tools for:

• Discovering price feeds by symbol or description
• Fetching the latest price for a feed by ID or symbol
• Fetching latest prices for multiple feeds in one request

All tools return a { success: boolean, ... } payload so agents can reason about failures consistently.

Installation

npm install hak-pyth-plugin

Quick Start (Agent)

import { HederaLangchainToolkit } from "@hashgraph/hedera-agent-kit-langchain";
import { pythPlugin } from "hak-pyth-plugin";

const hederaAgentToolkit = new HederaLangchainToolkit({
  client,
  configuration: {
    plugins: [pythPlugin],
  },
});

const tools = hederaAgentToolkit.getTools();

Configuration

Defaults:

• PYTH_BASE_URL (default: https://hermes.pyth.network)
• PYTH_TIMEOUT_MS (default: 10000)
• PYTH_RETRIES (default: 2)

You can override in code by passing a pyth key inside context:

import { AgentMode } from "@hashgraph/hedera-agent-kit";
import { HederaLangchainToolkit } from "@hashgraph/hedera-agent-kit-langchain";

const hederaAgentToolkit = new HederaLangchainToolkit({
  client,
  configuration: {
    plugins: [pythPlugin],
    context: {
      mode: AgentMode.AUTONOMOUS,
      pyth: {
        baseUrl: "https://hermes.pyth.network",
        timeoutMs: 10000,
        retries: 2,
      },
    },
  },
});

Tool Catalog

| Method | Description | Parameters | | --- | --- | --- | | pyth_list_price_feeds | List/search feeds | query? (symbol/base/quote filter), limit? (1–25, default 10) | | pyth_get_latest_price | Latest price for one feed | priceFeedId?, symbol? | | pyth_get_latest_prices | Latest prices for many feeds | priceFeedIds?, symbols? |

Token context warning: Querying pyth_list_price_feeds without a query filter can return thousands of feeds and exhaust the LLM context window. Always pass a focused query (e.g. "BTC", "ETH/USD") and rely on the default limit of 10 results. Avoid broad queries like "show me all available price feeds".

LLM Prompt Examples

Once the plugin is registered with your agent, you can interact with it using natural language:

"What BTC/USD price feeds are available on Pyth?"
"What is the current price of ETH in USD?"
"Get me the latest prices for BTC/USD and SOL/USD."
"Find Pyth feeds for gold (XAU)."
"What is the EUR/USD exchange rate right now?"

See the examples/ directory for fully-wired LangChain and Vercel AI agent scripts.

Usage Examples

List feeds by query:

const tools = pythPlugin.tools({});
const listTool = tools.find((tool) => tool.method === "pyth_list_price_feeds");
const result = await listTool?.execute(null, {}, { query: "BTC" });

if (result?.success) {
  console.log(result.count, result.feeds[0]);
}

Get latest price by symbol:

const priceTool = tools.find((tool) => tool.method === "pyth_get_latest_price");
const result = await priceTool?.execute(null, {}, { symbol: "BTC/USD" });

if (result?.success) {
  console.log(result.update?.formattedPrice, result.update?.publishTime);
}

Batch latest prices:

const pricesTool = tools.find((tool) => tool.method === "pyth_get_latest_prices");
const result = await pricesTool?.execute(null, {}, { symbols: ["BTC/USD", "ETH/USD"] });

if (result?.success) {
  console.log(result.updates.map((update) => update.formattedPrice));
}

Example Script (Local)

Build first, then run the demo script:

npm run build
npm run example

Optional overrides:

export PYTH_EXAMPLE_QUERY=BTC
export PYTH_EXAMPLE_FEED_ID=0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace

Response Shape Notes

• update.formattedPrice applies the Pyth exponent for human-readable output.
• update.publishTime is an epoch timestamp (seconds).
• On failure, tools return { success: false, error }.

Integration Smoke Test

npm run test:integration

Optional env overrides:

export PYTH_BASE_URL=https://hermes.pyth.network
export PYTH_TEST_QUERY=BTC
export PYTH_TEST_FEED_ID=0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace

Development

npm run build
npm run test
npm run lint

Resources

• Hedera Agent Kit
• Hedera AI Agent Kit Docs
• Pyth Hermes API Docs

License

MIT