stakepass_openapi.yaml

openapi: 3.0.3
info:
  title: StakePass API
  version: 1.0.0
servers:
  - url: https://api.stakepass.example.com
    description: Production
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.stakepass.example.com/oauth/authorize
          tokenUrl: https://auth.stakepass.example.com/oauth/token
          scopes:
            profile: 사용자 프로필 정보 접근
            subscribe: 구독 API 접근 권한
  schemas:
    SubscribeRequest:
      type: object
      required: [userAddress, planId, amount]
      properties:
        userAddress: { type: string }
        planId: { type: integer }
        amount: { type: string }
    SubscribeResponse:
      type: object
      required: [txHash, tokenId]
      properties:
        txHash: { type: string }
        tokenId: { type: integer }
    VerifyResponse:
      type: object
      required: [valid, expiry]
      properties:
        valid: { type: boolean }
        expiry: { type: integer }
    UnsubscribeRequest:
      type: object
      required: [userAddress, tokenId, amount]
      properties:
        userAddress: { type: string }
        tokenId: { type: integer }
        amount: { type: string }
    UnsubscribeResponse:
      type: object
      required: [txHash]
      properties:
        txHash: { type: string }
    PlanInfo:
      type: object
      required: [planId, amountRequired, duration, active]
      properties:
        planId: { type: integer }
        amountRequired: { type: string }
        duration: { type: integer }
        active: { type: boolean }
    QuoteRequest:
      type: object
      required: [serviceId, term]
      properties:
        serviceId: { type: string }
        term: { type: integer, enum: [3,6,12] }
    QuoteResponse:
      type: object
      required: [requiredDeposit, ltv, expiry]
      properties:
        requiredDeposit: { type: string }
        ltv: { type: number, format: float }
        expiry: { type: integer }
        feeSchedule:
          type: object
          additionalProperties: { type: string }
    RenewRequest:
      type: object
      required: [orderId]
      properties:
        orderId: { type: string }
    RenewResponse:
      type: object
      required: [renewed, newExpiry]
      properties:
        renewed: { type: boolean }
        newExpiry: { type: integer }
    CancelEarlyRequest:
      type: object
      required: [orderId]
      properties:
        orderId: { type: string }
        reason: { type: string }
    CancelEarlyResponse:
      type: object
      required: [refundAmount, penalty]
      properties:
        refundAmount: { type: string }
        penalty: { type: string }
security:
  - bearerAuth: []
paths:
  /api/subscribe:
    post:
      summary: 사용자 예치 및 구독 시작
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscribeRequest'
      responses:
        '200':
          description: 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscribeResponse'
  /api/verify:
    get:
      summary: SBT 검증 및 서비스 접근 권한 확인
      parameters:
        - in: query
          name: userAddress
          required: true
          schema: { type: string }
        - in: query
          name: tokenId
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: 검증 결과
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
  /api/unsubscribe:
    post:
      summary: 예치금 회수 및 구독 종료
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnsubscribeRequest'
      responses:
        '200':
          description: 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsubscribeResponse'
  /api/plans:
    get:
      summary: 구독 플랜 목록 조회
      responses:
        '200':
          description: 플랜 배열
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlanInfo'
  /api/quote:
    post:
      summary: 담보 견적 조회
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteRequest'
      responses:
        '200':
          description: 견적
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
  /api/renew:
    post:
      summary: 자동/수동 갱신 트리거
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenewRequest'
      responses:
        '200':
          description: 갱신 결과
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenewResponse'
  /api/cancel-early:
    post:
      summary: 조기 해지 요청
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelEarlyRequest'
      responses:
        '200':
          description: 환급/페널티 계산 결과
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelEarlyResponse'
  /api/admin/provider:
    post:
      summary: Provider 등록 (Admin)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [providerName, payoutWallet]
              properties:
                providerName: { type: string }
                payoutWallet: { type: string }
      responses:
        '200':
          description: 생성됨
  /api/admin/plan:
    post:
      summary: 신규 구독 플랜 생성 (Admin)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [serviceId, currency, monthlyFee, terms, minCollateral]
              properties:
                serviceId: { type: string }
                currency: { type: string, enum: [USDT, KRWT] }
                monthlyFee: { type: string }
                terms:
                  type: array
                  items: { type: integer, enum: [3,6,12] }
                minCollateral: { type: string }
      responses:
        '200':
          description: 생성됨