Build with AI Agents

This guide covers steps to connect AI agents to Pyth market data with the Pyth MCP server and MCP Skills.

MCP ServerCopy Anchor Link

The Pyth MCP server gives AI assistants direct, structured access to Pyth market data through the Model Context Protocol. You can discover feeds, fetch real-time and historical prices, replay every update in a short window, and generate chart-ready candles, all within a single conversation.

ToolsCopy Anchor Link

Price tools accept full symbols (Crypto.BTC/USD) or plain pairs (BTC/USD). A plain pair resolves to the live spot feed when there is one, otherwise to the only other live match. resolved_symbols in the response shows what each input resolved to.

API KeyCopy Anchor Link

Every user brings their own Pyth Pro API key; the hosted server has none of its own. See Acquire an API Key.

Give the server your key in one of three ways. A key passed on a call overrides a configured one.

1. In your MCP client's configuration (recommended): your client sends the key as an Authorization: Bearer <key> header on every request. The Setup tabs below show how for each client.
2. As an environment variable, for a local server: set PYTH_PRO_ACCESS_TOKEN in the server's env block.
3. On each call: the access_token parameter. Your assistant asks for the key when none is configured.

get_symbols works without a key. With a key, it also lists feeds visible only to Pro keys and marks each feed entitled: true or false: whether your key can query that feed.

SetupCopy Anchor Link

• Endpoint: https://mcp.pyth.network/mcp
• Transport: Streamable HTTP
• Auth: connecting needs no key; the price tools use your key, sent as an Authorization: Bearer header

Replace YOUR_API_KEY with your Pyth Pro API key.

claude mcp add --transport http pyth https://mcp.pyth.network/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

claude mcp list

Tool ReferenceCopy Anchor Link

Every price tool also takes an optional access_token. Leave it out when your client sends the key.

get_symbolsCopy Anchor Link

Search and list Pyth Pro feeds.

• Each feed has a state. Only stable feeds return prices; beta and coming_soon feeds are listed but cannot be queried yet.
• With a key, each feed carries entitled, and the list includes feeds visible only to Pro keys.

get_latest_priceCopy Anchor Link

Fetch the latest prices for one or more feeds.

* At least one of symbols or price_feed_ids is required.

• Up to 100 feeds per request. If both symbols and price_feed_ids are sent, only the IDs are used.
• properties: price, bestBidPrice, bestAskPrice, exponent, publisherCount, confidence, fundingRate, fundingTimestamp, fundingRateInterval, marketSession, emaPrice, emaConfidence, feedUpdateTimestamp. The default is the first six plus marketSession and feedUpdateTimestamp.
• Prices are integers with an exponent. Each response also carries display_* values (display_price, display_bid, display_ask, display_confidence, display_ema_price, display_ema_confidence, display_funding_rate) with the exponent applied.

get_historical_priceCopy Anchor Link

Get prices at a single historical timestamp.

* At least one of symbols or price_feed_ids is required.

• Up to 50 feeds per request. If both are sent, only the IDs are used.
• The timestamp is aligned down to the channel's update interval.

get_price_rangeCopy Anchor Link

Return every price update for one or more feeds within a short window, such as the seconds around a liquidation or a news event.

* At least one of symbols or price_feed_ids is required. Up to 50 feeds.

• When has_more is true, call again with the same arguments and after set to next_cursor.

get_candlestick_dataCopy Anchor Link

Fetch OHLC candlestick data for a single feed.

• from must be earlier than to.
• Up to 500 candles per response; larger results come back with truncated: true.
• For funding-rate feeds, candles chart the mark price. Use get_latest_price or get_historical_price for the funding rate itself.

convert_date_to_timestampCopy Anchor Link

Convert a date to Unix timestamps for the other tools. No key needed.

TroubleshootingCopy Anchor Link

"This tool requires your Pyth Pro access token"Copy Anchor Link

• Cause: No key reached the server.
• Fix: Configure the key in your client (see Setup), then restart or reconnect the client. Or pass it as access_token.

Invalid or expired keyCopy Anchor Link

• Cause: The server rejected the key (HTTP 401).
• Fix: Check that the header reads exactly Authorization: Bearer <key>, or get a new key from Acquire an API Key.

Not entitled to a feedCopy Anchor Link

• Cause: Your key is valid, but your plan does not include the feed (HTTP 403). The error names the entitlement group it needs.
• Fix: Run get_symbols with your key and pick feeds with entitled: true.

Symbol not found or ambiguousCopy Anchor Link

• Fix: Use the full symbol or a feed ID from get_symbols. For an ambiguous pair, the error lists the matching feeds.

Feed listed in missing_feed_idsCopy Anchor Link

