openapi: 3.0.3
info:
  title: EDUT Marketplace API
  version: v1
  description: Membership-gated offer and entitlement commerce endpoints.
servers:
  - url: https://api.edut.ai
security:
  - AppSession: []
paths:
  /marketplace/offers:
    get:
      summary: List active offers (launcher/app surface)
      parameters:
        - in: query
          name: merchant_id
          required: false
          schema:
            type: string
          description: Merchant namespace. Defaults to `edut.firstparty`.
      responses:
        '200':
          description: Offer list
          content:
            application/json:
              schema:
                type: object
                required: [offers]
                properties:
                  offers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Offer'
  /marketplace/offers/{offer_id}:
    get:
      summary: Get offer by id
      parameters:
        - in: path
          name: offer_id
          required: true
          schema:
            type: string
        - in: query
          name: merchant_id
          required: false
          schema:
            type: string
          description: Merchant namespace. Defaults to `edut.firstparty`.
      responses:
        '200':
          description: Offer record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Offer'
        '404':
          description: Not found
  /marketplace/checkout/quote:
    post:
      summary: Create checkout quote (membership required)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutQuoteRequest'
      responses:
        '200':
          description: Quote created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutQuoteResponse'
        '403':
          description: Membership not active
  /marketplace/checkout/confirm:
    post:
      summary: Confirm checkout transaction and mint entitlement
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutConfirmRequest'
      responses:
        '200':
          description: Entitlement active
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutConfirmResponse'
  /marketplace/entitlements:
    get:
      summary: List entitlements for wallet
      parameters:
        - in: query
          name: wallet
          required: true
          schema:
            type: string
            pattern: '^0x[a-fA-F0-9]{40}$'
        - in: query
          name: merchant_id
          required: false
          schema:
            type: string
          description: Optional merchant filter. If omitted, returns all merchants for wallet.
      responses:
        '200':
          description: Entitlements list
          content:
            application/json:
              schema:
                type: object
                required: [entitlements]
                properties:
                  entitlements:
                    type: array
                    items:
                      $ref: '#/components/schemas/Entitlement'
