# Commodity Prices, Momentum & Sentiment — MCP/Agent-Ready API (`palatial_lorikeet/commodity-pulse`) Actor

Commodity prices from licensing-clean sources (World Bank, EIA public domain; BYOK Alpha Vantage/Polygon), B-Xtrender momentum scores, and a daily leaderboard of top-mentioned tickers with LLM sentiment. Agent-ready: callable via MCP, flat JSON rows, pay per row. No scraped quotes, no tweet content.

- **URL**: https://apify.com/palatial\_lorikeet/commodity-pulse.md
- **Developed by:** [Palatial Lorikeet](https://apify.com/palatial_lorikeet) (community)
- **Categories:** AI
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 price rows

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Commodity Prices, Momentum Scores & Social Leaderboard

**One actor that answers three questions your market research, dashboards, or
AI agents keep asking: what are commodities actually trading at, which way is
momentum pointing, and what is the market talking about right now?**

Getting commodity data normally means juggling half a dozen sources — a
government API here, a spreadsheet there, an expensive terminal for anything
social — and then worrying about whether you're even allowed to store and
reuse what you fetched. This actor collapses that into one call with a clean
licensing story: prices come only from sources that permit reuse (World Bank,
US-government data) or from your own API keys; sentiment comes as statistics
we compute ourselves. **No scraped exchange quotes, no redistributed social
content — nothing you have to think twice about building on.**

It's built agent-first: every mode returns flat, predictable JSON rows an LLM
agent or a pandas one-liner can consume directly, and the whole catalog is
discoverable with a free `list` call. Ask it for two years of gold prices, a
momentum read on WTI, or this week's most-talked-about tickers with their
sentiment — same actor, one line of input each.

### Use from AI agents (MCP)

This actor is callable through **Apify's MCP server** — point your agent at
`https://mcp.apify.com` (authorized with your Apify token) and it can discover
this actor and run it like any tool:

```json
{
  "actor": "palatial_lorikeet/commodity-pulse",
  "input": { "mode": "leaderboard" }
}
```

Every mode returns flat JSON rows with stable field names — no HTML, no
nested blobs — so results drop straight into an agent's context or a
DataFrame. Typical agent patterns: pull the daily sentiment leaderboard as
market context, check momentum state before a simulated trade, or fetch a
price history for charting and analysis.

### What you get

**Four modes, one actor:**

| Mode | What it returns | Charged per |
|---|---|---|
| `fetch` | Normalized price rows: `series_id, date, value, unit, source` | price row |
| `score` | B-Xtrender momentum composite per date (daily + weekly + monthly momentum states, RSI, integer score −8..+8) | score row |
| `leaderboard` | Daily snapshot: top-25 most-mentioned tickers on finance social media with LLM sentiment aggregates, plus commodity topics (gold, oil, natgas, …) with mention z-scores | leaderboard row |
| `list` | The full series catalog | free |

### Price series

- **World Bank Pink Sheet (monthly)** — WTI, Brent, natural gas, gold, silver,
  copper, wheat, maize, coffee, sugar. Always current: the actor resolves the
  latest release automatically.
- **EIA daily spot** (WTI Cushing, Brent, Henry Hub) — US-government data,
  rolling out.
- **Bring-your-own-key (daily)** — Alpha Vantage commodity endpoints and
  Polygon commodity-ETF proxies (GLD, SLV, USO, UNG) using *your* API key;
  your data relationship stays between you and your provider.

### Momentum scores

The `score` mode runs a B-Xtrender-based composite on any daily series:
short-term momentum state, completed-bar weekly and monthly states (no
lookahead — a bar's state is only used after the bar closes), RSI(14), and an
integer composite score. Built for systematic filters and agent decision
inputs, not chart art.

### Social leaderboard

Refreshed daily from a curated set of finance accounts:

- **Top 25 tickers by mention volume** (7-day window) with sentiment
  aggregates — each ticker's tweets are individually scored by an LLM that
  reads trader slang and sarcasm, not just surface tone.
- **Commodity topics** (gold, silver, oil, natgas, wheat, corn) with mention
  counts, attention z-scores, and sentiment.

**Aggregates only.** The feed contains counts and statistics — never tweet
text or user content.

Example leaderboard row:

```json
{
  "date": "2026-08-09",
  "window_days": 7,
  "kind": "symbol",
  "symbol": "PLTR",
  "mentions_7d": 82,
  "sentiment_n": 21,
  "sentiment_mean": 0.41
}
```

### Input

```json
{
  "mode": "fetch",
  "series": "wti_monthly_wb",
  "start": "2026-01-01",
  "end": "2026-08-01"
}
```

Run `mode: "list"` to see every series id. BYOK series take your key in the
`api_key` field (stored as a secret input).

### Licensing & attribution

- World Bank Pink Sheet: CC BY 4.0 — "Source: World Bank, Commodity Markets (CMO)."
- EIA / USDA series: US-government public domain.
- BYOK series: fetched with your credentials under your provider agreement.
- Momentum scores and leaderboard aggregates are original derived data.

### Support

Issues and feature requests (additional series, more tickers, delivery
formats) are welcome via the actor's Issues tab.

# Actor input Schema

## `mode` (type: `string`):

fetch = normalized price rows; score = B-Xtrender momentum composite per date; leaderboard = daily top-mentioned symbols + LLM sentiment aggregates (no tweet content); list = available series

## `series` (type: `string`):

e.g. wti\_spot\_daily, gold\_monthly\_wb, wti\_daily\_byok\_av (run mode=list to see all)

## `start` (type: `string`):

Earliest date to include (YYYY-MM-DD). Omit for full history.

## `end` (type: `string`):

Latest date to include (YYYY-MM-DD). Omit for up to the latest available.

## `api_key` (type: `string`):

For **byok** series: your own Alpha Vantage / Polygon key. Licensing of fetched values is between you and that provider.

## Actor input object example

```json
{
  "mode": "fetch",
  "series": "wti_monthly_wb"
}
```

# Actor output Schema

## `rows` (type: `string`):

Price / score / leaderboard / catalog rows, depending on the selected mode.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("palatial_lorikeet/commodity-pulse").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("palatial_lorikeet/commodity-pulse").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call palatial_lorikeet/commodity-pulse --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,palatial_lorikeet/commodity-pulse"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/rI1F3e4BmPhOghnQ9/builds/0ku34kLHaO0imwwTO/openapi.json