• Cause: get_latest_price or get_historical_price returned no price for the feed. The feed is not live yet (beta or coming_soon), or the channel is faster than the feed's min_channel.
• Fix: Check the feed's state and min_channel in get_symbols, or use a slower channel.

No historical dataCopy Anchor Link

• Fix: Use timestamps from April 2025 onward, and not in the future.

Truncated candlesCopy Anchor Link

• Symptom: Response includes truncated: true
• Fix: Narrow the time range or use a larger resolution.

Local DevelopmentCopy Anchor Link

Optionally run the MCP server locally:

git clone https://github.com/pyth-network/pyth-crosschain.git
cd pyth-crosschain
pnpm install
pnpm --filter @pythnetwork/mcp build

Then configure your client with stdio transport. The local server reads your key from PYTH_PRO_ACCESS_TOKEN:

{
  "mcpServers": {
    "pyth": {
      "command": "node",
      "args": ["<path-to-repo>/apps/mcp/dist/index.js"],
      "env": {
        "PYTH_PRO_ACCESS_TOKEN": "YOUR_API_KEY"
      }
    }
  }
}

MCP SkillsCopy Anchor Link

MCP Skills are pre-built prompt templates that teach AI assistants specific workflows using the Pyth MCP server. Instead of figuring out which tools to call and how to combine them, you can describe what you want in natural language and the skill handles the rest.

Skills work with Claude Code and are installed alongside the MCP server. Each skill listed below includes example prompts you can try directly in your AI assistant.

InstallationCopy Anchor Link

Skills are Claude Code slash commands that live in your project's .claude/skills/ directory. Each skill is a folder containing a SKILL.md file.

PrerequisitesCopy Anchor Link

• Claude Code installed
• Pyth MCP server configured with your API key

SetupCopy Anchor Link

git clone https://github.com/pyth-network/pyth-crosschain.git

cp -r pyth-crosschain/apps/mcp/skills/ your-project/.claude/skills/

your-project/
└── .claude/
    └── skills/
        ├── pyth-alert-conditions/
        │   └── SKILL.md
        ├── pyth-cross-asset-comparison/
        │   └── SKILL.md
        ├── pyth-fx-converter/
        │   └── SKILL.md
        ├── ... (9 skills total)
        └── references/
            └── common.md

/pyth-alert-conditions Is BTC above $100k?
/pyth-fx-converter Convert 1000 EUR to JPY
/pyth-portfolio-tracker I hold 2 BTC and 50 ETH

Available SkillsCopy Anchor Link

Market DataCopy Anchor Link

Price AlertsCopy Anchor Link

Evaluates one-time price conditions — checks if prices are above or below thresholds, if assets have moved by a percentage, or if prices are near period highs or lows. These are point-in-time checks, not persistent alerts.

How it works: Decomposes your question into the data needed, fetches it, evaluates the condition, and answers YES or NO with supporting numbers.

What you can ask:

• "Is BTC above $100k?"
• "Has ETH dropped 5% today?"
• "Is gold near its weekly high?"
• "Has SOL changed more than 10% since June 1?"
• "Is the BTC bid-ask spread above $10?"

Try it:

"Is gold near its weekly high?"

The assistant fetches this week's daily candles and the current price, computes the weekly high from the candle data, and tells you how close the current price is as a percentage.

Cross-Asset ComparisonCopy Anchor Link

Compares price performance across multiple assets by normalizing OHLC data to a common baseline. Converts absolute prices to relative performance so you can compare assets at different price scales (e.g., BTC at $97k vs Gold at$2k).

How it works: Fetches candlestick data for each asset over the same time range, divides each close by the first close (1.0 = starting point), and computes period returns.

What you can ask:

• "Compare Bitcoin vs Gold this quarter"
• "ETH vs SOL performance over the last 30 days"
• "EUR/USD vs GBP/USD over the past week"
• "Which performed better this month: BTC, ETH, or SOL?"

Try it:

"Compare Bitcoin vs Gold this quarter"

The assistant fetches daily candles for both assets, normalizes each series, and presents a side-by-side table showing that, for example, BTC returned +12.4% while Gold returned +4.2%.

Volatility AnalysisCopy Anchor Link

Analyzes price volatility using candlestick data. Computes annualized volatility from close-to-close returns, average true range (ATR), and daily range metrics.

How it works: Fetches candlestick data, calculates daily returns, then computes standard deviation and annualizes it (using 365 days for crypto, 252 for equities/FX).

What you can ask:

• "How volatile is SOL?"
• "Compare the volatility of BTC, ETH, and AAPL"
• "What's the average daily range of gold?"
• "Is ETH more volatile than BTC?"

Try it:

"Compare the volatility of BTC, ETH, and AAPL"

