{
  "openapi": "3.1.0",
  "info": {
    "title": "Stackit.ai Treasury API",
    "description": "Rules-based BTC & ETH treasury management API. Auto-buy, auto-protect, borrow without liquidation. 2% usage fee per action, 0% on liquidation protection.",
    "version": "1.0.0",
    "contact": {
      "name": "Stackit.ai Support",
      "email": "support@stackit.ai",
      "url": "https://stackit.ai"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://api.stackit.ai",
      "description": "Production"
    },
    {
      "url": "https://sandbox.api.stackit.ai",
      "description": "Sandbox (Coming Soon)"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/deposits": {
      "post": {
        "operationId": "createDeposit",
        "summary": "Create Deposit",
        "description": "Initiates a new USDC deposit into the treasury. The system converts deposited funds into BTC and ETH following the user's configured allocation rules. 2% fee applies.",
        "tags": ["Treasury"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DepositRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deposit initiated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DepositResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/borrow": {
      "post": {
        "operationId": "createBorrow",
        "summary": "Create Borrow",
        "description": "Borrow against existing BTC and ETH holdings. The system enforces LTV limits and rejects requests that would breach the safe range. One-time 2% Stackit.ai fee plus Aave's variable interest rate.",
        "tags": ["Treasury"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BorrowRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Borrow approved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BorrowResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/LtvExceeded" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/convert": {
      "post": {
        "operationId": "convertUsdc",
        "summary": "Convert USDC",
        "description": "Convert USDC holdings into BTC or ETH. Used for dollar-cost averaging and treasury rebalancing. 2% fee applies.",
        "tags": ["Treasury"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConvertRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Conversion initiated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConvertResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/repay": {
      "post": {
        "operationId": "manualRepay",
        "summary": "Manual Repay",
        "description": "Manually repay a portion of the outstanding borrow. Reduces LTV and increases borrowing capacity. No fee.",
        "tags": ["Treasury"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RepayRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Repayment completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RepayResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/treasury": {
      "get": {
        "operationId": "getTreasuryStatus",
        "summary": "Get Treasury Status",
        "description": "Returns the current state of the treasury including holdings, LTV, health score, and utilization. No fee.",
        "tags": ["Monitoring"],
        "responses": {
          "200": {
            "description": "Treasury status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TreasuryResponse"
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "operationId": "getHealthScore",
        "summary": "Get Health Score",
        "description": "Returns the current health score and LTV breakdown. Use this for monitoring and alerts. No fee.",
        "tags": ["Monitoring"],
        "responses": {
          "200": {
            "description": "Health score",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/estimate": {
      "post": {
        "operationId": "estimateFees",
        "summary": "Estimate Fees",
        "description": "Estimate fees and net amounts for a treasury action before executing it. Returns Stackit.ai fee, Aave rate (if applicable), DEX spread (if applicable), and net amount. No fee to call this endpoint.",
        "tags": ["Monitoring"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EstimateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Fee estimate",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EstimateResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "API key issued during onboarding. Format: sk_live_* (production) or sk_test_* (sandbox)."
      }
    },
    "schemas": {
      "DepositRequest": {
        "type": "object",
        "required": ["amount"],
        "properties": {
          "amount": {
            "type": "number",
            "minimum": 100,
            "description": "Amount in USDC to deposit. Minimum 100."
          },
          "allocation": {
            "type": "object",
            "properties": {
              "btc": { "type": "number", "description": "Percentage allocated to BTC." },
              "eth": { "type": "number", "description": "Percentage allocated to ETH." }
            },
            "description": "BTC/ETH split. Defaults to {\"btc\": 50, \"eth\": 50}."
          }
        }
      },
      "DepositResponse": {
        "type": "object",
        "properties": {
          "deposit_id": { "type": "string" },
          "amount_usdc": { "type": "number" },
          "fee_usdc": { "type": "number" },
          "net_amount": { "type": "number" },
          "allocation": {
            "type": "object",
            "properties": {
              "btc": { "type": "number" },
              "eth": { "type": "number" }
            }
          },
          "status": { "type": "string", "enum": ["processing", "completed", "failed"] },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "BorrowRequest": {
        "type": "object",
        "required": ["amount"],
        "properties": {
          "amount": {
            "type": "number",
            "description": "Amount in USDC to borrow."
          },
          "purpose": {
            "type": "string",
            "description": "Optional label for the borrow (e.g., 'payroll', 'expenses')."
          }
        }
      },
      "BorrowResponse": {
        "type": "object",
        "properties": {
          "borrow_id": { "type": "string" },
          "amount_usdc": { "type": "number" },
          "fee_usdc": { "type": "number" },
          "current_ltv": { "type": "number" },
          "ltv_after": { "type": "number" },
          "status": { "type": "string", "enum": ["approved", "rejected"] },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "ConvertRequest": {
        "type": "object",
        "required": ["amount", "target"],
        "properties": {
          "amount": {
            "type": "number",
            "description": "Amount in USDC to convert."
          },
          "target": {
            "type": "string",
            "enum": ["btc", "eth"],
            "description": "Target asset: \"btc\" or \"eth\"."
          }
        }
      },
      "ConvertResponse": {
        "type": "object",
        "properties": {
          "conversion_id": { "type": "string" },
          "amount_usdc": { "type": "number" },
          "fee_usdc": { "type": "number" },
          "target": { "type": "string" },
          "estimated_amount": { "type": "number" },
          "status": { "type": "string", "enum": ["processing", "completed", "failed"] },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "RepayRequest": {
        "type": "object",
        "required": ["amount"],
        "properties": {
          "amount": {
            "type": "number",
            "description": "Amount in USDC to repay."
          }
        }
      },
      "RepayResponse": {
        "type": "object",
        "properties": {
          "repayment_id": { "type": "string" },
          "amount_usdc": { "type": "number" },
          "ltv_before": { "type": "number" },
          "ltv_after": { "type": "number" },
          "remaining_borrow": { "type": "number" },
          "status": { "type": "string", "enum": ["completed", "failed"] }
        }
      },
      "TreasuryResponse": {
        "type": "object",
        "properties": {
          "treasury_id": { "type": "string" },
          "holdings": {
            "type": "object",
            "properties": {
              "btc": { "type": "number" },
              "eth": { "type": "number" },
              "usdc": { "type": "number" }
            }
          },
          "total_value_usd": { "type": "number" },
          "borrowed_usd": { "type": "number" },
          "ltv": { "type": "number" },
          "health_score": { "type": "number" },
          "utilization_score": { "type": "number" },
          "auto_repay_active": { "type": "boolean" }
        }
      },
      "HealthResponse": {
        "type": "object",
        "properties": {
          "health_score": { "type": "number" },
          "ltv": { "type": "number" },
          "ltv_zone": { "type": "string", "enum": ["safe", "active", "ceiling"] },
          "auto_repay_active": { "type": "boolean" },
          "ltv_zones": {
            "type": "object",
            "properties": {
              "safe": {
                "type": "object",
                "properties": { "min": { "type": "number" }, "max": { "type": "number" } }
              },
              "active": {
                "type": "object",
                "properties": { "min": { "type": "number" }, "max": { "type": "number" } }
              },
              "ceiling": {
                "type": "object",
                "properties": { "min": { "type": "number" }, "max": { "type": "number" } }
              },
              "hard_ceiling": { "type": "number" }
            }
          }
        }
      },
      "EstimateRequest": {
        "type": "object",
        "required": ["action", "amount"],
        "properties": {
          "action": {
            "type": "string",
            "enum": ["deposit", "borrow", "convert", "repay"],
            "description": "The action to estimate fees for."
          },
          "amount": {
            "type": "number",
            "description": "Amount in USDC."
          },
          "target": {
            "type": "string",
            "enum": ["btc", "eth"],
            "description": "Target asset (required for convert action)."
          }
        }
      },
      "EstimateResponse": {
        "type": "object",
        "properties": {
          "action": { "type": "string" },
          "amount_usdc": { "type": "number" },
          "stackit_fee": { "type": "number", "description": "Stackit.ai 2% usage fee." },
          "aave_rate": { "type": "number", "nullable": true, "description": "Current Aave variable interest rate (borrow only)." },
          "dex_spread": { "type": "number", "nullable": true, "description": "Estimated DEX spread (convert only)." },
          "net_amount": { "type": "number", "description": "Amount after all fees." },
          "estimated_at": { "type": "string", "format": "date-time" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "code": { "type": "integer" },
          "message": { "type": "string" }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Missing or invalid parameters",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "Unauthorized": {
        "description": "Invalid or missing API key",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "LtvExceeded": {
        "description": "The requested action would breach the configured LTV ceiling (default 60%, adjustable based on lending protocol limits)",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests. Retry after the indicated delay.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      }
    }
  }
}