# Commodity Prices API & Momentum Signals — MCP (`palatial_lorikeet/commodity-pulse`) Actor

Get current WTI momentum plus World Bank, EIA, and USDA commodity prices in flat JSON through API or MCP. Price history, signals, and sentiment.

- **URL**: https://apify.com/palatial\_lorikeet/commodity-pulse.md
- **Developed by:** [Palatial Lorikeet](https://apify.com/palatial_lorikeet) (community)
- **Categories:** Business, Developer tools, MCP servers
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 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/actors/running/actors-in-store.md#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 API & Momentum Signals

**Get one current WTI price and momentum signal for a $0.002 custom-event
charge, or pull normalized commodity history, USDA cash bids, and aggregate
market sentiment through the same API/MCP tool.**

### Quick start

The default run returns one actionable WTI row—price, composite momentum,
daily/weekly/monthly states, RSI, freshness, and provenance. It does not pull
or charge for the full history.

#### curl

```bash
curl -sS -X POST \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"latest","series":"wti_spot_daily"}' \
  "https://api.apify.com/v2/acts/palatial_lorikeet~commodity-pulse/run-sync-get-dataset-items"
```

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("palatial_lorikeet/commodity-pulse").call(
    run_input={"mode": "latest", "series": "wti_spot_daily"},
)
rows = client.dataset(run.default_dataset_id).list_items().items
print(rows[:3])
```

#### JavaScript

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('palatial_lorikeet/commodity-pulse').call({
    mode: 'latest',
    series: 'wti_spot_daily',
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items.slice(0, 3));
```

#### AI agent via MCP

Connect the Apify MCP server at `https://mcp.apify.com`, then ask:

> Run `palatial_lorikeet/commodity-pulse` in latest mode for
> `wti_spot_daily`. Explain the momentum score and whether daily, weekly, and
> monthly states agree. Mention the observation date and freshness.

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 catalog-only `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

**Five modes, one actor:**

| Mode | What it returns | Charged per |
|---|---|---|
| `latest` | One current daily price + B-Xtrender momentum signal | score row ($0.002) |
| `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 | no custom charge; Apify platform micro-events may apply |

### Predictable example costs

The input form caps `fetch` and `score` output at 24 newest rows by default.
API callers can omit `max_rows` for backward-compatible full history or set an
explicit higher cap.

| Example | Custom-event charge |
|---|---:|
| Default latest WTI signal | 1 × $0.002 = **$0.002** |
| 24 normalized price rows | 24 × $0.001 = **$0.024** |
| 24 dated momentum scores | 24 × $0.002 = **$0.048** |
| Current ~32-row sentiment leaderboard | ~32 × $0.01 = **~$0.32** |

Apify's small Actor-start, dataset-item, or platform-usage charges may also
apply. Set a maximum run budget in Apify when you need a hard ceiling.

### Runnable examples

- [`examples/latest_wti_signal.py`](examples/latest_wti_signal.py) — one current WTI signal.
- [`examples/usda_cash_bids.py`](examples/usda_cash_bids.py) — recent Iowa corn bids in pandas.
- [`examples/mcp_daily_briefing.md`](examples/mcp_daily_briefing.md) — connect through Apify MCP and request a daily briefing.

### 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,
  available for both normalized price history and momentum scores.
- **USDA daily agricultural cash bids** — Iowa corn and soybeans plus Kansas
  hard-red-winter wheat. Each series is the daily mean of current
  country-elevator regional bids, labeled explicitly in `mode: "list"`.
- **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": "latest",
  "series": "wti_spot_daily"
}
```

For history, use `mode: "fetch"` or `mode: "score"` with `start`, `end`, and
`max_rows`. Run `mode: "list"` to see every series id. BYOK series take your
key in the `api_key` field (stored as a secret input).

### Commodity prices API FAQ

#### Can I fetch WTI, Brent, and Henry Hub prices?

Yes. EIA daily spot series are available as `wti_spot_daily`,
`brent_spot_daily`, and `henry_hub_daily`. Use `latest` for one signal,
`fetch` for prices, or `score` for dated momentum history.

#### Does the USDA cash bids API return national futures prices?

No. The USDA series are transparent regional means of current
country-elevator cash bids: Iowa corn/soybeans and Kansas HRW wheat.

#### Can an AI agent call the commodity data through MCP?

Yes. Connect to Apify's MCP server, discover `palatial_lorikeet/commodity-pulse`,
and call any mode with the same JSON input used by the API.

### 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`):

latest = one current price + momentum signal (~$0.002); fetch = normalized price history; score = dated momentum history; leaderboard = daily top-mentioned symbols + LLM sentiment aggregates; list = available series

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

e.g. wti\_spot\_daily, gold\_monthly\_wb, iowa\_corn\_cash\_daily (run mode=list to see all). latest/score require a daily series.

## `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.

## `max_rows` (type: `integer`):

Safety cap for fetch/score output and charges. The newest rows are returned after indicators are calculated. Ignored by latest/list/leaderboard.

## `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": "latest",
  "series": "wti_spot_daily",
  "max_rows": 24
}
```

# Actor output Schema

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

Latest signal / 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/Nh2BzVe1HCmznXVqz/openapi.json