{
  "openapi": "3.1.0",
  "info": {
    "title": "BestSendRate Open Historical Rate API",
    "version": "1.0.0",
    "description": "Daily money-transfer quotes across verified providers and routes. Responses include rates, fees and recipient amounts.",
    "license": { "name": "CC BY 4.0", "url": "https://creativecommons.org/licenses/by/4.0/" }
  },
  "servers": [{ "url": "https://bestsendrate.com" }],
  "paths": {
    "/api/statistics/catalog/": {
      "get": {
        "operationId": "getStatisticsCatalog",
        "summary": "List available providers, routes, dimensions and date coverage",
        "responses": { "200": { "description": "Dataset catalogue", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/api/statistics/": {
      "get": {
        "operationId": "getHistoricalRates",
        "summary": "Filter and paginate daily historical money-transfer quotes",
        "parameters": [
          { "name": "provider", "in": "query", "schema": { "type": "string" } },
          { "name": "route", "in": "query", "schema": { "type": "string" } },
          { "name": "amount", "in": "query", "schema": { "type": "number" } },
          { "name": "mode", "in": "query", "schema": { "type": "string", "enum": ["standard", "promo"] } },
          { "name": "payIn", "in": "query", "schema": { "type": "string" } },
          { "name": "payOut", "in": "query", "schema": { "type": "string" } },
          { "name": "method", "in": "query", "schema": { "type": "string" } },
          { "name": "fromCountry", "in": "query", "schema": { "type": "string" } },
          { "name": "toCountry", "in": "query", "schema": { "type": "string" } },
          { "name": "fromCurrency", "in": "query", "schema": { "type": "string" } },
          { "name": "toCurrency", "in": "query", "schema": { "type": "string" } },
          { "name": "from", "in": "query", "description": "First UTC date, inclusive", "schema": { "type": "string", "format": "date" } },
          { "name": "to", "in": "query", "description": "Last UTC date, inclusive", "schema": { "type": "string", "format": "date" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } },
          { "name": "order", "in": "query", "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc" } },
          { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["json", "csv"], "default": "json" } }
        ],
        "responses": {
          "200": {
            "description": "A paginated historical quote result",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/StatisticsResponse" } },
              "text/csv": { "schema": { "type": "string" } }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "StatisticsResponse": {
        "type": "object",
        "required": ["schemaVersion", "license", "generatedAt", "pagination", "summary", "data"],
        "properties": {
          "schemaVersion": { "type": "string" },
          "license": { "type": "string" },
          "generatedAt": { "type": "integer", "description": "Unix epoch milliseconds" },
          "pagination": { "type": "object" },
          "summary": { "type": "object" },
          "trend": { "type": "array", "items": { "type": "object" } },
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/DailyQuote" } }
        }
      },
      "DailyQuote": {
        "type": "object",
        "properties": {
          "date": { "type": "string", "format": "date" }, "provider": { "type": "string" }, "providerName": { "type": "string" }, "route": { "type": "string" },
          "fromCountry": { "type": "string" }, "toCountry": { "type": "string" }, "fromCurrency": { "type": "string" }, "toCurrency": { "type": "string" },
          "amount": { "type": "number" }, "mode": { "type": "string" }, "payIn": { "type": "string" }, "payOut": { "type": "string" }, "method": { "type": "string" },
          "rate": { "type": "number" }, "fee": { "type": "number" }, "feeCurrency": { "type": "string" }, "recipientAmount": { "type": "number" },
          "deliveryMinutes": { "type": ["integer", "null"] }, "midRate": { "type": ["number", "null"] }, "marginPct": { "type": ["number", "null"] }, "promoTitle": { "type": ["string", "null"] }, "confidence": { "type": "string" }
        }
      }
    }
  }
}