{
  "openapi": "3.1.0",
  "info": {
    "title": "Thai FX Compare API",
    "version": "1.0.0",
    "description": "Normalized Thai bank TT buying/selling exchange rates, rankings, bank metadata and historical observations. All documented GET endpoints are free and require no API key during beta."
  },
  "servers": [
    {
      "url": "https://fxratetracker.njtools.workers.dev"
    }
  ],
  "tags": [
    {
      "name": "Public",
      "description": "No API key required. Cached, fair-use endpoints for latest Thai bank FX comparisons."
    }
  ],
  "paths": {
    "/api/public/rates": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "Compare current Thai bank TT rates",
        "description": "Returns only current bank-published quotes. Selling is ordered lowest-first; buying is ordered highest-first.",
        "operationId": "getPublicThaiBankFxRates",
        "parameters": [
          {
            "name": "currency",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Z]{3}$",
              "default": "CNY"
            },
            "description": "ISO 4217 currency code, e.g. CNY, USD, EUR."
          },
          {
            "name": "side",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "selling",
                "buying"
              ],
              "default": "selling"
            },
            "description": "selling = bank TT selling (pay THB to buy foreign currency); buying = bank TT buying/transfer (receive THB from foreign currency)."
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked current rates",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string"
                }
              },
              "X-RateLimit-Policy": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid currency"
          }
        }
      }
    },
    "/api/public/banks": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "List banks and stored currencies",
        "operationId": "getPublicThaiBankList",
        "responses": {
          "200": {
            "description": "Bank list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string"
                    },
                    "access": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Bank"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/rates/{currency}": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "Get current rates",
        "operationId": "getCommercialThaiBankFxRates",
        "parameters": [
          {
            "name": "currency",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Z]{3}$"
            }
          },
          {
            "name": "side",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "selling",
                "buying"
              ],
              "default": "selling"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked current rates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateList"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/history/{currency}": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "Get historical rates for one bank",
        "operationId": "getThaiBankFxHistory",
        "parameters": [
          {
            "name": "currency",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Z]{3}$"
            }
          },
          {
            "name": "bank",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Bank ID, e.g. BOCT, KBANK, BBL."
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 90,
              "default": 30
            }
          },
          {
            "name": "side",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "selling",
                "buying"
              ],
              "default": "selling"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Historical observations"
          }
        }
      }
    },
    "/api/v1/banks": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "List banks",
        "operationId": "getCommercialThaiBankList",
        "responses": {
          "200": {
            "description": "Bank list"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Rate": {
        "type": "object",
        "properties": {
          "bank_id": {
            "type": "string"
          },
          "bank": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "side": {
            "type": "string",
            "enum": [
              "selling",
              "buying"
            ]
          },
          "rate": {
            "type": "number"
          },
          "unit": {
            "type": "string"
          },
          "source_updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "fetched_at": {
            "type": "string",
            "format": "date-time"
          },
          "source_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "rank": {
            "type": "integer"
          }
        }
      },
      "RateList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "const": "fx_rate_list"
          },
          "access": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "side": {
            "type": "string"
          },
          "retrieved_at": {
            "type": "string",
            "format": "date-time"
          },
          "count": {
            "type": "integer"
          },
          "best": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Rate"
              },
              {
                "type": "null"
              }
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Rate"
            }
          }
        }
      },
      "Bank": {
        "type": "object",
        "properties": {
          "bank_id": {
            "type": "string"
          },
          "bank": {
            "type": "string"
          },
          "currencies": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "latest_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "current": {
            "type": "boolean"
          }
        }
      }
    }
  }
}