--- name: blockrun-web-vbsbhh7lea-uc.a.run.app description: blockrun-web-vbsbhh7lea-uc.a.run.app provides real-time spot price lookups for US-listed equities and ETFs sourced from Pyth Network. Each skill returns a single current price snapshot with confidence interval, publish timestamp, and feed metadata. The host covers a fixed set of tickers (NVDA, CRCL, GLD, IWM, DIA, QQQ, XLE, SPY, USO, VXUS, BND, BSV, VOO) plus two parameterized endpoints for arbitrary US symbols. host: blockrun-web-vbsbhh7lea-uc.a.run.app --- # blockrun-web-vbsbhh7lea-uc.a.run.app This host is a Pyth Network price relay for US equities and ETFs. It serves agents that need current market prices with on-chain provenance (Pyth feed IDs and confidence intervals) for display, calculation, or decision logic. Most skills are hardcoded to a single ticker; two skills (fetch-us-stock-price and fetch-us-stock-spot-price) accept a symbol parameter for broader coverage. The host does not provide historical data, streaming feeds, or non-US market prices. ## When to use this host Use this host when an agent needs the current Pyth Network spot price for a US-listed equity or ETF, particularly when on-chain feed provenance (feed ID, confidence interval) is required. For arbitrary tickers, prefer fetch-us-stock-price or fetch-us-stock-spot-price over the hardcoded single-ticker skills. Do not use this host for: historical price series or OHLCV data (no such endpoints exist here), non-US markets (the not_for notes reference HK, TSE, KRX, LSE, XETRA, and Euronext alternatives), streaming or tick-by-tick feeds, or crypto asset prices. If the required ticker is not among the hardcoded symbols and the parameterized endpoints do not support it, a different price feed host should be used. ## Capabilities ### Parameterized US Equity Price Lookup Two skills that accept a ticker symbol as input, enabling price lookups for any supported US-listed equity from Pyth Network, including confidence and feed metadata. - **`fetch-us-stock-price`** — Returns the latest US equity price for a given stock symbol, sourced from Pyth, including confidence interval and publish timestamp. - **`fetch-us-stock-spot-price`** — Returns the current spot price for a US-listed stock symbol sourced from Pyth Network, including price, confidence interval, and publish timestamp. ### Fixed-Ticker Index ETF Prices Hardcoded endpoints for major US index ETFs (SPY, QQQ, DIA, IWM, VOO), each returning the latest Pyth-sourced price with confidence interval and timestamp. - **`fetch-us-stock-price-spy`** — Returns the latest SPY US equity price with confidence score, publish time, and Pyth feed metadata via a single GET request. - **`fetch-qqq-us-stock-price`** — Returns the latest real-time US equity price for QQQ (Invesco QQQ Trust) including price, confidence interval, publish time, and data source. - **`fetch-us-stock-price-dia`** — Returns the latest US equity price for DIA (SPDR Dow Jones Industrial Average ETF) including confidence score, publish time, and data source. - **`fetch-iwm-us-price`** — Returns the latest real-time US equity price for IWM (iShares Russell 2000 ETF) sourced from Pyth, including confidence interval and publish timestamp. - **`fetch-us-stock-price-voo`** — Returns the latest US equity price for VOO (Vanguard S&P 500 ETF) including price, confidence score, publish time, and data source. ### Fixed-Ticker Sector and Commodity ETF Prices Hardcoded endpoints for sector and commodity-linked ETFs (XLE, GLD, USO, VXUS, BND, BSV), each returning the latest Pyth-sourced price snapshot. - **`fetch-us-stock-price-xle`** — Returns the current US equity price for XLE (Energy Select Sector SPDR Fund) sourced from Pyth, including price, confidence interval, and publish timestamp. - **`fetch-us-stock-price-gld`** — Returns the latest US equity price for GLD (SPDR Gold Shares) including price, confidence interval, publish time, and data source from Pyth. - **`fetch-uso-stock-price`** — Returns the latest USO (United States Oil Fund) stock price with confidence score, publish time, and source metadata from Pyth Network. - **`fetch-vxus-stock-price`** — Returns the latest U.S. equity price for VXUS (Vanguard Total International Stock ETF) sourced from Pyth, including price, confidence interval, and publish timestamp. - **`fetch-us-stock-price-bnd`** — Returns the latest US equity price for BND (Vanguard Total Bond Market ETF) including confidence interval, publish time, and Pyth feed metadata. - **`fetch-us-stock-price-bsv`** — Returns the latest US equity price for BSV (ticker symbol) including price, confidence score, publish time, and data source metadata. ### Fixed-Ticker Individual Stock Prices Hardcoded endpoints for specific individual equities (NVDA, CRCL), returning the latest Pyth price with confidence and feed metadata. - **`fetch-us-stock-price`** — Returns the latest US equity price for a given stock symbol, sourced from Pyth, including confidence interval and publish timestamp. - **`fetch-us-stock-price-crcl`** — Returns the current US equity price for CRCL (Circle Internet Group) sourced from Pyth, including price, confidence interval, and publish timestamp. ## Workflows ### Multi-Asset Portfolio Snapshot *Use when an agent needs to assemble a current price snapshot across several holdings simultaneously, such as valuing a portfolio containing equities and ETFs.* 1. **`fetch-us-stock-price`** — Fetch the current price for any individual equity (e.g. TSLA) by passing the symbol parameter. 2. **`fetch-us-stock-price-spy`** — Fetch the current SPY price as a broad market benchmark alongside the individual equity. 3. **`fetch-us-stock-price-voo`** — Fetch the current VOO price to compare S&P 500 exposure across two ETF vehicles. ### Equity vs. Benchmark Comparison *Use when an agent needs to compare a specific stock price against a relevant market index ETF to assess relative performance or trigger conditional logic.* 1. **`fetch-us-stock-price`** — Retrieve the latest price for the target US equity symbol. 2. **`fetch-us-stock-price-spy`** — Retrieve the SPY price as the S&P 500 benchmark for comparison. ## Skill reference ### `fetch-us-stock-price` **NVDA Stock Price** — Returns the current US equity price for NVDA sourced from Pyth, including confidence interval, publish time, and feed metadata. *Use when:* Use when an agent needs the latest market price for NVDA (Nvidia) stock as a numeric value with confidence and timestamp, suitable for display, calculation, or downstream trading logic. *Not for:* Do not use for historical price data or other US stock tickers; this endpoint is hardcoded to NVDA only. Not suitable for streaming or real-time tick data. **Returns:** Returns a JSON object with NVDA's current USD price (222.14), a Pyth confidence interval, publish timestamp, asset type of equity, and the Pyth feed ID. **Example:** `GET https://blockrun-web-vbsbhh7lea-uc.a.run.app/api/v1/stocks/us/price/NVDA` --- ### `fetch-us-stock-price` **US Stock Price** — Returns the latest US equity price for a given stock symbol, sourced from Pyth, including confidence interval and publish timestamp. *Use when:* Use when an agent needs the current market price of a US-listed stock (e.g. TSLA) along with price confidence, asset type, and the Pyth feed ID for on-chain reference. *Not for:* Do not use for non-US equities, crypto assets, or historical price series; this is a single-shot latest-price lookup only. **Inputs:** - `symbol` (string, required) — US stock ticker symbol embedded in the URL path (e.g. TSLA, AAPL, MSFT). **Returns:** Returns a JSON object with TSLA's latest USD price (422.14), Pyth confidence interval, publish timestamp, asset type 'equity', and the Pyth feed ID. **Example:** `GET https://blockrun-web-vbsbhh7lea-uc.a.run.app/api/v1/stocks/us/price/TSLA` --- ### `fetch-us-stock-price-crcl` **CRCL Stock Price** — Returns the current US equity price for CRCL (Circle Internet Group) sourced from Pyth, including price, confidence interval, and publish timestamp. *Use when:* Use when an agent needs the latest market price for CRCL stock, including confidence score and feed metadata, to display, compare, or act on equity pricing data. *Not for:* Do not use for historical price data or other ticker symbols; this endpoint is fixed to CRCL only. **Returns:** Returns a JSON object with CRCL's current USD price (114.00), a Pyth confidence interval, publish timestamp, asset type, and feed ID. **Example:** `GET https://blockrun-web-vbsbhh7lea-uc.a.run.app/api/v1/stocks/us/price/CRCL` --- ### `fetch-us-stock-price-gld` **GLD Price Quote** — Returns the latest US equity price for GLD (SPDR Gold Shares) including price, confidence interval, publish time, and data source from Pyth. *Use when:* Use when an agent needs the current market price of GLD (SPDR Gold Shares ETF) as a US equity, along with metadata such as confidence, timestamp, and feed source. *Not for:* Do not use for historical price series or other ticker symbols; this endpoint is fixed to GLD only. **Returns:** Returns a JSON object with GLD's current USD price (~417.37), confidence interval, Unix and ISO publish timestamps, asset type (equity), Pyth feed ID, and source. **Example:** `GET https://blockrun-web-vbsbhh7lea-uc.a.run.app/api/v1/stocks/us/price/GLD` --- ### `fetch-iwm-us-price` **IWM US Price Feed** — Returns the latest real-time US equity price for IWM (iShares Russell 2000 ETF) sourced from Pyth, including confidence interval and publish timestamp. *Use when:* Use when an agent needs the current market price of IWM (iShares Russell 2000 ETF) along with price confidence, asset type, and feed metadata for display, calculation, or decision-making purposes. *Not for:* Do not use for historical price data or price series; this returns only the latest single price snapshot. Not suitable for non-US equities or other asset classes. **Returns:** Returns a JSON object with IWM's latest USD price (282.595), confidence interval, Unix and ISO publish timestamps, asset type (equity), Pyth feed ID, and source. **Example:** `GET https://blockrun-web-vbsbhh7lea-uc.a.run.app/api/v1/stocks/us/price/IWM` --- ### `fetch-us-stock-price-dia` **DIA Stock Price** — Returns the latest US equity price for DIA (SPDR Dow Jones Industrial Average ETF) including confidence score, publish time, and data source. *Use when:* Use when an agent needs the current market price of DIA along with metadata such as confidence, timestamp, feed ID, and source for downstream financial calculations or display. *Not for:* Do not use for historical price series or other ticker symbols; this endpoint is specific to DIA only. **Returns:** Returns a JSON object with DIA's latest USD price, confidence interval, publish timestamp, asset type, Pyth feed ID, and source. **Example:** `GET https://blockrun-web-vbsbhh7lea-uc.a.run.app/api/v1/stocks/us/price/DIA` --- ### `fetch-qqq-us-stock-price` **QQQ US Stock Price** — Returns the latest real-time US equity price for QQQ (Invesco QQQ Trust) including price, confidence interval, publish time, and data source. *Use when:* Use when an agent needs the current market price of QQQ (Invesco QQQ Trust ETF) for display, trading decisions, portfolio valuation, or price-triggered logic. *Not for:* Do not use for historical price data or other ticker symbols; this endpoint is fixed to QQQ only. **Returns:** Returns a JSON object with QQQ's latest price (e.g. 673.62), confidence interval, Unix and ISO publish timestamps, asset type, Pyth feed ID, and source. **Example:** `GET https://blockrun-web-vbsbhh7lea-uc.a.run.app/api/v1/stocks/us/price/QQQ` --- ### `fetch-us-stock-price-xle` **XLE Stock Price** — Returns the current US equity price for XLE (Energy Select Sector SPDR Fund) sourced from Pyth, including price, confidence interval, and publish timestamp. *Use when:* Use when an agent needs the current market price of XLE (Energy Select Sector SPDR ETF) along with its confidence interval and last-updated timestamp for trading decisions, portfolio valuation, or price monitoring. *Not for:* Do not use for historical price data or price series; this returns only the latest single-point price. Not suitable for non-US equities or other tickers — this endpoint is fixed to XLE. **Returns:** Returns a JSON object with XLE's current USD price, Pyth confidence interval, publish Unix timestamp, ISO timestamp, asset type, Pyth feed ID, and source label. **Example:** `GET https://blockrun-web-vbsbhh7lea-uc.a.run.app/api/v1/stocks/us/price/XLE` --- ### `fetch-us-stock-price-spy` **SPY Price Lookup** — Returns the latest SPY US equity price with confidence score, publish time, and Pyth feed metadata via a single GET request. *Use when:* Use when an agent needs the current market price of the SPY ETF (S&P 500 tracker) along with a confidence interval and data source attribution from Pyth Network. *Not for:* Do not use for historical price series or other ticker symbols; this endpoint is hardcoded to SPY only. **Returns:** Returns a JSON object with SPY's latest USD price, confidence interval, publish timestamp, asset type, Pyth feed ID, and source label. **Example:** `GET https://blockrun-web-vbsbhh7lea-uc.a.run.app/api/v1/stocks/us/price/SPY` --- ### `fetch-uso-stock-price` **USO Price Feed** — Returns the latest USO (United States Oil Fund) stock price with confidence score, publish time, and source metadata from Pyth Network. *Use when:* Use when an agent needs the current market price of USO equity, including timestamp and data source provenance, for display, calculation, or decision-making purposes. *Not for:* Do not use for historical price series or other US equities; use a dedicated historical or multi-symbol endpoint instead. **Returns:** Returns a JSON object with USO's current price (e.g. 133.49 USD), confidence interval, Unix and ISO publish timestamps, asset type, Pyth feed ID, and source. **Example:** `GET https://blockrun-web-vbsbhh7lea-uc.a.run.app/api/v1/stocks/us/price/USO` --- ### `fetch-vxus-stock-price` **VXUS Price Check** — Returns the latest U.S. equity price for VXUS (Vanguard Total International Stock ETF) sourced from Pyth, including price, confidence interval, and publish timestamp. *Use when:* Use when an agent needs the current market price of VXUS (Vanguard Total International Stock ETF) along with its confidence value, feed ID, and last publish time for trading or portfolio valuation purposes. *Not for:* Do not use for historical price data or price series; this endpoint returns only the latest single price snapshot. Not suitable for non-US equities or other asset classes. **Returns:** Returns a JSON object with symbol, category, numeric price in USD, confidence interval, Unix and ISO publish timestamps, asset type, Pyth feed ID, and source name. **Example:** `GET https://blockrun-web-vbsbhh7lea-uc.a.run.app/api/v1/stocks/us/price/VXUS` --- ### `fetch-us-stock-price-bnd` **BND Price Feed** — Returns the latest US equity price for BND (Vanguard Total Bond Market ETF) including confidence interval, publish time, and Pyth feed metadata. *Use when:* Use when an agent needs the current market price of BND (Vanguard Total Bond Market ETF) along with price confidence, asset type, and feed source details for display, calculation, or decision-making. *Not for:* Do not use for historical price data or price series; this returns only the latest single price snapshot. Not suitable for non-US equities or other asset classes. **Returns:** Returns a JSON object with BND's latest price (~$73.52), confidence interval, Unix and ISO publish timestamps, asset type (equity), Pyth feedId, and source. **Example:** `GET https://blockrun-web-vbsbhh7lea-uc.a.run.app/api/v1/stocks/us/price/BND` --- ### `fetch-us-stock-price-bsv` **BSV Stock Price** — Returns the latest US equity price for BSV (ticker symbol) including price, confidence score, publish time, and data source metadata. *Use when:* Use when an agent needs the current market price of the BSV US stock, along with metadata such as confidence level, feed ID, and timestamp of the last price update. *Not for:* Do not use for historical price data or price series; this returns only the latest single price snapshot. Not suitable for non-US equities or crypto assets with the same ticker. **Returns:** Returns a JSON object with BSV's latest USD price (78.17), confidence score, Unix and ISO publish timestamps, asset type, Pyth feed ID, and source name. **Example:** `GET https://blockrun-web-vbsbhh7lea-uc.a.run.app/api/v1/stocks/us/price/BSV` --- ### `fetch-us-stock-price-voo` **VOO Stock Price** — Returns the latest US equity price for VOO (Vanguard S&P 500 ETF) including price, confidence score, publish time, and data source. *Use when:* Use when an agent needs the current market price of VOO along with metadata such as confidence level, feed ID, and timestamp for display, calculation, or decision-making purposes. *Not for:* Do not use for historical price data or other ticker symbols; this endpoint is fixed to VOO only. **Returns:** Returns a JSON object with VOO's latest price in USD, a confidence score, Unix and ISO publish timestamps, asset type, Pyth feed ID, and source name. **Example:** `GET https://blockrun-web-vbsbhh7lea-uc.a.run.app/api/v1/stocks/us/price/VOO` --- ### `fetch-us-stock-spot-price` **US Stock Spot Price** — Returns the current spot price for a US-listed stock symbol sourced from Pyth Network, including price, confidence interval, and publish timestamp. *Use when:* Use when an agent needs the latest real-time spot price for a US equity ticker (e.g. AAPL, TSLA) from Pyth Network, including confidence and feed metadata. *Not for:* Do not use for non-US stock markets (use the equivalent HK, TSE, KRX, LSE, XETRA, or Euronext endpoint instead). Not suitable for historical price lookups or streaming price feeds. **Inputs:** - `symbol` (string, required) — US stock ticker symbol as a path parameter. Must match a valid symbol from /list (e.g. AAPL, TSLA). - `session` (string) — Trading session hint. Accepted values: 'regular' or 'extended'. **Returns:** Returns a JSON object with the stock symbol, USD spot price, Pyth confidence interval, publish timestamp, asset type, feed ID, and source. **Example:** `GET https://blockrun-web-vbsbhh7lea-uc.a.run.app/api/v1/stocks/us/price/AAPL?session=regular` ---