Unified Market API Quickstart

Welcome to pota.ai. Query financial equities, physical agricultural spot benchmarks (Rice, Coconut, Palm Oil), and historical consumer retail prices through unified REST endpoints.

pip install pota-market-data
# or npm: npm install @pota-ai/client

GET AGRO SPOT /v1/commodities/agro/{commodity}/spot-prices

Agro Commodity Spot & Farmgate Rates

Retrieve official physical benchmark prices and wholesale auction spreads for agricultural crops. Supported commodities include: RICE_PREMIUM, RICE_MEDIUM, COCONUT_COPRA, COCONUT_CRUDE_OIL, PALM_OIL_CPO, COFFEE_ROBUSTA, COFFEE_ARABICA, and COCOA_BEANS.

Example Request:

curl -X GET "https://api.pota.ai/v1/commodities/agro/rice/spot-prices?grade=premium_long_grain®ion=SE_ASIA¤cy=USD" \
     -H "Authorization: Bearer YOUR_API_KEY"

Python SDK Example:

from pota import PotaClient

client = PotaClient(api_key="YOUR_API_KEY")
rice_spot = client.agro.get_spot("RICE_PREMIUM", grade="long_grain_5pct")
print(f"Price: ${rice_spot.price_per_mt} USD/MT | Farmgate Spread: {rice_spot.farmgate_spread}%")

GET RETAIL TIME-SERIES /v1/retail/prices/history

Retail Pricing History & Margin Spreads

Access up to 10+ years of point-of-sale scanner and shelf price history for consumer grocery goods and retail commodities. Filter by barcode (EAN/UPC), category, or market region.

Example Request:

curl -X GET "https://api.pota.ai/v1/retail/prices/history?item=RICE_PREMIUM_5KG&from=2021-01-01&to=2026-10-12&granularity=monthly" \
     -H "Authorization: Bearer YOUR_API_KEY"

Response Schema:

{
  "item_code": "RICE_PREMIUM_5KG",
  "category": "STAPLE_GRAINS",
  "currency": "USD",
  "historical_data": [
    { "date": "2026-10-01", "avg_shelf_price": 6.85, "min_price": 6.40, "max_price": 7.30, "sample_stores": 2840 },
    { "date": "2026-09-01", "avg_shelf_price": 6.78, "min_price": 6.35, "max_price": 7.25, "sample_stores": 2840 }
  ]
}

AI MCP pota.ai/mcp/v1

Model Context Protocol (MCP) Setup

Provide real-time market access to Claude Code, Cursor, and ChatGPT for autonomous analysis of agricultural crop yields, retail inflation, and equity prices:

{
  "mcpServers": {
    "pota": {
      "command": "npx",
      "args": ["-y", "@pota-ai/mcp-server"],
      "env": {
        "POTA_API_KEY": "YOUR_POTA_API_KEY"
      }
    }
  }
}

GET /v1/stocks/{ticker}/aggregates

US Stock Candlestick Aggregates

Retrieve normalized minute, hour, or daily aggregate bars for US equities.

curl -X GET "https://api.pota.ai/v1/stocks/AAPL/aggregates?timespan=minute&multiplier=1" \
     -H "Authorization: Bearer YOUR_API_KEY"