{
  "openapi": "3.1.0",
  "info": {
    "title": "Stablecoin Atlas API",
    "version": "1.0.0",
    "x-api-version": "2026-05-01",
    "description": "REST API for programmatic access to regulated stablecoin models, regimes, reserves, chains, issuers, and a change feed.",
    "contact": { "name": "Stablecoin Atlas", "url": "https://stablecoinlens.live/api-access" },
    "license": { "name": "Proprietary" }
  },
  "servers": [
    { "url": "https://api.stablecoinlens.live", "description": "Production" }
  ],
  "security": [{ "BearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_live_… / sk_test_…" }
    },
    "schemas": {
      "Reserves": {
        "type": "object",
        "required": ["type", "last_updated"],
        "properties": {
          "type": { "type": "string", "example": "fiat" },
          "attestation_url": { "type": "string", "format": "uri" },
          "last_updated": { "type": "string", "format": "date-time" }
        }
      },
      "Fees": {
        "type": "object",
        "properties": {
          "mint_bps": { "type": "integer", "minimum": 0 },
          "redeem_bps": { "type": "integer", "minimum": 0 }
        }
      },
      "Model": {
        "type": "object",
        "required": ["id", "name", "issuer", "category", "regimes", "chains", "reserves", "updated_at"],
        "properties": {
          "id": { "type": "string", "example": "usdc" },
          "name": { "type": "string" },
          "issuer": { "type": "string" },
          "category": { "type": "string", "enum": ["fiat-backed", "crypto-backed", "algorithmic", "rwa"] },
          "regimes": { "type": "array", "items": { "type": "string" } },
          "chains": { "type": "array", "items": { "type": "string" } },
          "reserves": { "$ref": "#/components/schemas/Reserves" },
          "fees": { "$ref": "#/components/schemas/Fees" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "Regime": {
        "type": "object",
        "required": ["code", "jurisdiction", "updated_at"],
        "properties": {
          "code": { "type": "string", "example": "EU-MiCA-EMT" },
          "jurisdiction": { "type": "string" },
          "issuers": { "type": "array", "items": { "type": "string" } },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "ChangeEvent": {
        "type": "object",
        "required": ["id", "type", "resource_id", "occurred_at"],
        "properties": {
          "id": { "type": "string" },
          "type": { "type": "string", "enum": ["model.created", "model.updated", "regime.updated"] },
          "resource_id": { "type": "string" },
          "occurred_at": { "type": "string", "format": "date-time" },
          "diff": { "type": "object", "additionalProperties": true }
        }
      },
      "PageMeta": {
        "type": "object",
        "required": ["request_id", "limit", "has_more"],
        "properties": {
          "request_id": { "type": "string" },
          "limit": { "type": "integer" },
          "next_cursor": { "type": ["string", "null"] },
          "has_more": { "type": "boolean" }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "request_id"],
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" },
              "fields": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": { "type": "string" },
                    "reason": { "type": "string" }
                  }
                }
              },
              "request_id": { "type": "string" },
              "docs_url": { "type": "string", "format": "uri" }
            }
          }
        }
      }
    },
    "parameters": {
      "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } },
      "Cursor": { "name": "cursor", "in": "query", "schema": { "type": "string" } },
      "Sort": { "name": "sort", "in": "query", "schema": { "type": "string" }, "description": "Field to sort by, prefix - for descending" }
    },
    "responses": {
      "ErrorResponse": {
        "description": "Error",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  },
  "paths": {
    "/v1/models": {
      "get": {
        "operationId": "listModels",
        "summary": "List stablecoin models",
        "parameters": [
          { "name": "category", "in": "query", "schema": { "type": "string" } },
          { "name": "regime", "in": "query", "schema": { "type": "string" } },
          { "name": "chain", "in": "query", "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Cursor" },
          { "$ref": "#/components/parameters/Sort" }
        ],
        "responses": {
          "200": {
            "description": "Page of models",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } },
                    "meta": { "$ref": "#/components/schemas/PageMeta" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/ErrorResponse" },
          "429": { "$ref": "#/components/responses/ErrorResponse" }
        }
      }
    },
    "/v1/models/{id}": {
      "get": {
        "operationId": "getModel",
        "summary": "Retrieve a model by id",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Single model",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "data": { "$ref": "#/components/schemas/Model" } }
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/ErrorResponse" }
        }
      }
    },
    "/v1/regimes": {
      "get": {
        "operationId": "listRegimes",
        "summary": "List regulatory regimes",
        "parameters": [
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Cursor" }
        ],
        "responses": {
          "200": {
            "description": "Page of regimes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Regime" } },
                    "meta": { "$ref": "#/components/schemas/PageMeta" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/changes": {
      "get": {
        "operationId": "listChanges",
        "summary": "Append-only change feed",
        "parameters": [
          { "name": "since", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } },
          { "name": "type", "in": "query", "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Cursor" }
        ],
        "responses": {
          "200": {
            "description": "Page of change events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeEvent" } },
                    "meta": { "$ref": "#/components/schemas/PageMeta" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhooks": {
      "post": {
        "operationId": "createWebhook",
        "summary": "Register a webhook subscription",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url", "events"],
                "properties": {
                  "url": { "type": "string", "format": "uri" },
                  "events": { "type": "array", "items": { "type": "string" } }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string" },
                    "secret": { "type": "string", "description": "Shown once. Used to verify X-Atlas-Signature." }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}