{
  "openapi": "3.1.0",
  "info": {
    "title": "Metrifly Partner API",
    "version": "1.0.0",
    "description": "Versioned public API for approved Metrifly technology partners."
  },
  "servers": [
    {
      "url": "https://api.metrifly.com/v1",
      "description": "Production"
    },
    {
      "url": "https://dev-api.metrifly.com/v1",
      "description": "Development"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/me": {
      "get": {
        "summary": "Get authenticated partner identity",
        "operationId": "getPartnerMe",
        "responses": {
          "200": {
            "description": "Partner identity and grants",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnvelopePartnerMe"
                }
              }
            }
          }
        }
      }
    },
    "/portfolios": {
      "get": {
        "summary": "List granted portfolios",
        "operationId": "listPortfolios",
        "responses": {
          "200": {
            "description": "Granted portfolios",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnvelopePortfolioList"
                }
              }
            }
          }
        }
      }
    },
    "/portfolios/{portfolioId}": {
      "get": {
        "summary": "Get a granted portfolio",
        "operationId": "getPortfolio",
        "parameters": [
          {
            "$ref": "#/components/parameters/PortfolioId"
          }
        ],
        "responses": {
          "200": {
            "description": "Portfolio",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnvelopePortfolio"
                }
              }
            }
          }
        }
      }
    },
    "/portfolios/{portfolioId}/imports": {
      "get": {
        "summary": "List import jobs for a granted portfolio",
        "operationId": "listImports",
        "parameters": [
          {
            "$ref": "#/components/parameters/PortfolioId"
          }
        ],
        "responses": {
          "200": {
            "description": "Import jobs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnvelopeImportList"
                }
              }
            }
          }
        }
      }
    },
    "/portfolios/{portfolioId}/imports/{importId}": {
      "get": {
        "summary": "Get import job status",
        "operationId": "getImport",
        "parameters": [
          {
            "$ref": "#/components/parameters/PortfolioId"
          },
          {
            "name": "importId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Import job",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnvelopeImport"
                }
              }
            }
          }
        }
      }
    },
    "/portfolios/{portfolioId}/trades": {
      "get": {
        "summary": "List transactions for a granted portfolio",
        "operationId": "listTrades",
        "parameters": [
          {
            "$ref": "#/components/parameters/PortfolioId"
          },
          {
            "name": "startDate",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "endDate",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "ticker",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "holdingId",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transactions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnvelopeTransactionList"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a transaction in a granted portfolio",
        "operationId": "createTrade",
        "parameters": [
          {
            "$ref": "#/components/parameters/PortfolioId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TradeInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created transaction",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnvelopeTransaction"
                }
              }
            }
          }
        }
      }
    },
    "/portfolios/{portfolioId}/performance": {
      "get": {
        "summary": "Get performance report data",
        "operationId": "getPerformance",
        "parameters": [
          {
            "$ref": "#/components/parameters/PortfolioId"
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Performance data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnvelopePerformance"
                }
              }
            }
          }
        }
      }
    },
    "/portfolios/{portfolioId}/tax-report": {
      "get": {
        "summary": "Get tax report data",
        "operationId": "getTaxReport",
        "parameters": [
          {
            "$ref": "#/components/parameters/PortfolioId"
          },
          {
            "name": "fy",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "method",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["FIFO", "LIFO", "Max gain", "Min gain"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tax report data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnvelopeTaxReport"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Use `Authorization: ApiKey <key>`."
      }
    },
    "parameters": {
      "PortfolioId": {
        "name": "portfolioId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "Scope": {
        "type": "string",
        "enum": [
          "portfolio:read",
          "transactions:read",
          "transactions:write",
          "imports:read",
          "performance:read",
          "tax:read"
        ]
      },
      "Grant": {
        "type": "object",
        "required": ["portfolioId", "capabilities"],
        "properties": {
          "portfolioId": {
            "type": "string"
          },
          "capabilities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Scope"
            }
          }
        }
      },
      "PartnerMe": {
        "type": "object",
        "required": ["partner", "credential", "grants"],
        "properties": {
          "partner": {
            "type": "object",
            "additionalProperties": true
          },
          "credential": {
            "type": "object",
            "additionalProperties": true
          },
          "grants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Grant"
            }
          }
        }
      },
      "Portfolio": {
        "type": "object",
        "additionalProperties": true
      },
      "ImportJob": {
        "type": "object",
        "additionalProperties": true
      },
      "Transaction": {
        "type": "object",
        "additionalProperties": true
      },
      "TradeInput": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/BuySellInput"
          },
          {
            "$ref": "#/components/schemas/DividendInput"
          },
          {
            "$ref": "#/components/schemas/CryptoIncomeInput"
          }
        ]
      },
      "BuySellInput": {
        "type": "object",
        "required": ["type", "ticker", "exchange", "quantity", "price", "currency", "date"],
        "properties": {
          "type": {
            "type": "string",
            "enum": ["BUY", "SELL"]
          },
          "ticker": {
            "type": "string"
          },
          "exchange": {
            "type": "string"
          },
          "assetName": {
            "type": "string"
          },
          "quantity": {
            "type": "string"
          },
          "price": {
            "type": "string"
          },
          "fee": {
            "type": "string"
          },
          "feeCurrency": {
            "type": "string"
          },
          "exchangeRate": {
            "type": "number"
          },
          "currency": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "notes": {
            "type": "string"
          },
          "broker": {
            "type": "string"
          }
        }
      },
      "DividendInput": {
        "type": "object",
        "required": ["type", "ticker", "exchange", "amount", "currency", "date"],
        "properties": {
          "type": {
            "type": "string",
            "const": "DIVIDEND"
          },
          "ticker": {
            "type": "string"
          },
          "exchange": {
            "type": "string"
          },
          "amount": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "format": "date"
          }
        }
      },
      "CryptoIncomeInput": {
        "type": "object",
        "required": ["type", "ticker", "exchange", "quantity", "date"],
        "properties": {
          "type": {
            "type": "string",
            "enum": ["STAKING_REWARD", "AIRDROP"]
          },
          "ticker": {
            "type": "string"
          },
          "exchange": {
            "type": "string",
            "const": "CRYPTO"
          },
          "quantity": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "format": "date"
          }
        }
      },
      "Performance": {
        "type": "object",
        "additionalProperties": true
      },
      "TaxReport": {
        "type": "object",
        "additionalProperties": true
      },
      "EnvelopePartnerMe": {
        "$ref": "#/components/schemas/Envelope"
      },
      "EnvelopePortfolioList": {
        "$ref": "#/components/schemas/Envelope"
      },
      "EnvelopePortfolio": {
        "$ref": "#/components/schemas/Envelope"
      },
      "EnvelopeImportList": {
        "$ref": "#/components/schemas/Envelope"
      },
      "EnvelopeImport": {
        "$ref": "#/components/schemas/Envelope"
      },
      "EnvelopeTransactionList": {
        "$ref": "#/components/schemas/Envelope"
      },
      "EnvelopeTransaction": {
        "$ref": "#/components/schemas/Envelope"
      },
      "EnvelopePerformance": {
        "$ref": "#/components/schemas/Envelope"
      },
      "EnvelopeTaxReport": {
        "$ref": "#/components/schemas/Envelope"
      },
      "Envelope": {
        "type": "object",
        "required": ["data"],
        "properties": {
          "data": {}
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}