Agent guide

Use Price Action API from an AI agent

Language models are poor at reading charts and worse at doing bar-by-bar arithmetic. Give your agent one tool that returns objective market structure as plain fields, and let it reason over that instead.

By 345 Strategies. Last updated October 23, 2026

1. Start from the OpenAPI spec

Agent frameworks and OpenAPI-to-MCP bridges can load /openapi.json directly. It describes both endpoints, their parameters, the response fields, and bearer auth. Get a free API key first: it is issued instantly, with no credit card.

2. Or define one tool by hand

One focused tool is usually better than exposing the whole API. This definition uses JSON Schema, which tool-calling APIs from the major model providers accept with minor key renames.

Tool definition

{
  "name": "get_market_structure",
  "description": "Get current, objective bar states (TheStrat 1, 2u, 2d, 3, failed breaks), above/below-open markers, and timeframe continuity for US index ETFs. Use before reasoning about trend, breakouts, or consolidation.",
  "input_schema": {
    "type": "object",
    "properties": {
      "symbols": {
        "type": "string",
        "description": "Comma-separated. Any of SPY, QQQ, DIA, IWM."
      },
      "timeframes": {
        "type": "string",
        "description": "Comma-separated. Any of M, W, D, H1, 30m, 15m, 5m."
      }
    },
    "required": ["symbols"]
  }
}

The handler calls /v1/snapshot and returns only the continuity and interpretation notes, which keeps the tool result short.

Handler (JavaScript)

async function getMarketStructure({ symbols, timeframes = "M,W,D,H1,15m" }) {
  const url = new URL("https://priceactionapi.com/v1/snapshot");
  url.searchParams.set("symbols", symbols);
  url.searchParams.set("tf", timeframes);

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.PRICE_ACTION_API_KEY}` },
  });

  if (!response.ok) {
    const { error } = await response.json();
    return { error: error.code, message: error.message };
  }

  // Return the compact parts an agent reasons over.
  const snapshot = await response.json();
  return Object.fromEntries(
    Object.entries(snapshot.events).map(([symbol, event]) => [
      symbol,
      {
        continuity: event.continuity,
        interpretation: event.interpretation,
      },
    ]),
  );
}

What the agent sees

{
  "SPY": {
    "continuity": {
      "display": "M:2u W:1> D:2u H1:F2d 15m:2u",
      "full_continuity": "none"
    },
    "interpretation": [
      "SPY day is above the prior day's high.",
      "SPY is an inside week.",
      "The monthly, weekly, and daily trend is mixed.",
      "60 and 15 minute trend is mixed."
    ]
  }
}

3. Run it responsibly

Keep the key server-side

Run the tool handler in your agent's backend. Never put the key in a prompt, a browser, or a shared notebook.

Budget your calls

Free keys allow 10 requests per minute and 1,000 per day. Batch symbols and timeframes into one call instead of one call per pair.

Treat it as context, not advice

The API describes what price did. It does not recommend trades, so your agent's own rules decide what to do with it.

Check status before acting

A snapshot with status warming_up or a timeframe with status missing has no data yet. Outside market hours, states reflect the last session.

Field definitions are in the API docs and the Bar States guide.