{
  "openapi": "3.1.0",
  "info": {
    "title": "Quub Exchange - Primary Market Service",
    "version": "2.0.0",
    "license": {
      "name": "Proprietary",
      "identifier": "Proprietary"
    },
    "description": "Primary market service for tokenized asset issuance:\n- Project setup and governance\n- Token class definitions\n- Offerings and subscription flows\n- Milestone certification and escrow release\n"
  },
  "servers": [
    {
      "url": "https://api.sandbox.quub.exchange/v1",
      "description": "Sandbox environment"
    },
    {
      "url": "https://api.quub.exchange/v1",
      "description": "Production environment"
    }
  ],
  "tags": [
    {
      "name": "primary-market",
      "description": "Primary market operations (projects, offerings, subscriptions, milestones)"
    }
  ],
  "paths": {
    "/orgs/{orgId}/projects": {
      "parameters": [
        {
          "$ref": "./common/components.yaml#/components/parameters/orgId"
        },
        {
          "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
        }
      ],
      "get": {
        "tags": [
          "primary"
        ],
        "summary": "List projects",
        "operationId": "listProjects",
        "security": [
          {
            "oauth2": [
              "read:primary-market"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "$ref": "./common/pagination.yaml#/components/parameters/cursor"
          },
          {
            "$ref": "./common/pagination.yaml#/components/parameters/limit"
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "$ref": "./common/primitives.yaml#/components/schemas/ProjectType"
            }
          },
          {
            "name": "spvId",
            "in": "query",
            "schema": {
              "$ref": "./common/primitives.yaml#/components/schemas/OrgId"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of projects",
            "headers": {
              "Request-Id": {
                "$ref": "./common/components.yaml#/components/headers/Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "./common/pagination.yaml#/components/schemas/PageResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "./common/domain-models.yaml#/components/schemas/Project"
                          }
                        },
                        "meta": {
                          "$ref": "./common/pagination.yaml#/components/schemas/PageMeta"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "./common/responses.yaml#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          }
        }
      },
      "post": {
        "tags": [
          "primary"
        ],
        "summary": "Create project",
        "operationId": "createProject",
        "security": [
          {
            "oauth2": [
              "write:primary-market"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "type",
                  "currency"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "location": {
                    "type": "string"
                  },
                  "spvId": {
                    "$ref": "./common/primitives.yaml#/components/schemas/OrgId"
                  },
                  "type": {
                    "$ref": "./common/primitives.yaml#/components/schemas/ProjectType"
                  },
                  "currency": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$"
                  },
                  "metadata": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Project created successfully",
            "headers": {
              "Request-Id": {
                "$ref": "./common/components.yaml#/components/headers/Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "./common/domain-models.yaml#/components/schemas/Project"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "./common/responses.yaml#/components/responses/Conflict"
          },
          "422": {
            "$ref": "./common/responses.yaml#/components/responses/ValidationError"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/orgs/{orgId}/projects/{projectId}": {
      "parameters": [
        {
          "$ref": "./common/components.yaml#/components/parameters/orgId"
        },
        {
          "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
        },
        {
          "name": "projectId",
          "in": "path",
          "required": true,
          "schema": {
            "$ref": "./common/primitives.yaml#/components/schemas/ProjectId"
          }
        }
      ],
      "get": {
        "tags": [
          "primary"
        ],
        "summary": "Get project details",
        "operationId": "getProject",
        "security": [
          {
            "oauth2": [
              "read:primary-market"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "./common/primitives.yaml#/components/schemas/ProjectId"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Project details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "./common/domain-models.yaml#/components/schemas/Project"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "./common/responses.yaml#/components/responses/NotFound"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          }
        }
      },
      "patch": {
        "tags": [
          "primary"
        ],
        "summary": "Update project",
        "operationId": "updateProject",
        "security": [
          {
            "oauth2": [
              "write:primary-market"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "./common/primitives.yaml#/components/schemas/ProjectId"
            }
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "location": {
                    "type": "string"
                  },
                  "metadata": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Project updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "./common/domain-models.yaml#/components/schemas/Project"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "./common/responses.yaml#/components/responses/NotFound"
          },
          "422": {
            "$ref": "./common/responses.yaml#/components/responses/ValidationError"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/orgs/{orgId}/token-classes": {
      "parameters": [
        {
          "$ref": "./common/components.yaml#/components/parameters/orgId"
        },
        {
          "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
        }
      ],
      "get": {
        "tags": [
          "primary"
        ],
        "summary": "List token classes",
        "operationId": "listTokenClasses",
        "security": [
          {
            "oauth2": [
              "read:primary-market"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "$ref": "./common/pagination.yaml#/components/parameters/cursor"
          },
          {
            "$ref": "./common/pagination.yaml#/components/parameters/limit"
          },
          {
            "name": "chainId",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "rights",
            "in": "query",
            "schema": {
              "$ref": "./common/primitives.yaml#/components/schemas/Rights"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of token classes",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "./common/pagination.yaml#/components/schemas/PageResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "./common/domain-models.yaml#/components/schemas/TokenClass"
                          }
                        },
                        "meta": {
                          "$ref": "./common/pagination.yaml#/components/schemas/PageMeta"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          }
        }
      },
      "post": {
        "tags": [
          "primary"
        ],
        "summary": "Create token class",
        "operationId": "createTokenClass",
        "security": [
          {
            "oauth2": [
              "write:primary-market"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "standard",
                  "rights",
                  "transferRestricted",
                  "decimals",
                  "chainId"
                ],
                "properties": {
                  "standard": {
                    "$ref": "./common/primitives.yaml#/components/schemas/TokenStandard"
                  },
                  "rights": {
                    "$ref": "./common/primitives.yaml#/components/schemas/Rights"
                  },
                  "transferRestricted": {
                    "type": "boolean"
                  },
                  "decimals": {
                    "type": "integer",
                    "enum": [
                      0,
                      6,
                      18
                    ]
                  },
                  "chainId": {
                    "type": "integer"
                  },
                  "contractAddr": {
                    "type": "string",
                    "pattern": "^0x[a-fA-F0-9]{40}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Token class created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "./common/domain-models.yaml#/components/schemas/TokenClass"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "./common/responses.yaml#/components/responses/Conflict"
          },
          "422": {
            "$ref": "./common/responses.yaml#/components/responses/ValidationError"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/orgs/{orgId}/token-classes/{tokenClassId}": {
      "parameters": [
        {
          "$ref": "./common/components.yaml#/components/parameters/orgId"
        },
        {
          "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
        },
        {
          "name": "tokenClassId",
          "in": "path",
          "required": true,
          "schema": {
            "$ref": "./common/primitives.yaml#/components/schemas/TokenClassId"
          }
        }
      ],
      "get": {
        "tags": [
          "primary"
        ],
        "summary": "Get token class details",
        "operationId": "getTokenClass",
        "security": [
          {
            "oauth2": [
              "read:primary-market"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "name": "tokenClassId",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "./common/primitives.yaml#/components/schemas/TokenClassId"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Token class details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "./common/domain-models.yaml#/components/schemas/TokenClass"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "./common/responses.yaml#/components/responses/NotFound"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          }
        }
      },
      "patch": {
        "tags": [
          "primary"
        ],
        "summary": "Update token class",
        "operationId": "updateTokenClass",
        "security": [
          {
            "oauth2": [
              "write:primary-market"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "name": "tokenClassId",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "./common/primitives.yaml#/components/schemas/TokenClassId"
            }
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "contractAddr": {
                    "type": "string",
                    "pattern": "^0x[a-fA-F0-9]{40}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token class updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "./common/domain-models.yaml#/components/schemas/TokenClass"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "./common/responses.yaml#/components/responses/NotFound"
          },
          "422": {
            "$ref": "./common/responses.yaml#/components/responses/ValidationError"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/orgs/{orgId}/offerings": {
      "parameters": [
        {
          "$ref": "./common/components.yaml#/components/parameters/orgId"
        },
        {
          "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
        }
      ],
      "get": {
        "tags": [
          "primary"
        ],
        "summary": "List offerings",
        "operationId": "listOfferings",
        "security": [
          {
            "oauth2": [
              "read:primary-market"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "$ref": "./common/pagination.yaml#/components/parameters/cursor"
          },
          {
            "$ref": "./common/pagination.yaml#/components/parameters/limit"
          },
          {
            "name": "projectId",
            "in": "query",
            "schema": {
              "$ref": "./common/primitives.yaml#/components/schemas/ProjectId"
            }
          },
          {
            "name": "tokenClassId",
            "in": "query",
            "schema": {
              "$ref": "./common/primitives.yaml#/components/schemas/TokenClassId"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of offerings",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "./common/pagination.yaml#/components/schemas/PageResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "./common/domain-models.yaml#/components/schemas/Offering"
                          }
                        },
                        "meta": {
                          "$ref": "./common/pagination.yaml#/components/schemas/PageMeta"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          }
        }
      },
      "post": {
        "tags": [
          "primary"
        ],
        "summary": "Create offering",
        "operationId": "createOffering",
        "security": [
          {
            "oauth2": [
              "write:primary-market"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "projectId",
                  "tokenClassId",
                  "tranche",
                  "price",
                  "minLot",
                  "hardCap"
                ],
                "properties": {
                  "projectId": {
                    "$ref": "./common/primitives.yaml#/components/schemas/ProjectId"
                  },
                  "tokenClassId": {
                    "$ref": "./common/primitives.yaml#/components/schemas/TokenClassId"
                  },
                  "tranche": {
                    "$ref": "./common/primitives.yaml#/components/schemas/Tranche"
                  },
                  "price": {
                    "type": "number",
                    "format": "double"
                  },
                  "minLot": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "softCap": {
                    "type": "number",
                    "format": "double"
                  },
                  "hardCap": {
                    "type": "number",
                    "format": "double"
                  },
                  "startAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "endAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "docs": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Offering created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "./common/domain-models.yaml#/components/schemas/Offering"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "./common/responses.yaml#/components/responses/Conflict"
          },
          "422": {
            "$ref": "./common/responses.yaml#/components/responses/ValidationError"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/orgs/{orgId}/subscriptions": {
      "parameters": [
        {
          "$ref": "./common/components.yaml#/components/parameters/orgId"
        },
        {
          "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
        }
      ],
      "post": {
        "tags": [
          "primary"
        ],
        "summary": "Create subscription (idempotent)",
        "operationId": "createSubscription",
        "security": [
          {
            "oauth2": [
              "write:primary-market"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "accountId",
                  "offeringId",
                  "qty"
                ],
                "properties": {
                  "accountId": {
                    "$ref": "./common/primitives.yaml#/components/schemas/AccountId"
                  },
                  "offeringId": {
                    "$ref": "./common/primitives.yaml#/components/schemas/OfferingId"
                  },
                  "qty": {
                    "type": "integer",
                    "minimum": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Subscription created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Subscription"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "./common/responses.yaml#/components/responses/Conflict"
          },
          "422": {
            "$ref": "./common/responses.yaml#/components/responses/ValidationError"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/orgs/{orgId}/subscriptions/{subscriptionId}/fund": {
      "parameters": [
        {
          "$ref": "./common/components.yaml#/components/parameters/orgId"
        },
        {
          "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
        },
        {
          "name": "subscriptionId",
          "in": "path",
          "required": true,
          "schema": {
            "$ref": "./common/primitives.yaml#/components/schemas/SubscriptionId"
          }
        }
      ],
      "post": {
        "tags": [
          "primary"
        ],
        "summary": "Attach payment to subscription",
        "operationId": "fundSubscription",
        "security": [
          {
            "oauth2": [
              "write:primary-market"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "name": "subscriptionId",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "./common/primitives.yaml#/components/schemas/SubscriptionId"
            }
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "paymentRef"
                ],
                "properties": {
                  "paymentRef": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscription funded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Subscription"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "./common/responses.yaml#/components/responses/NotFound"
          },
          "422": {
            "$ref": "./common/responses.yaml#/components/responses/ValidationError"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/orgs/{orgId}/subscriptions/{subscriptionId}/allocate": {
      "parameters": [
        {
          "$ref": "./common/components.yaml#/components/parameters/orgId"
        },
        {
          "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
        },
        {
          "name": "subscriptionId",
          "in": "path",
          "required": true,
          "schema": {
            "$ref": "./common/primitives.yaml#/components/schemas/SubscriptionId"
          }
        }
      ],
      "post": {
        "tags": [
          "primary"
        ],
        "summary": "Mint and allocate tokens to subscription",
        "operationId": "allocateSubscription",
        "security": [
          {
            "oauth2": [
              "write:primary-market"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "name": "subscriptionId",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "./common/primitives.yaml#/components/schemas/SubscriptionId"
            }
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "walletId"
                ],
                "properties": {
                  "walletId": {
                    "type": "string",
                    "pattern": "^wlt_[a-zA-Z0-9]{16,32}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscription allocated (tokens minted)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Subscription"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "./common/responses.yaml#/components/responses/NotFound"
          },
          "422": {
            "$ref": "./common/responses.yaml#/components/responses/ValidationError"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/orgs/{orgId}/subscriptions/{subscriptionId}/refund": {
      "parameters": [
        {
          "$ref": "./common/components.yaml#/components/parameters/orgId"
        },
        {
          "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
        },
        {
          "name": "subscriptionId",
          "in": "path",
          "required": true,
          "schema": {
            "$ref": "./common/primitives.yaml#/components/schemas/SubscriptionId"
          }
        }
      ],
      "post": {
        "tags": [
          "primary"
        ],
        "summary": "Refund subscription",
        "operationId": "refundSubscription",
        "security": [
          {
            "oauth2": [
              "write:primary-market"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "name": "subscriptionId",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "./common/primitives.yaml#/components/schemas/SubscriptionId"
            }
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscription refunded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Subscription"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "./common/responses.yaml#/components/responses/NotFound"
          },
          "422": {
            "$ref": "./common/responses.yaml#/components/responses/ValidationError"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/orgs/{orgId}/milestones": {
      "parameters": [
        {
          "$ref": "./common/components.yaml#/components/parameters/orgId"
        },
        {
          "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
        }
      ],
      "get": {
        "tags": [
          "primary"
        ],
        "summary": "List milestones",
        "operationId": "listMilestones",
        "security": [
          {
            "oauth2": [
              "read:primary-market"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "$ref": "./common/pagination.yaml#/components/parameters/cursor"
          },
          {
            "$ref": "./common/pagination.yaml#/components/parameters/limit"
          },
          {
            "name": "projectId",
            "in": "query",
            "required": true,
            "schema": {
              "$ref": "./common/primitives.yaml#/components/schemas/ProjectId"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of milestones",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "./common/pagination.yaml#/components/schemas/PageResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Milestone"
                          }
                        },
                        "meta": {
                          "$ref": "./common/pagination.yaml#/components/schemas/PageMeta"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "./common/responses.yaml#/components/responses/NotFound"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          }
        }
      },
      "post": {
        "tags": [
          "primary"
        ],
        "summary": "Create milestone",
        "operationId": "createMilestone",
        "security": [
          {
            "oauth2": [
              "write:primary-market"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "projectId",
                  "name",
                  "escrowReleasePct"
                ],
                "properties": {
                  "projectId": {
                    "$ref": "./common/primitives.yaml#/components/schemas/ProjectId"
                  },
                  "name": {
                    "type": "string"
                  },
                  "targetDay": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "escrowReleasePct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Milestone created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Milestone"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "./common/responses.yaml#/components/responses/Conflict"
          },
          "422": {
            "$ref": "./common/responses.yaml#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "./common/responses.yaml#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Subscription": {
        "type": "object",
        "description": "Investor subscription to an offering",
        "required": [
          "id",
          "orgId",
          "accountId",
          "offeringId",
          "qty",
          "status"
        ],
        "properties": {
          "id": {
            "$ref": "./common/primitives.yaml#/components/schemas/SubscriptionId"
          },
          "orgId": {
            "$ref": "./common/primitives.yaml#/components/schemas/OrgId"
          },
          "accountId": {
            "$ref": "./common/primitives.yaml#/components/schemas/AccountId"
          },
          "offeringId": {
            "$ref": "./common/primitives.yaml#/components/schemas/OfferingId"
          },
          "qty": {
            "type": "integer",
            "minimum": 1,
            "description": "Number of tokens/shares subscribed"
          },
          "price": {
            "type": "number",
            "format": "double",
            "description": "Price per token/share"
          },
          "totalAmount": {
            "type": "number",
            "format": "double"
          },
          "currency": {
            "type": "string",
            "example": "USD"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "FUNDED",
              "ALLOCATED",
              "REFUNDED",
              "CANCELLED"
            ]
          },
          "subscribedAt": {
            "type": "string",
            "format": "date-time"
          },
          "fundedAt": {
            "oneOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "allocatedAt": {
            "oneOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "paymentRef": {
            "type": "string",
            "description": "Reference to payment transaction"
          }
        }
      },
      "Milestone": {
        "type": "object",
        "description": "Project milestone for fund release",
        "required": [
          "id",
          "projectId",
          "title",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "projectId": {
            "$ref": "./common/primitives.yaml#/components/schemas/ProjectId"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "fundAmount": {
            "type": "number",
            "format": "double",
            "description": "Funds to be released upon completion"
          },
          "currency": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "IN_PROGRESS",
              "COMPLETED",
              "FAILED",
              "CANCELLED"
            ]
          },
          "dueDate": {
            "oneOf": [
              {
                "type": "string",
                "format": "date"
              },
              {
                "type": "null"
              }
            ]
          },
          "completedAt": {
            "oneOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "verificationDocs": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "approver": {
            "type": "string",
            "description": "Account ID of approver"
          }
        }
      }
    },
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://auth.quub.exchange/oauth/authorize",
            "tokenUrl": "https://auth.quub.exchange/oauth/token",
            "scopes": {
              "read:projects": "Read project information",
              "write:projects": "Create and modify projects",
              "admin:*": "Full administrative access"
            }
          }
        }
      },
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}