The assistant fetches 30 days of daily candles for each, computes annualized volatility and ATR, and presents a comparison table showing relative risk levels.

Financial WorkflowsCopy Anchor Link

FX ConverterCopy Anchor Link

Converts currencies using Pyth FX and crypto price feeds. Supports fiat-to-fiat, crypto-to-fiat, and historical rate conversions.

How it works: The assistant uses a direct pair, such as EUR/JPY, when Pyth has one live. Otherwise it converts through USD and reads each pair's direction: EUR/USD is dollars per euro, and USD/JPY is yen per dollar.

What you can ask:

• "Convert 1000 EUR to JPY"
• "How much is 5 BTC in EUR?"
• "What was the GBP/JPY rate last Friday?"
• "Convert 500 USD to GBP"

Try it:

"Convert 1000 EUR to JPY"

The assistant finds the live EUR/JPY pair, fetches its rate (e.g., 161.19), and returns: 1000 EUR = 161,190 JPY.

Portfolio TrackerCopy Anchor Link

Tracks a portfolio of assets with current prices, allocation percentages, and P&L calculations. Supports cost-basis and date-based P&L.

How it works: Discovers feeds, batches all assets into a single price call (up to 100 feeds), then computes value, allocation, and optionally compares against historical reference prices.

What you can ask:

• "What's my portfolio worth? I hold 2 BTC, 50 ETH, and 1000 SOL"
• "Show gold, silver, and platinum prices"
• "How has my portfolio performed since last month?"
• "What's the allocation breakdown of my crypto holdings?"

Try it:

"What's my portfolio worth? I hold 2 BTC, 50 ETH, and 1000 SOL"

The assistant fetches all three prices in one call and returns a table with each asset's value and your total portfolio value with allocation percentages.

Funding Rate MonitorCopy Anchor Link

Monitors perpetual futures funding rates to gauge market sentiment. Positive rates indicate long-biased (bullish) markets, negative rates indicate short-biased (bearish) markets.

How it works: Discovers funding rate feeds using the funding-rate asset type, fetches current rates, and tracks how a rate has changed by sampling it with historical price snapshots.

What you can ask:

• "What are the current BTC and ETH funding rates?"
• "Show me all funding rates sorted by magnitude"
• "How has the BTC funding rate changed this week?"
• "Which assets have the highest funding rates right now?"

Try it:

"What are the current BTC and ETH funding rates?"

The assistant fetches both rates and presents them with sentiment labels — for example, BTC at +0.012% (slightly long-biased) and ETH at +0.035% (moderately long-biased).

Data & IntegrationCopy Anchor Link

Data ExportCopy Anchor Link

Exports Pyth price data in CSV, JSON, or Markdown table format. Handles OHLC exports, feed catalog dumps, historical snapshots, and current price tables.

How it works: Fetches all requested data first (with pagination if needed), then formats the complete dataset. Caps exports at 1000 rows.

What you can ask:

• "Export BTC daily OHLC for the last 30 days as CSV"
• "Give me all crypto feeds as JSON"
• "Show current prices for BTC, ETH, and gold as a Markdown table"
• "Export the full feed catalog"

Try it:

"Export BTC daily OHLC for the last 30 days as CSV"

The assistant fetches daily candlestick data and formats it with headers: timestamp,open,high,low,close,volume followed by one row per day.

Time-Series SnapshotsCopy Anchor Link

Fetches price snapshots at specific historical timestamps. Generates timestamp series (monthly, weekly, quarterly) and retrieves prices for each date.

How it works: Generates Unix timestamps for your requested dates, then calls the historical price API once per timestamp with up to 50 feeds per call. For continuous data (more than ~20 points), suggests candlestick data instead.

What you can ask:

• "What was BTC at the start of each month this year?"
• "Show me ETH and SOL prices every Monday for the last 4 weeks"
• "Get quarterly gold prices since April 2025"

Try it:

"What was BTC at the start of each month this year?"

The assistant generates timestamps for April 1, May 1, June 1, etc. (data starts April 2025), fetches each snapshot, and presents a table of monthly prices.

Integration HelperCopy Anchor Link

Guides developers on integrating Pyth price feeds. Explains feed discovery, symbol formats, ID types, price exponents, and data channels.

How it works: Understands your integration context (language, chain, use case), uses feed discovery to find specific feeds, and explains the symbol/ID/exponent/channel system.

What you can ask:

• "How do I use Pyth in my trading bot?"
• "What's the feed ID for AAPL?"
• "What asset types does Pyth support?"
• "How does Pyth Pro work?"
• "How do pricing channels work?"

Try it:

"What's the feed ID for AAPL?"

The assistant searches for AAPL and returns the symbol (Equity.US.AAPL/USD), the Pyth Pro numeric feed ID, and the exponent for price conversion.