# Frontier Labs Stock API - Agent Getting Started

A minimal, dependency-free REST API returning real-time stock prices sourced
from the public Yahoo Finance chart endpoint.

## Base URL
https://stocks.frontierlabs.nl   (or https behind a reverse proxy)

## Endpoints

### GET /api/v1/price?ticker={TICKER}
Returns the latest regular-market price for a ticker symbol.

Success (200 OK, default - 4 fields only):
{
  "ticker": "AAPL",
  "price": 175.42,
  "currency": "USD",
  "timestamp": 1711978432
}

Add &full=1 to also receive:
  - "percentChange": daily move vs previous close, as a percentage (e.g. 0.54)
  - "meta": EVERY raw Yahoo field (exchange, day high/low, volume,
    52-week range, previous close, etc.)
  - "derived": computed, human-friendly analytics:
      {
        "companyName": "Apple Inc.",
        "exchange": "NasdaqGS",
        "asOf": "2026-07-19T14:30:00Z",
        "previousClose": 333.26,
        "dayChange": 0.48,
        "dayRange":      { "low": 329.00, "high": 334.98, "positionPercent": 92.1 },
        "fiftyTwoWeekRange": { "low": 201.50, "high": 334.99, "positionPercent": 99.4 },
        "volume": { "raw": 63325386, "formatted": "63,325,386" },
        "priceDecimals": 2
      }

Errors:
  400  missing or invalid ticker (allowed chars: A-Z a-z 0-9 . -, max 12)
  404  ticker not found or delisted on Yahoo Finance
  500  upstream provider unreachable or blocked

Example requests:
  GET /api/v1/price?ticker=AAPL
  GET /api/v1/price?ticker=AAPL&full=1

### GET /openapi.json
Machine-readable description of this API (endpoints, parameters, schema).

### GET /agent.md
This document.

## Notes
- One request may hit up to two upstream hosts (query1 then query2) for
  resilience; responses are cached by the upstream, not by this server.
- The "timestamp" is the upstream regular-market epoch seconds (UTC).
- "derived.asOf" is the same instant rendered as ISO-8601 UTC.
- "derived.*Range.positionPercent" is where price sits in the band (0-100).
- Do not send more than a few requests per second; this is a thin proxy.