components:
  securitySchemes:
    AppSession:
      type: http
      scheme: bearer
      bearerFormat: EDUT-APP-SESSION
      description: |
        Wallet session token issued by `POST /secret/wallet/verify`.
        Send as `Authorization: Bearer <token>` (preferred) or `X-Edut-Session: <token>`.
  schemas:
    Offer:
      type: object
      required: [offer_id, issuer_id, title, status, pricing, policies]
      properties:
        merchant_id:
          type: string
        offer_id:
          type: string
        issuer_id:
          type: string
        title:
          type: string
        summary:
          type: string
        status:
          type: string
          enum: [draft, active, paused, retired]
        pricing:
          type: object
          required: [currency, amount_atomic, decimals]
          properties:
            currency:
              type: string
              enum: [USDC, ETH]
            amount_atomic:
              type: string
            decimals:
              type: integer
            chain_id:
              type: integer
        execution_profile:
          type: object
          required: [connector_surface, pacing_tier]
          properties:
            connector_surface:
              type: string
              enum: [edut_native, external_connector, hybrid]
            pacing_tier:
              type: string
              enum: [governed_human_pace, local_hardware_speed]
            human_pace_floor_ms:
              type: integer
              minimum: 0
      policies:
        type: object
        required: [member_only, workspace_bound, transferable, internal_use_only, multi_tenant]
        properties:
          member_only:
            type: boolean
          workspace_bound:
            type: boolean
          transferable:
            type: boolean
          internal_use_only:
            type: boolean
          multi_tenant:
            type: boolean
    CheckoutQuoteRequest:
      type: object
      required: [wallet, offer_id]
      properties:
        merchant_id:
          type: string
          description: Merchant namespace. Defaults to `edut.firstparty`.
        wallet:
          type: string
          pattern: '^0x[a-fA-F0-9]{40}$'
          description: Ownership wallet that will receive entitlement.
        payer_wallet:
          type: string
          pattern: '^0x[a-fA-F0-9]{40}$'
          description: Optional wallet paying the quote transaction when different from ownership wallet.
        offer_id:
          type: string
        org_root_id:
          type: string
          description: Economic boundary identifier for suite entitlement checks.
        principal_id:
          type: string
          description: Human principal requesting checkout.
        principal_role:
          type: string
          enum: [workspace_member, org_root_owner]
        workspace_id:
          type: string
        ownership_proof:
          type: string
          description: Optional ownership-wallet signature proving entitlement recipient approval when payer differs.
        include_membership_if_missing:
          type: boolean
          default: true
          description: If true, quote may bundle first-time membership fee into total.
    CheckoutQuoteResponse:
      type: object
      required: [quote_id, regulatory_profile_id, wallet, offer_id, currency, amount_atomic, total_amount_atomic, decimals, cost_envelope, policy_hash, expires_at]
      properties:
        quote_id:
          type: string
        merchant_id:
          type: string
        regulatory_profile_id:
          type: string
          enum: [us_general_2026, eu_ai_act_2026_baseline]
        wallet:
          type: string
        payer_wallet:
          type: string
        offer_id:
          type: string
        org_root_id:
          type: string
        principal_id:
          type: string
        principal_role:
          type: string
          enum: [workspace_member, org_root_owner]
        currency:
          type: string
        amount:
          type: string
        amount_atomic:
          type: string
          description: License amount component only.
        total_amount:
          type: string
          description: Total payable amount for this checkout quote.
        total_amount_atomic:
          type: string
        decimals:
          type: integer
        cost_envelope:
          $ref: '#/components/schemas/QuoteCostEnvelope'
        membership_activation_included:
          type: boolean
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/QuoteLineItem'
        policy_hash:
          type: string
        expires_at:
          type: string
          format: date-time
        tx:
          type: object
          additionalProperties: true
        access_class:
          type: string
          enum: [connected, sovereign]
        availability_state:
          type: string
          enum: [active, grace, continuity, parked]
    QuoteLineItem:
      type: object
      required: [kind, amount_atomic, decimals, currency, label]
      properties:
        kind:
          type: string
          enum: [license, membership, network_estimate]
        label:
          type: string
        amount:
          type: string
        amount_atomic:
          type: string
        decimals:
          type: integer
        currency:
          type: string
    QuoteCostEnvelope:
      type: object
      required:
        - version
        - checkout_currency
        - checkout_decimals
        - checkout_total_atomic
        - checkout_total
        - provider_fee_policy
        - provider_fee_included
        - provider_fee_estimate_status
        - provider_fee_estimate_atomic
        - network_fee_policy
        - network_fee_currency
        - network_fee_estimate_status
        - network_fee_estimate_atomic
      properties:
        version:
          type: string
          enum: [edut.quote_cost_envelope.v1]
        checkout_currency:
          type: string
        checkout_decimals:
          type: integer
        checkout_total_atomic:
          type: string
        checkout_total:
          type: string
        provider_fee_policy:
          type: string
          enum: [edut_absorbed]
        provider_fee_included:
          type: boolean
        provider_fee_estimate_status:
          type: string
          enum: [absorbed_by_edut]
        provider_fee_estimate_atomic:
          type: string
        network_fee_policy:
          type: string
          enum: [payer_wallet_pays_chain_gas]
        network_fee_currency:
          type: string
          enum: [ETH]
        network_fee_estimate_status:
          type: string
          enum: [wallet_estimate_required]
        network_fee_estimate_atomic:
          type: string
    CheckoutConfirmRequest:
      type: object
      required: [quote_id, wallet, offer_id, tx_hash, chain_id]
      properties:
        quote_id:
          type: string
        merchant_id:
          type: string
          description: Merchant namespace. Defaults to `edut.firstparty`.
        wallet:
          type: string
          pattern: '^0x[a-fA-F0-9]{40}$'
          description: Ownership wallet bound to entitlement.
        payer_wallet:
          type: string
          pattern: '^0x[a-fA-F0-9]{40}$'
          description: Optional payment wallet for tx provenance when different from ownership wallet.
        offer_id:
          type: string
        org_root_id:
          type: string
        principal_id:
          type: string
        principal_role:
          type: string
          enum: [workspace_member, org_root_owner]
        workspace_id:
          type: string
        tx_hash:
          type: string
          pattern: '^0x[a-fA-F0-9]{64}$'
        chain_id:
          type: integer
    CheckoutConfirmResponse:
      type: object
      required: [status, entitlement_id, regulatory_profile_id, offer_id, wallet, tx_hash]
      properties:
        status:
          type: string
          enum: [entitlement_active]
        entitlement_id:
          type: string
        merchant_id:
          type: string
        regulatory_profile_id:
          type: string
          enum: [us_general_2026, eu_ai_act_2026_baseline]
        offer_id:
          type: string
        org_root_id:
          type: string
        principal_id:
          type: string
        principal_role:
          type: string
          enum: [workspace_member, org_root_owner]
        wallet:
          type: string
        tx_hash:
          type: string
        policy_hash:
          type: string
        activated_at:
          type: string
          format: date-time
        access_class:
          type: string
          enum: [connected, sovereign]
        availability_state:
          type: string
          enum: [active, grace, continuity, parked]
    Entitlement:
      type: object
      required: [entitlement_id, offer_id, wallet_address, state]
      properties:
        entitlement_id:
          type: string
        merchant_id:
          type: string
        offer_id:
          type: string
        wallet_address:
          type: string
        workspace_id:
          type: string
        org_root_id:
          type: string
        state:
          type: string
          enum: [active, suspended, revoked, expired]
        access_class:
          type: string
          enum: [connected, sovereign]
        availability_state:
          type: string
          enum: [active, grace, continuity, parked]
        policy_hash:
          type: string
        issued_at:
          type: string
          format: date-time