web/docs/api/secret-system.openapi.yaml

openapi: 3.0.3
info:
  title: EDUT Secret System API
  version: v1
  description: Wallet-first designation and membership activation endpoints.
servers:
  - url: https://api.edut.ai
paths:
  /secret/wallet/intent:
    post:
      summary: Create wallet signature intent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletIntentRequest'
      responses:
        '200':
          description: Intent created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletIntentResponse'
  /secret/wallet/verify:
    post:
      summary: Verify signed intent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletVerifyRequest'
      responses:
        '200':
          description: Signature verified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletVerifyResponse'
  /secret/membership/quote:
    post:
      summary: Get current membership mint quote
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MembershipQuoteRequest'
      responses:
        '200':
          description: Quote created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipQuoteResponse'
  /secret/membership/confirm:
    post:
      summary: Confirm membership mint transaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MembershipConfirmRequest'
      responses:
        '200':
          description: Membership active
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipConfirmResponse'
  /secret/membership/status:
    get:
      summary: Resolve membership status by wallet or designation code
      parameters:
        - in: query
          name: wallet
          required: false
          schema:
            type: string
            pattern: '^0x[a-fA-F0-9]{40}$'
        - in: query
          name: designation_code
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Membership status resolved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipStatusResponse'
  /secret/notify:
    post:
      summary: Save optional notification email
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotifyRequest'
      responses:
        '200':
          description: Notification saved
          content:
            application/json:
              schema:
                type: object
                required: [status]
                properties:
                  status:
                    type: string
                    enum: [saved]
components:
  schemas:
    WalletIntentRequest:
      type: object
      required: [address, origin, locale, chain_id]
      properties:
        address:
          type: string
          pattern: '^0x[a-fA-F0-9]{40}$'
        origin:
          type: string
          format: uri
        locale:
          type: string
        chain_id:
          type: integer
    WalletIntentResponse:
      type: object
      required: [intent_id, designation_code, display_token, nonce, issued_at, expires_at, chain_id]
      properties:
        intent_id:
          type: string
        designation_code:
          type: string
        display_token:
          type: string
        nonce:
          type: string
        issued_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        domain_name:
          type: string
        chain_id:
          type: integer
        verifying_contract:
          type: string
    WalletVerifyRequest:
      type: object
      required: [intent_id, address, chain_id, signature]
      properties:
        intent_id:
          type: string
        address:
          type: string
          pattern: '^0x[a-fA-F0-9]{40}$'
        chain_id:
          type: integer
        signature:
          type: string
    WalletVerifyResponse:
      type: object
      required: [status, designation_code, display_token, verified_at]
      properties:
        status:
          type: string
          enum: [signature_verified]
        designation_code:
          type: string
        display_token:
          type: string
        verified_at:
          type: string
          format: date-time
    MembershipQuoteRequest:
      type: object
      required: [designation_code, address, chain_id]
      properties:
        designation_code:
          type: string
        address:
          type: string
          pattern: '^0x[a-fA-F0-9]{40}$'
        chain_id:
          type: integer
    MembershipQuoteResponse:
      type: object
      required: [quote_id, chain_id, currency, amount_atomic, deadline, contract_address]
      properties:
        quote_id:
          type: string
        chain_id:
          type: integer
        currency:
          type: string
          enum: [USDC, ETH]
        amount:
          type: string
        amount_atomic:
          type: string
        decimals:
          type: integer
        deadline:
          type: string
          format: date-time
        contract_address:
          type: string
        method:
          type: string
        calldata:
          type: string
        value:
          type: string
        tx:
          type: object
          additionalProperties: true
    MembershipConfirmRequest:
      type: object
      required: [designation_code, quote_id, tx_hash, address, chain_id]
      properties:
        designation_code:
          type: string
        quote_id:
          type: string
        tx_hash:
          type: string
          pattern: '^0x[a-fA-F0-9]{64}$'
        address:
          type: string
          pattern: '^0x[a-fA-F0-9]{40}$'
        chain_id:
          type: integer
    MembershipConfirmResponse:
      type: object
      required: [status, designation_code, display_token, tx_hash, activated_at]
      properties:
        status:
          type: string
          enum: [membership_active]
        designation_code:
          type: string
        display_token:
          type: string
        tx_hash:
          type: string
        activated_at:
          type: string
          format: date-time
    MembershipStatusResponse:
      type: object
      required: [status]
      properties:
        status:
          type: string
          enum: [active, none, suspended, revoked, unknown]
        wallet:
          type: string
        designation_code:
          type: string
    NotifyRequest:
      type: object
      required: [email, designation_code, wallet, locale]
      properties:
        email:
          type: string
          format: email
        designation_code:
          type: string
        designation_token:
          type: string
        wallet:
          type: string
          pattern: '^0x[a-fA-F0-9]{40}$'
        locale:
          type: string