{
  "openapi": "3.1.0",
  "info": {
    "title": "MazalGold read-only agent API",
    "version": "1.0.0",
    "description": "Public market references and user-authorized saved records. No tool or route in this description can create, change, or delete a record. Prices are reference data, not executable quotes."
  },
  "servers": [{"url": "https://mazalgold.com"}],
  "paths": {
    "/api/markets": {
      "get": {"operationId": "listMarkets", "summary": "Read the latest stored prices for all available markets", "description": "Public. Data is read from the MazalGold store; this call does not trigger an upstream price-provider request.", "responses": {"200": {"description": "Stored market snapshot", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string"}, "providerAt": {"type": "string", "format": "date-time"}, "receivedAt": {"type": "string", "format": "date-time"}, "prices": {"type": "array", "items": {"type": "object"}}}}}}}}}
    },
    "/api/metals": {
      "get": {"operationId": "listPreciousMetals", "summary": "Read the latest stored five-metal USD prices", "responses": {"200": {"description": "Gold, silver, platinum, palladium and rhodium prices", "content": {"application/json": {"schema": {"type": "object"}}}}}}
    },
    "/api/closes": {
      "get": {"operationId": "listPreciousMetalDailyMarks", "summary": "Read stored daily-close marks", "description": "Nearest stored observations to adopted market cutoffs, not official settlements or trade-price locks.", "parameters": [{"name": "year", "in": "query", "required": false, "schema": {"type": "string", "pattern": "^20[0-9]{2}$", "default": "2026"}}], "responses": {"200": {"description": "Stored close marks", "content": {"application/json": {"schema": {"type": "object"}}}}}}
    },
    "/v1/instruments": {
      "get": {"operationId": "listInstruments", "summary": "Read symbols, units and coverage metadata", "responses": {"200": {"description": "Instrument registry", "content": {"application/json": {"schema": {"type": "object"}}}}}}
    },
    "/v1/series/{symbol}": {
      "get": {"operationId": "readPriceSeries", "summary": "Read stored historical price observations", "description": "USD only. Half-open UTC interval [start,end). Last observation per bucket; gaps are not interpolated. Live and backfill sources remain separate.", "parameters": [{"name": "symbol", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "start", "in": "query", "required": true, "schema": {"type": "string", "format": "date-time"}}, {"name": "end", "in": "query", "required": true, "schema": {"type": "string", "format": "date-time"}}, {"name": "interval", "in": "query", "required": false, "schema": {"type": "string", "enum": ["1m", "1h", "1d"], "default": "1h"}}], "responses": {"200": {"description": "Stored series by source", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "Invalid range, resolution or symbol"}}}
    },
    "/agents/api/records": {
      "get": {"operationId": "readOwnSavedRecords", "summary": "Read records saved to the authorizing account", "description": "Requires a 30-day read-only connection token created by the account owner at /agents. Includes seller details. No access to guest browser-only records, unsynced changes, prediction entries, or owner controls.", "security": [{"readOnlyToken": []}], "parameters": [{"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}}, {"name": "offset", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 0, "maximum": 500, "default": 0}}], "responses": {"200": {"description": "Paged saved account records", "content": {"application/json": {"schema": {"type": "object", "required": ["records", "total", "limit", "offset", "nextOffset"], "properties": {"records": {"type": "array", "items": {"type": "object"}}, "total": {"type": "integer"}, "limit": {"type": "integer"}, "offset": {"type": "integer"}, "nextOffset": {"type": ["integer", "null"]}}}}}}, "401": {"description": "Missing, expired or revoked connection"}, "429": {"description": "Read limit reached"}}}
    }
  },
  "components": {"securitySchemes": {"readOnlyToken": {"type": "http", "scheme": "bearer", "description": "Create a read-only token in your signed-in MazalGold /agents page. Keep it out of prompts, URLs and logs. Tokens expire after 30 days and can be revoked."}}}
}