openapi: 3.0.0
paths:
  /purchases/webhooks/stripe:
    post:
      operationId: PurchasesController_handleStripeWebhook
      summary: Stripe payment webhook (Critical)
      description: >-
        Handles Stripe payment events for financial reconciliation. CRITICAL: Do
        not modify without extensive testing. Replaces POST
        /purchase/stripe-webhook
      parameters: []
      responses:
        '200':
          description: Webhook processed successfully
          content:
            application/json:
              schema:
                type: boolean
      tags:
        - Purchases
      security:
        - '': []
  /purchases/tokens:
    get:
      operationId: PurchasesController_getPurchaseTokens
      summary: Get purchase tokens (Intelligent Access)
      description: >-
        Intelligent endpoint that adapts based on authentication: Public users
        get active tokens only, Admin users get filtered tokens. Replaces GET
        /purchase/token
      parameters:
        - name: active
          required: false
          in: query
          description: >-
            Filter by active status (Admin only: true=active, false=inactive,
            omit=all). Ignored for public access.
          schema:
            type: boolean
      responses:
        '200':
          description: Purchase tokens retrieved based on access level
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseTokenDTO'
      tags:
        - Purchases
      security:
        - projectKey: []
    post:
      operationId: PurchasesController_createPurchaseToken
      summary: Create purchase token (Admin)
      description: >-
        Create a new purchase token for the product catalog. Admin-only
        operation. Replaces POST /purchase/admin/token
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseTokenCreateRequestDTO'
      responses:
        '200':
          description: Purchase token created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseTokenDTO'
      tags:
        - Purchases
      security:
        - tenantAdminJWT: []
  /purchases/donation-types:
    get:
      operationId: PurchasesController_getDonationTypes
      summary: Get donation types
      description: >-
        Get all available donation types for public catalog browsing. Requires
        valid project API key. Replaces GET /purchase/donation/type
      parameters: []
      responses:
        '200':
          description: Donation types retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DonationTypeDTO'
      tags:
        - Purchases
      security:
        - projectKey: []
    post:
      operationId: PurchasesController_createDonationType
      summary: Create donation type (Admin)
      description: >-
        Create a new donation type for system configuration. Admin-only
        operation. Replaces POST /purchase/admin/donation/type
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DonationTypeDTO'
      responses:
        '200':
          description: Donation type created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DonationTypeDTO'
      tags:
        - Purchases
      security:
        - tenantAdminJWT: []
  /purchases/payment-intents:
    post:
      operationId: PurchasesController_createPaymentIntent
      summary: Create payment intent (Financial)
      description: >-
        Create a new Stripe payment intent for purchase processing. Requires
        tenant context for Stripe API key. FINANCIAL OPERATION - handle with
        care. Replaces POST /purchase/payment-intent
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentIntentCreateDTO'
      responses:
        '200':
          description: Payment intent created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentIntentDTO'
      tags:
        - Purchases
      security:
        - projectKey: []
  /purchases/payment-intents/{paymentIntentId}:
    put:
      operationId: PurchasesController_updatePaymentIntent
      summary: Update payment intent (Financial)
      description: >-
        Update an existing Stripe payment intent. Requires tenant context for
        Stripe API key. FINANCIAL OPERATION - handle with care. Replaces PUT
        /purchase/payment-intent/{paymentIntentId}
      parameters:
        - name: paymentIntentId
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentIntentCreateDTO'
      responses:
        '200':
          description: Payment intent updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentIntentDTO'
      tags:
        - Purchases
      security:
        - projectKey: []
    delete:
      operationId: PurchasesController_cancelPaymentIntent
      summary: Cancel payment intent (Financial)
      description: >-
        Cancel an existing Stripe payment intent. Requires tenant context for
        Stripe API key. FINANCIAL OPERATION - handle with care. Replaces DELETE
        /purchase/payment-intent/{paymentIntentId}
      parameters:
        - name: paymentIntentId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Payment intent cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentIntentDTO'
      tags:
        - Purchases
      security:
        - projectKey: []
  /purchases:
    post:
      operationId: PurchasesController_createUserPurchase
      summary: Create user purchase (Financial Transaction)
      description: >-
        Create a new purchase for the authenticated user. BUSINESS CRITICAL -
        handles real financial transactions with Stripe integration. Requires
        user and tenant context. Replaces POST /purchase/auth
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseCreateRequestDTO'
      responses:
        '200':
          description: Purchase created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseCreateResponseDTO'
      tags:
        - Purchases
      security:
        - projectKey: []
        - authUserJWT: []
  /purchases/me/history:
    get:
      operationId: PurchasesController_getUserPurchaseHistory
      summary: Get user purchase history
      description: >-
        Get all purchases made by the authenticated user. Financial records
        require proper user attribution. Replaces GET /purchase/auth
      parameters: []
      responses:
        '200':
          description: User purchase history retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PurchaseDTO'
      tags:
        - Purchases
      security:
        - projectKey: []
        - authUserJWT: []
  /purchases/tokens/{id}:
    put:
      operationId: PurchasesController_updatePurchaseToken
      summary: Update purchase token (Admin)
      description: >-
        Update an existing purchase token in the product catalog. Admin-only
        operation. Replaces PUT /purchase/admin/token/{id}
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseTokenUpdateRequestDTO'
      responses:
        '200':
          description: Purchase token updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseTokenDTO'
      tags:
        - Purchases
      security:
        - tenantAdminJWT: []
    delete:
      operationId: PurchasesController_deletePurchaseToken
      summary: Delete purchase token (Admin)
      description: >-
        Delete an existing purchase token from the product catalog. Admin-only
        operation. Replaces DELETE /purchase/admin/token/{id}
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Purchase token deleted successfully
          content:
            application/json:
              schema:
                type: boolean
      tags:
        - Purchases
      security:
        - tenantAdminJWT: []
  /purchases/types:
    post:
      operationId: PurchasesController_createPurchaseType
      summary: Create purchase type (Admin)
      description: >-
        Create a new purchase type for system configuration. Admin-only
        operation. Replaces POST /purchase/admin/type
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseTypeCreateRequestDTO'
      responses:
        '200':
          description: Purchase type created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseTypeDTO'
      tags:
        - Purchases
      security:
        - tenantAdminJWT: []
  /campaigns:
    get:
      operationId: CampaignsController_getCampaigns
      summary: Get campaigns (Intelligent Access)
      description: >-
        Intelligent endpoint that adapts based on authentication: Public users
        get active campaigns with filtering, Admin users get all campaigns with
        full filtering. Replaces GET /campaign and GET /campaign/admin
      parameters:
        - name: active
          required: false
          in: query
          description: >-
            Filter by active status (Admin only: true=active, false=inactive,
            omit=all). Ignored for public access.
          schema:
            type: boolean
        - name: tag
          required: false
          in: query
          description: Filter by tag
          schema:
            type: string
        - name: limit
          required: false
          in: query
          description: Maximum number of results
          schema:
            type: string
        - name: offset
          required: false
          in: query
          description: Number of results to skip
          schema:
            type: string
        - name: sort
          required: false
          in: query
          description: Sort field
          schema:
            enum:
              - name
              - createdAt
              - startDate
            type: string
        - name: order
          required: false
          in: query
          description: Sort direction
          schema:
            enum:
              - ASC
              - DESC
            type: string
      responses:
        '200':
          description: Campaigns retrieved based on access level
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CampaignDTO'
      tags:
        - Campaigns
      security:
        - projectKey: []
    post:
      operationId: CampaignsController_createCampaign
      summary: Create campaign (Admin)
      description: >-
        Create a new campaign. Admin-only operation. Replaces POST
        /campaign/admin/
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignCreateRequestDTO'
      responses:
        '200':
          description: Campaign created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDTO'
      tags:
        - Campaigns
      security:
        - tenantAdminJWT: []
  /campaigns/{id}:
    get:
      operationId: CampaignsController_getCampaignById
      summary: Get campaign by ID
      description: >-
        Get single campaign details by ID. Available to public with project key.
        Replaces GET /campaign/{id}
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Campaign retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDTO'
      tags:
        - Campaigns
      security:
        - projectKey: []
    put:
      operationId: CampaignsController_updateCampaign
      summary: Update campaign (Admin)
      description: >-
        Update an existing campaign. Admin-only operation. Replaces PUT
        /campaign/admin/{id}
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignCreateRequestDTO'
      responses:
        '200':
          description: Campaign updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDTO'
      tags:
        - Campaigns
      security:
        - tenantAdminJWT: []
    delete:
      operationId: CampaignsController_deleteCampaign
      summary: Delete campaign (Admin)
      description: >-
        Delete an existing campaign. Admin-only operation. Replaces DELETE
        /campaign/admin/{id}
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Campaign deleted successfully
          content:
            application/json:
              schema:
                type: boolean
      tags:
        - Campaigns
      security:
        - tenantAdminJWT: []
  /campaigns/{id}/status:
    put:
      operationId: CampaignsController_toggleCampaignStatus
      summary: Toggle campaign status (Admin)
      description: >-
        Toggle campaign active/inactive status. Admin-only operation. Replaces
        PUT /campaign/admin/{id}/activate
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Campaign status toggled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDTO'
      tags:
        - Campaigns
      security:
        - tenantAdminJWT: []
  /campaigns/{id}/environment:
    put:
      operationId: CampaignsController_toggleCampaignEnvironment
      summary: Toggle campaign environment (Admin)
      description: >-
        Toggle campaign between testnet and mainnet environment. Admin-only
        operation. Replaces PUT /campaign/admin/{id}/environment
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Campaign environment toggled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDTO'
      tags:
        - Campaigns
      security:
        - tenantAdminJWT: []
  /campaign-tags:
    get:
      operationId: CampaignTagsController_getAllUniqueTags
      summary: Get all unique campaign tags (Admin)
      description: >-
        Get all unique tags used across all campaigns. Admin-only operation for
        tag management. Replaces GET /campaign/tags
      parameters: []
      responses:
        '200':
          description: All unique campaign tags retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
      tags:
        - Campaign Tags
      security:
        - tenantAdminJWT: []
  /campaign-tags/{id}:
    put:
      operationId: CampaignTagsController_updateCampaignTags
      summary: Update campaign tags (Admin)
      description: >-
        Replace all tags for a campaign with new tag list. Admin-only operation.
        Replaces PUT /campaign/admin/{id}/tags
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddTagsRequestDTO'
      responses:
        '200':
          description: Campaign tags updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDTO'
      tags:
        - Campaign Tags
      security:
        - tenantAdminJWT: []
    post:
      operationId: CampaignTagsController_addTagsToCampaign
      summary: Add tags to campaign (Admin)
      description: >-
        Add new tags to existing campaign tags without removing existing ones.
        Admin-only operation. Replaces POST /campaign/admin/{id}/tags
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddTagsRequestDTO'
      responses:
        '200':
          description: Tags added to campaign successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDTO'
      tags:
        - Campaign Tags
      security:
        - tenantAdminJWT: []
  /campaign-tags/{id}/{tag}:
    delete:
      operationId: CampaignTagsController_removeTagFromCampaign
      summary: Remove tag from campaign (Admin)
      description: >-
        Remove a specific tag from campaign while preserving other tags.
        Admin-only operation. Replaces DELETE /campaign/admin/{id}/tags/{tag}
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
        - name: tag
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Tag removed from campaign successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDTO'
      tags:
        - Campaign Tags
      security:
        - tenantAdminJWT: []
  /campaign-tokens/{id}:
    post:
      operationId: CampaignTokensController_createCampaignTokenUnit
      summary: Create campaign token unit (Admin)
      description: >-
        Add a new token unit to campaign for reward distribution. Admin-only
        operation. Replaces POST /campaign/admin/{id}/token-units
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenUnitCreateRequestDTO'
      responses:
        '200':
          description: Campaign token unit created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDTO'
      tags:
        - Campaign Tokens
      security:
        - tenantAdminJWT: []
  /campaign-tokens/{id}/{tokenUnitId}:
    put:
      operationId: CampaignTokensController_updateCampaignTokenUnit
      summary: Update campaign token unit (Admin)
      description: >-
        Update an existing token unit in campaign. Admin-only operation.
        Replaces PUT /campaign/admin/{id}/token-units/{tokenUnitId}
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
        - name: tokenUnitId
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenUnitCreateRequestDTO'
      responses:
        '200':
          description: Campaign token unit updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDTO'
      tags:
        - Campaign Tokens
      security:
        - tenantAdminJWT: []
    delete:
      operationId: CampaignTokensController_removeCampaignTokenUnit
      summary: Remove campaign token unit (Admin)
      description: >-
        Remove a token unit from campaign. Admin-only operation. Replaces DELETE
        /campaign/admin/{id}/token-units/{tokenUnitId}
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
        - name: tokenUnitId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Campaign token unit removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDTO'
      tags:
        - Campaign Tokens
      security:
        - tenantAdminJWT: []
  /campaign-triggers:
    get:
      operationId: CampaignTriggersController_getAllTriggers
      summary: Get all triggers (Public Catalog)
      description: >-
        Get all available triggers for campaign configuration. Public access for
        catalog browsing. Replaces GET /campaign/trigger/all
      parameters: []
      responses:
        '200':
          description: All available triggers retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CampaignTriggerDTO'
      tags:
        - Campaign Triggers
      security:
        - projectKey: []
    post:
      operationId: CampaignTriggersController_createCampaignTrigger
      summary: Create campaign trigger (Admin)
      description: >-
        Create a new campaign trigger for use in campaigns. Admin-only
        operation. Replaces POST /campaign/admin/trigger
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignTriggerCreateRequestDTO'
      responses:
        '200':
          description: Campaign trigger created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignTriggerDTO'
      tags:
        - Campaign Triggers
      security:
        - tenantAdminJWT: []
  /campaign-triggers/{id}:
    put:
      operationId: CampaignTriggersController_updateCampaignTrigger
      summary: Update campaign trigger (Admin)
      description: >-
        Update an existing campaign trigger. Admin-only operation. Replaces PUT
        /campaign/admin/trigger/{id}
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignTriggerCreateRequestDTO'
      responses:
        '200':
          description: Campaign trigger updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignTriggerDTO'
      tags:
        - Campaign Triggers
      security:
        - tenantAdminJWT: []
    delete:
      operationId: CampaignTriggersController_deleteCampaignTrigger
      summary: Delete campaign trigger (Admin)
      description: >-
        Delete an existing campaign trigger. Admin-only operation. Replaces
        DELETE /campaign/admin/trigger/{id}
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Campaign trigger deleted successfully
          content:
            application/json:
              schema:
                type: boolean
      tags:
        - Campaign Triggers
      security:
        - tenantAdminJWT: []
  /campaign-triggers/campaigns/{id}/trigger/{triggerId}:
    put:
      operationId: CampaignTriggersController_assignTriggerToCampaign
      summary: Assign trigger to campaign (Admin)
      description: >-
        Assign a specific trigger to campaign for activation conditions.
        Admin-only operation. Replaces PUT
        /campaign/admin/{id}/trigger/{triggerId}
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
        - name: triggerId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Trigger assigned to campaign successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDTO'
      tags:
        - Campaign Triggers
      security:
        - tenantAdminJWT: []
  /campaign-triggers/conditions:
    post:
      operationId: CampaignTriggersController_createTriggerCondition
      summary: Create trigger condition (Admin)
      description: >-
        Create a new trigger condition for use in campaign triggers. Admin-only
        operation. Replaces POST /campaign/admin/trigger-condition
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignTriggerConditionDTO'
      responses:
        '200':
          description: Trigger condition created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignTriggerConditionCreateRequestDTO'
      tags:
        - Campaign Triggers
      security:
        - tenantAdminJWT: []
  /campaign-triggers/conditions/{id}:
    put:
      operationId: CampaignTriggersController_updateTriggerCondition
      summary: Update trigger condition (Admin)
      description: >-
        Update an existing trigger condition. Admin-only operation. Replaces PUT
        /campaign/admin/trigger-condition/{id}
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignTriggerConditionDTO'
      responses:
        '200':
          description: Trigger condition updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignTriggerConditionCreateRequestDTO'
      tags:
        - Campaign Triggers
      security:
        - tenantAdminJWT: []
  /campaign-triggers/{triggerId}/conditions/{conditionId}:
    put:
      operationId: CampaignTriggersController_toggleConditionInTrigger
      summary: Toggle condition in trigger (Admin)
      description: >-
        Add or remove a condition from a trigger (toggle relationship).
        Admin-only operation. Replaces PUT
        /campaign/admin/trigger/{triggerId}/condition/{conditionId}
      parameters:
        - name: triggerId
          required: true
          in: path
          schema:
            type: string
        - name: conditionId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Trigger condition relationship updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignTriggerDTO'
      tags:
        - Campaign Triggers
      security:
        - tenantAdminJWT: []
  /campaign-engagements/{id}:
    post:
      operationId: CampaignEngagementsController_createBusinessEngagementForCampaign
      summary: Create business engagement for campaign (Admin)
      description: >-
        Add a business engagement relationship to campaign for business-specific
        rewards. Admin-only operation. Replaces POST
        /campaign/admin/{id}/business-engagement
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignBusinessEngagementCreateRequestDTO'
      responses:
        '200':
          description: Business engagement added to campaign successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDTO'
      tags:
        - Campaign Engagements
      security:
        - tenantAdminJWT: []
  /campaign-engagements/{id}/{businessEngagementId}:
    put:
      operationId: CampaignEngagementsController_updateBusinessEngagementInCampaign
      summary: Update business engagement in campaign (Admin)
      description: >-
        Update an existing business engagement relationship in campaign.
        Admin-only operation. Replaces PUT
        /campaign/admin/{id}/business-engagement/{businessEngagementId}
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
        - name: businessEngagementId
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignBusinessEngagementCreateRequestDTO'
      responses:
        '200':
          description: Business engagement updated in campaign successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDTO'
      tags:
        - Campaign Engagements
      security:
        - tenantAdminJWT: []
    delete:
      operationId: CampaignEngagementsController_removeBusinessEngagementFromCampaign
      summary: Remove business engagement from campaign (Admin)
      description: >-
        Remove a business engagement relationship from campaign. Admin-only
        operation. Replaces DELETE
        /campaign/admin/{id}/business-engagement/{businessEngagementId}
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
        - name: businessEngagementId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Business engagement removed from campaign successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDTO'
      tags:
        - Campaign Engagements
      security:
        - tenantAdminJWT: []
  /campaign-claims/system:
    post:
      operationId: CampaignClaimsController_processSystemClaim
      summary: System claim reward (Critical Financial)
      description: >-
        Process automated reward claims via system API. BUSINESS CRITICAL -
        handles real financial transactions. Requires valid tenant system API
        key. Replaces POST /campaign/system/claim
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignClaimBusinessRequestDTO'
      responses:
        '200':
          description: System reward claim processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignUserClaimDTO'
      tags:
        - Campaign Claims
  /campaign-claims/business:
    post:
      operationId: CampaignClaimsController_processBusinessClaim
      summary: Business claim reward (Critical Financial)
      description: >-
        Process reward claims by business accounts for customers. BUSINESS
        CRITICAL - handles real financial transactions with business attribution
        and IP tracking. Replaces POST /campaign/business/claim
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignClaimBusinessRequestDTO'
      responses:
        '200':
          description: Business reward claim processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignUserClaimDTO'
      tags:
        - Campaign Claims
  /campaign-claims:
    post:
      operationId: CampaignClaimsController_processUserClaim
      summary: User claim reward (Critical Financial)
      description: >-
        Process reward claims by authenticated users for their own accounts.
        BUSINESS CRITICAL - handles real financial transactions with user
        attribution and IP tracking. Replaces POST /campaign/auth/claim
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignClaimRequestDTO'
      responses:
        '200':
          description: User reward claim processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignUserClaimDTO'
      tags:
        - Campaign Claims
      security:
        - projectKey: []
        - authUserJWT: []
  /campaign-claims/me/{campaignId}:
    get:
      operationId: CampaignClaimsController_getUserClaimsForCampaign
      summary: Get user claims for campaign
      description: >-
        Get authenticated user claim history for specific campaign. Financial
        records with user attribution. Replaces GET
        /campaign/auth/{campaignId}/claim
      parameters:
        - name: campaignId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: User claim history for campaign retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CampaignUserClaimDTO'
      tags:
        - Campaign Claims
      security:
        - projectKey: []
        - authUserJWT: []
  /campaign-claims/me:
    get:
      operationId: CampaignClaimsController_getAllUserClaims
      summary: Get all user claims
      description: >-
        Get authenticated user complete claim history across all campaigns.
        Financial records with user attribution. Replaces GET
        /campaign/auth/claim
      parameters: []
      responses:
        '200':
          description: Complete user claim history retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CampaignUserClaimDTO'
      tags:
        - Campaign Claims
      security:
        - projectKey: []
        - authUserJWT: []
  /campaign-claims/admin:
    get:
      operationId: CampaignClaimsController_getAllClaimsHistory
      summary: Get all claims history (Admin)
      description: >-
        Get complete claims history across all campaigns and users for
        administrative oversight. Admin-only financial reporting. Replaces GET
        /campaign/admin/claim
      parameters: []
      responses:
        '200':
          description: Complete claims history retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CampaignUserClaimDTO'
      tags:
        - Campaign Claims
      security:
        - tenantAdminJWT: []
  /campaign-claims/admin/{campaignId}:
    get:
      operationId: CampaignClaimsController_getCampaignClaimsHistory
      summary: Get campaign claims history (Admin)
      description: >-
        Get all claims for specific campaign for administrative oversight.
        Admin-only financial reporting. Replaces GET
        /campaign/admin/{campaignId}/claim
      parameters:
        - name: campaignId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Campaign claims history retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CampaignUserClaimDTO'
      tags:
        - Campaign Claims
      security:
        - tenantAdminJWT: []
  /campaign-claims/admin/users/{userId}:
    get:
      operationId: CampaignClaimsController_getClaimsByUser
      summary: Get user claims (Admin)
      description: >-
        Get all claims by specific user across all campaigns for administrative
        oversight. Admin-only financial reporting. Replaces GET
        /campaign/admin/claim/user/{userId}
      parameters:
        - name: userId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: User claims history retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CampaignUserClaimDTO'
      tags:
        - Campaign Claims
      security:
        - tenantAdminJWT: []
  /campaign-claims/admin/businesses/{businessId}:
    get:
      operationId: CampaignClaimsController_getClaimsByBusiness
      summary: Get business claims (Admin)
      description: >-
        Get all claims by specific business across all campaigns for
        administrative oversight. Admin-only financial reporting. Replaces GET
        /campaign/admin/claim/business/{businessId}
      parameters:
        - name: businessId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Business claims history retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CampaignUserClaimDTO'
      tags:
        - Campaign Claims
      security:
        - tenantAdminJWT: []
  /redemptions/types:
    get:
      operationId: RedemptionsController_getRedemptionTypes
      summary: Get redemption types
      description: >-
        Get all available redemption types for client reference. Requires valid
        project API key.
      parameters: []
      responses:
        '200':
          description: Redemption types retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RedemptionTypeDTO'
      tags:
        - Redemptions
      security:
        - projectKey: []
    post:
      operationId: RedemptionsController_createRedemptionType
      summary: Create redemption type (Admin)
      description: >-
        Create a new redemption type for system configuration. Replaces POST
        /redemption/admin/type
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedemptionTypeCreateRequestDTO'
      responses:
        '200':
          description: Redemption type created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedemptionTypeDTO'
      tags:
        - Redemptions
      security:
        - tenantAdminJWT: []
  /redemptions/{id}:
    get:
      operationId: RedemptionsController_getRedemptionById
      summary: Get redemption by ID
      description: Get specific redemption details by ID. Requires valid project API key.
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Redemption details retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedemptionDTO'
      tags:
        - Redemptions
      security:
        - projectKey: []
    put:
      operationId: RedemptionsController_updateRedemption
      summary: Update redemption (Admin)
      description: >-
        Update existing redemption information. Replaces PUT
        /redemption/admin/{id}
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedemptionCreateRequestDTO'
      responses:
        '200':
          description: Redemption updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedemptionDTO'
      tags:
        - Redemptions
      security:
        - tenantAdminJWT: []
    delete:
      operationId: RedemptionsController_deleteRedemption
      summary: Delete redemption (Admin)
      description: Permanently delete a redemption. Replaces DELETE /redemption/admin/{id}
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Redemption deleted successfully
          content:
            application/json:
              schema:
                type: boolean
      tags:
        - Redemptions
      security:
        - tenantAdminJWT: []
  /redemptions/{id}/available-supply:
    get:
      operationId: RedemptionsController_getAvailableSupply
      summary: Get redemption available supply
      description: >-
        Get the available supply count for a specific redemption. Used for
        inventory display.
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Available supply count
          content:
            application/json:
              schema:
                type: number
      tags:
        - Redemptions
      security:
        - projectKey: []
  /redemptions/{id}/redeem:
    post:
      operationId: RedemptionsController_redeemRedemption
      summary: Redeem redemption (User)
      description: >-
        Execute a redemption for the authenticated user. This is a
        business-critical operation with IP tracking for fraud prevention.
        Replaces POST /redemption/auth/redeem
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - redemptionId
              properties:
                redemptionId:
                  type: string
                  format: uuid
                  description: >-
                    The ID of the redemption to redeem (must match path
                    parameter)
      responses:
        '200':
          description: Redemption executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedemptionUserRedeemDetailedDTO'
      tags:
        - Redemptions
      security:
        - projectKey: []
        - authUserJWT: []
  /redemptions/me/history:
    get:
      operationId: RedemptionsController_getUserRedemptionHistory
      summary: Get user redemption history
      description: >-
        Get all redemptions executed by the authenticated user. Replaces GET
        /redemption/auth/redeem
      parameters: []
      responses:
        '200':
          description: User redemption history
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RedemptionUserRedeemDTO'
      tags:
        - Redemptions
      security:
        - projectKey: []
        - authUserJWT: []
  /redemptions:
    get:
      operationId: RedemptionsController_getRedemptions
      summary: Get redemptions (Intelligent Access)
      description: >-
        Intelligent endpoint that adapts based on authentication: Public users
        get active redemptions only, Admin users get all redemptions with
        optional filtering. Consolidates GET /redemption and GET
        /redemption/admin
      parameters:
        - name: active
          required: false
          in: query
          description: >-
            Filter by active status (Admin only: true=active, false=inactive,
            omit=all). Ignored for public access.
          schema:
            type: boolean
      responses:
        '200':
          description: Redemptions retrieved based on access level
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RedemptionDTO'
      tags:
        - Redemptions
      security:
        - projectKey: []
    post:
      operationId: RedemptionsController_createRedemption
      summary: Create redemption (Admin)
      description: >-
        Create a new redemption with administrative privileges. Replaces POST
        /redemption/admin
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedemptionCreateRequestDTO'
      responses:
        '200':
          description: Redemption created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedemptionDTO'
      tags:
        - Redemptions
      security:
        - tenantAdminJWT: []
  /redemptions/{id}/status:
    put:
      operationId: RedemptionsController_toggleRedemptionStatus
      summary: Toggle redemption status (Admin)
      description: >-
        Toggle redemption between active and inactive status. Follows standard
        /status pattern. Replaces PUT /redemption/admin/{id}/toggle-active
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Redemption status toggled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedemptionDTO'
      tags:
        - Redemptions
      security:
        - tenantAdminJWT: []
  /redemptions/{id}/token-units:
    post:
      operationId: RedemptionsController_addTokenUnitToRedemption
      summary: Add token unit to redemption (Admin)
      description: >-
        Add a new token unit to an existing redemption. Replaces POST
        /redemption/admin/{id}/token-units
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenUnitCreateRequestDTO'
      responses:
        '200':
          description: Token unit added to redemption
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedemptionDTO'
      tags:
        - Redemptions
      security:
        - tenantAdminJWT: []
  /redemptions/{id}/token-units/{tokenUnitId}:
    put:
      operationId: RedemptionsController_updateTokenUnit
      summary: Update redemption token unit (Admin)
      description: >-
        Update an existing token unit within a redemption. Replaces PUT
        /redemption/admin/{id}/token-units/{tokenUnitId}
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
        - name: tokenUnitId
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenUnitCreateRequestDTO'
      responses:
        '200':
          description: Token unit updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedemptionDTO'
      tags:
        - Redemptions
      security:
        - tenantAdminJWT: []
    delete:
      operationId: RedemptionsController_removeTokenUnit
      summary: Remove token unit from redemption (Admin)
      description: >-
        Remove an existing token unit from a redemption. Replaces DELETE
        /redemption/admin/{id}/token-units/{tokenUnitId}
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
        - name: tokenUnitId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Token unit removed from redemption
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedemptionDTO'
      tags:
        - Redemptions
      security:
        - tenantAdminJWT: []
  /users/me:
    get:
      operationId: UsersController_getCurrentUser
      summary: Get current user info
      description: Get authenticated user account info without balances
      parameters: []
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDTO'
        '404':
          description: User not found
      tags:
        - Users
      security:
        - projectKey: []
        - authUserJWT: []
    put:
      operationId: UsersController_updateCurrentUser
      summary: Update current user
      description: Update authenticated user account
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreateRequestDTO'
      responses:
        '200':
          description: User updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDTO'
        '404':
          description: User not found
      tags:
        - Users
      security:
        - projectKey: []
        - authUserJWT: []
  /users/me/balance:
    get:
      operationId: UsersController_getCurrentUserBalance
      summary: Get current user balance
      description: Get authenticated user account with current token balances
      parameters: []
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserTokenBalancesDTO'
        '404':
          description: User not found
      tags:
        - Users
      security:
        - projectKey: []
        - authUserJWT: []
  /users/me/status:
    get:
      operationId: UsersController_getCurrentUserStatus
      summary: Get current user status
      description: Get authenticated user status types
      parameters: []
      responses:
        '200':
          description: User status found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserStatusTypeDTO'
        '404':
          description: User status not found
      tags:
        - Users
      security:
        - projectKey: []
        - authUserJWT: []
  /users/exists:
    get:
      operationId: UsersController_checkUserExists
      summary: Check if user exists
      description: Check if a user exists using any identifier field (id, email, etc.)
      parameters:
        - name: filterValue
          required: true
          in: query
          description: Value to search for
          schema:
            type: string
        - name: filterKey
          required: false
          in: query
          description: >-
            Field to use for identification (id, email, instagramAccountId,
            etc.)
          schema:
            enum:
              - id
              - email
              - instagramAccountId
              - externalId
            type: string
      responses:
        '200':
          description: User existence check result
          content:
            application/json:
              schema:
                type: object
                properties:
                  exists:
                    type: boolean
                    example: true
                  identifier:
                    type: string
                    example: email
        '400':
          description: Invalid filter parameters
        '404':
          description: User not found
      tags:
        - Users
      security:
        - projectKey: []
  /users/public:
    get:
      operationId: UsersController_getAllPublicProfiles
      summary: Get all public profiles
      description: Get all public user profiles
      parameters:
        - name: filterKey
          required: false
          in: query
          description: Property key in publicProfile to filter by
          schema:
            type: string
        - name: filterValue
          required: false
          in: query
          description: Value to match in the publicProfile property
          schema:
            type: string
      responses:
        '200':
          description: Public profiles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicUserDTO'
        '404':
          description: Public profiles not found
      tags:
        - Users
      security:
        - projectKey: []
  /users/public/{id}:
    get:
      operationId: UsersController_getPublicProfile
      summary: Get public profile
      description: Get a public profile by user ID
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Public profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicUserDTO'
        '404':
          description: Public profile not found
      tags:
        - Users
      security:
        - projectKey: []
  /users/status-types:
    get:
      operationId: UsersController_getAllUserStatusTypes
      summary: Get all user status types
      description: Get all available user status types
      parameters: []
      responses:
        '200':
          description: User status types
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserStatusTypeDTO'
      tags:
        - Users
      security:
        - projectKey: []
    post:
      operationId: UsersController_createUserStatusType
      summary: Create user status type
      description: Create user status type as admin
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserStatusTypeCreateRequestDTO'
      responses:
        '200':
          description: User status type created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserStatusTypeDTO'
      tags:
        - Users
      security:
        - tenantAdminJWT: []
  /users/status-types/{id}:
    get:
      operationId: UsersController_getUserStatusType
      summary: Get user status type
      description: Get a user status type by ID
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: User status type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserStatusTypeDTO'
        '404':
          description: User status type not found
      tags:
        - Users
      security:
        - projectKey: []
  /users/status-types/{id}/eligible-tokens/{tokenAddress}:
    put:
      operationId: UsersController_updateUserStatusTypeEligibleToken
      summary: Update eligible token for status type
      description: Add or remove eligible token for user status type as admin
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
        - name: tokenAddress
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: User status type updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserStatusTypeDTO'
        '404':
          description: User status type not found
      tags:
        - Users
      security:
        - tenantAdminJWT: []
  /users/info:
    post:
      operationId: UsersController_getUserInfo
      summary: Get user info
      description: >-
        Get user account info without balances (business with user management
        permission OR admin authentication required)
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreateRequestDTO'
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDTO'
        '404':
          description: User not found
      tags:
        - Users
      security:
        - tenantAdminJWT: []
        - projectKey: []
  /users/balance:
    post:
      operationId: UsersController_getUserBalance
      summary: Get user balance
      description: >-
        Get user account with current token balances (business with user
        management permission OR admin authentication required)
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreateRequestDTO'
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserTokenBalancesDTO'
        '404':
          description: User not found
      tags:
        - Users
      security:
        - tenantAdminJWT: []
        - projectKey: []
  /users:
    post:
      operationId: UsersController_createOrUpdateUser
      summary: Create or update user account
      description: >-
        Create or update user account(s). Supports single user (business/admin)
        or bulk operations (admin only)
      parameters: []
      requestBody:
        required: true
        description: >-
          Single user object or array of users (bulk operations require admin
          authentication)
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/UserCreateRequestDTO'
                - type: array
                  items:
                    $ref: '#/components/schemas/UserCreateRequestDTO'
      responses:
        '200':
          description: User(s) created/updated
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/UserDTO'
                  - type: array
                    items:
                      $ref: '#/components/schemas/UserDTO'
      tags:
        - Users
      security:
        - tenantAdminJWT: []
        - projectKey: []
    get:
      operationId: UsersController_getAllUsers
      summary: Get all users
      description: >-
        Get all users with role-based access. Project API key users get public
        profiles only. Admin users get full access with query parameters.
      parameters:
        - name: sanitize
          required: false
          in: query
          description: >-
            Sanitize user models: soft checks for current wallet address, hard
            overwrites wallet in case of update (use with caution, admin only)
          schema:
            type: string
        - name: merge
          required: false
          in: query
          description: >-
            Merge user models: soft checks for current wallet address, hard
            overwrites wallet in case of update (use with caution, admin only)
          schema:
            type: string
      responses:
        '200':
          description: Users found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserDTO'
      tags:
        - Users
      security:
        - tenantAdminJWT: []
        - projectKey: []
  /users/{id}:
    get:
      operationId: UsersController_getUserById
      summary: Get user by ID
      description: Get user by any identifier field (admin only)
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDTO'
        '404':
          description: User not found
      tags:
        - Users
      security:
        - tenantAdminJWT: []
    put:
      operationId: UsersController_updateUserAdmin
      summary: Update user (admin)
      description: Update user account as admin
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreateRequestDTO'
      responses:
        '200':
          description: User updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDTO'
        '404':
          description: User not found
      tags:
        - Users
      security:
        - tenantAdminJWT: []
  /users/bulk/url:
    post:
      operationId: UsersController_createUsersFromUrl
      summary: Create users from URL (admin)
      description: Create user accounts from external URL as admin
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UrlRequestDTO'
      responses:
        '200':
          description: Users created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserDTO'
        '404':
          description: User not found
      tags:
        - Users
      security:
        - tenantAdminJWT: []
  /users/{id}/status:
    put:
      operationId: UsersController_toggleUserStatus
      summary: Toggle user status
      description: Toggle user active status as admin
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: User status updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDTO'
        '404':
          description: User not found
      tags:
        - Users
      security:
        - tenantAdminJWT: []
  /businesses/types:
    post:
      operationId: BusinessesController_createBusinessType
      summary: Create a new business type
      description: Create a new business type
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessTypeCreateRequestDTO'
      responses:
        '200':
          description: Business type created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessTypeDTO'
      tags:
        - Businesses
      security:
        - tenantAdminJWT: []
    put:
      operationId: BusinessesController_updateBusinessType
      summary: Update a business type
      description: Update a business type
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessTypeDTO'
      responses:
        '200':
          description: Business type updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessTypeDTO'
      tags:
        - Businesses
      security:
        - tenantAdminJWT: []
    get:
      operationId: BusinessesController_getAllBusinessTypes
      summary: Get all business types
      description: Get all business types
      parameters: []
      responses:
        '200':
          description: Business types found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BusinessTypeDTO'
      tags:
        - Businesses
      security:
        - projectKey: []
  /businesses/types/{id}:
    delete:
      operationId: BusinessesController_deleteBusinessType
      summary: Delete a business type
      description: Delete a business type
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Business type deleted
          content:
            application/json:
              schema:
                type: boolean
      tags:
        - Businesses
      security:
        - tenantAdminJWT: []
  /businesses/me:
    get:
      operationId: BusinessesController_getCurrentBusiness
      summary: Get current business info
      description: >-
        Get business info with current token balances (business authentication
        required)
      parameters: []
      responses:
        '200':
          description: Business found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessTokenBalancesDTO'
        '404':
          description: Business not found
      tags:
        - Businesses
  /businesses:
    get:
      operationId: BusinessesController_getAllBusinesses
      summary: Get all businesses
      description: >-
        Get all businesses. Project API key users get active businesses only.
        Admin users (with valid JWT) get full access with query parameters.
      parameters:
        - name: active
          required: false
          in: query
          description: Filter by active status (admin only for inactive)
          schema:
            type: string
        - name: sanitize
          required: false
          in: query
          description: >-
            Sanitize user models: soft checks for current wallet address, hard
            overwrites wallet in case of update (use with caution, admin only)
          schema:
            type: string
      responses:
        '200':
          description: Businesses found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BusinessDTO'
        '404':
          description: Businesses not found
      tags:
        - Businesses
      security:
        - projectKey: []
    post:
      operationId: BusinessesController_createBusiness
      summary: Create a new business
      description: Create a new business account, will be inactive until activated by admin
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessCreateRequestDTO'
      responses:
        '200':
          description: Business created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessApiKeyDTO'
      tags:
        - Businesses
      security:
        - tenantAdminJWT: []
  /businesses/account/{accountAddress}:
    get:
      operationId: BusinessesController_getByAccountAddress
      summary: Get business by account address
      description: Get business info by account address
      parameters:
        - name: accountAddress
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Business found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessDTO'
        '404':
          description: Business not found
      tags:
        - Businesses
      security:
        - projectKey: []
  /businesses/{id}:
    get:
      operationId: BusinessesController_getById
      summary: Get business by ID
      description: Get business info by ID
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Business found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessDTO'
        '404':
          description: Business not found
      tags:
        - Businesses
      security:
        - projectKey: []
    put:
      operationId: BusinessesController_updateBusiness
      summary: Update a business
      description: Update a business account
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessUpdateRequestDTO'
      responses:
        '200':
          description: Business updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessDTO'
      tags:
        - Businesses
      security:
        - tenantAdminJWT: []
  /businesses/bulk/url:
    post:
      operationId: BusinessesController_createBusinessesFromUrl
      summary: Create multiple businesses from URL
      description: >-
        Create multiple business accounts by fetching a JSON file from the
        provided URL. The file at the URL is expected to be a JSON object
        conforming to the BusinessBulkCreateRequestDTO structure, containing an
        array of business data.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UrlRequestDTO'
      responses:
        '200':
          description: Businesses created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BusinessDTO'
        '404':
          description: Businesses not found
      tags:
        - Businesses
      security:
        - tenantAdminJWT: []
  /businesses/{id}/status:
    put:
      operationId: BusinessesController_toggleBusinessStatus
      summary: Toggle business status
      description: Toggle business account active status
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessToggleActiveRequestDTO'
      responses:
        '200':
          description: Business status updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessDTO'
      tags:
        - Businesses
      security:
        - tenantAdminJWT: []
  /businesses/{id}/api-key:
    put:
      operationId: BusinessesController_generateNewBusinessApiKey
      summary: Generate new API key
      description: Retrieve a new api key and revoke previous
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: New API key generated
          content:
            application/json:
              schema:
                type: string
        '404':
          description: Business not found
      tags:
        - Businesses
      security:
        - tenantAdminJWT: []
  /transactions/me/sent:
    get:
      operationId: TransactionsController_getUserSentTransactions
      summary: Get authenticated user's sent transactions
      description: >-
        Get transactions where the authenticated user is the sender. Replaces
        GET /transaction/auth/sender
      parameters: []
      responses:
        '200':
          description: User sent transactions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TransactionDTO'
      tags:
        - Transactions
      security:
        - projectKey: []
        - authUserJWT: []
  /transactions/me/received:
    get:
      operationId: TransactionsController_getUserReceivedTransactions
      summary: Get authenticated user's received transactions
      description: >-
        Get transactions where the authenticated user is the recipient. Replaces
        GET /transaction/auth/recipient
      parameters: []
      responses:
        '200':
          description: User received transactions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TransactionDTO'
      tags:
        - Transactions
      security:
        - projectKey: []
        - authUserJWT: []
  /transactions:
    get:
      operationId: TransactionsController_getAllTransactions
      summary: Get all transactions with pagination (Admin)
      description: >-
        Get all transactions with structured pagination and filtering. RLS
        ensures tenant isolation automatically. Replaces GET /transaction/admin
      parameters: []
      responses:
        '200':
          description: Paginated transactions list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponseDTO'
      tags:
        - Transactions
      security:
        - tenantAdminJWT: []
  /transactions/query-sender:
    post:
      operationId: TransactionsController_queryTransactionsBySender
      summary: Query transactions by sender (Admin)
      description: >-
        Get transactions by sender for any account. Replaces POST
        /transaction/admin/sender
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountSelectorDTO'
      responses:
        '200':
          description: Transactions as sender
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TransactionDTO'
      tags:
        - Transactions
      security:
        - tenantAdminJWT: []
  /transactions/query-recipient:
    post:
      operationId: TransactionsController_queryTransactionsByRecipient
      summary: Query transactions by recipient (Admin)
      description: >-
        Get transactions by recipient for any account. Replaces POST
        /transaction/admin/recipient
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountSelectorDTO'
      responses:
        '200':
          description: Transactions as recipient
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TransactionDTO'
      tags:
        - Transactions
      security:
        - tenantAdminJWT: []
  /transactions/{id}:
    get:
      operationId: TransactionsController_getTransactionById
      summary: Get transaction by ID
      description: Get single transaction by ID. Requires valid project API key.
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Transaction found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionDTO'
      tags:
        - Transactions
      security:
        - projectKey: []
  /transactions/system:
    post:
      operationId: TransactionsController_createSystemTransaction
      summary: Create system transaction (Admin)
      description: >-
        Create any type of transaction (MINT/TRANSFER/BURN) using administrative
        privileges. Replaces POST /transaction/admin/transaction
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRequestDTO'
      responses:
        '200':
          description: System transaction created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionDTO'
      tags:
        - Transactions
      security:
        - tenantAdminJWT: []
  /transactions/user:
    post:
      operationId: TransactionsController_createUserTransaction
      summary: Create user transaction
      description: >-
        Create transaction for authenticated user. Sender automatically set to
        authenticated user. Replaces POST /transaction/auth/transaction
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRequestDTO'
      responses:
        '200':
          description: User transaction created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionDTO'
      tags:
        - Transactions
      security:
        - authUserJWT: []
  /transactions/business:
    post:
      operationId: TransactionsController_createBusinessTransaction
      summary: Create business transaction
      description: >-
        Create transaction for business context. Replaces POST
        /transaction/business/transaction
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRequestDTO'
      responses:
        '200':
          description: Business transaction created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionDTO'
      tags:
        - Transactions
  /transactions/prepare:
    post:
      operationId: TransactionsController_prepareTransaction
      summary: Prepare transaction for client-side signing
      description: >-
        Prepares transaction data for client-side execution. Returns the data
        needed for the client to sign and submit the transaction.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientTransactionRequestDTO'
      responses:
        '200':
          description: Transaction prepared successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientTransactionRequestResponseDto'
      tags:
        - Transactions
      security:
        - projectKey: []
        - authUserJWT: []
  /transactions/{id}/prepare:
    get:
      operationId: TransactionsController_prepareTransactionById
      summary: Prepare existing transaction for client-side signing
      description: >-
        Prepares transaction data for client-side execution from existing
        transaction ID. Returns the data needed for the client to sign and
        submit the transaction.
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Transaction prepared successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientTransactionRequestResponseDto'
      tags:
        - Transactions
      security:
        - projectKey: []
        - authUserJWT: []
  /transactions/{id}/submit:
    post:
      operationId: TransactionsController_submitTransaction
      summary: Submit client-side signed transaction
      description: >-
        Submits a signed transaction from the client. This method is used to
        finalize the transaction after the client has signed it.
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientTransactionConfirmationDTO'
      responses:
        '200':
          description: Transaction submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionDTO'
      tags:
        - Transactions
      security:
        - projectKey: []
        - authUserJWT: []
  /transactions/export/csv:
    get:
      operationId: TransactionsController_exportTransactionsAsCsv
      summary: Export all transactions as CSV
      description: >-
        Downloads all transactions as a CSV file. RLS ensures tenant isolation
        automatically. File includes all transaction data formatted for business
        analysis.
      parameters: []
      responses:
        '200':
          description: CSV file download
          headers:
            Content-Type:
              description: MIME type of the file
              schema:
                type: string
                example: text/csv
            Content-Disposition:
              description: File download attachment
              schema:
                type: string
                example: attachment; filename="transactions_2024-01-15.csv"
          content:
            application/json:
              schema:
                type: string
                format: binary
      tags:
        - Transactions
      security:
        - tenantAdminJWT: []
  /transactions/analytics:
    post:
      operationId: TransactionsController_getTransactionAnalytics
      summary: Get transaction analytics
      description: >-
        Get transaction analytics with dynamic filtering, grouping, and metrics.
        Optimized for dashboard modules: stamps count, rewards analysis, top
        users, etc. RLS ensures tenant isolation automatically.
      parameters: []
      requestBody:
        required: true
        description: Analytics configuration with filters, grouping, and metrics
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionAnalyticsRequestDTO'
            examples:
              stampsCount:
                summary: Count stamps by month
                value:
                  filters:
                    status: SUCCEEDED
                    tokenType: STAMP
                  groupBy:
                    - month
                  metrics:
                    - count
                  orderBy: count
                  orderDirection: DESC
                  limit: 12
      responses:
        '200':
          description: Analytics results retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionAnalyticsResponseDTO'
      tags:
        - Transactions
      security:
        - tenantAdminJWT: []
  /tokens:
    get:
      operationId: TokensController_getAllTokens
      summary: Get all token contracts
      description: >-
        Retrieve all token contracts for the project. Only admins can access
        inactive tokens via ?active=false parameter.
      parameters:
        - name: active
          required: false
          in: query
          description: >-
            Filter for active tokens only (default: true). Non-admin users
            always get active tokens only.
          schema:
            type: string
      responses:
        '200':
          description: Tokens retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TokenDTO'
      tags:
        - Tokens
      security:
        - projectKey: []
    post:
      operationId: TokensController_createToken
      summary: Create new token contract
      description: >-
        ADMIN: Create a new testnet token contract for the project. This can
        later be converted to mainnet.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenCreateRequestDTO'
      responses:
        '200':
          description: Token created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenDTO'
      tags:
        - Tokens
      security:
        - tenantAdminJWT: []
  /tokens/address/{contractAddress}:
    get:
      operationId: TokensController_getTokenByAddress
      summary: Get token by contract address
      description: Retrieve token information by contract address
      parameters:
        - name: contractAddress
          required: true
          in: path
          schema:
            type: string
        - name: contractTokenId
          required: false
          in: query
          description: Token ID for ERC721 or ERC1155 tokens
          schema:
            type: string
      responses:
        '200':
          description: Token retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenDTO'
      tags:
        - Tokens
      security:
        - projectKey: []
  /tokens/points:
    get:
      operationId: TokensController_getActivePointToken
      summary: Get active point token
      description: Retrieve the active point token contract for the project
      parameters: []
      responses:
        '200':
          description: Point token retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenDTO'
      tags:
        - Tokens
      security:
        - projectKey: []
  /tokens/rewards:
    get:
      operationId: TokensController_getRewardTokens
      summary: Get all reward tokens
      description: >-
        Retrieve all reward token contracts (ERC1155 tokens). Only admins can
        access inactive tokens via ?active=false parameter.
      parameters:
        - name: active
          required: false
          in: query
          description: >-
            Filter for active reward tokens only (default: true). Non-admin
            users always get active tokens only.
          schema:
            type: string
      responses:
        '200':
          description: Reward tokens retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TokenDTO'
      tags:
        - Tokens
      security:
        - projectKey: []
  /tokens/stamps:
    get:
      operationId: TokensController_getStampTokens
      summary: Get all stamp tokens
      description: >-
        Retrieve all stamp token contracts (ERC721 tokens). Only admins can
        access inactive tokens via ?active=false parameter.
      parameters:
        - name: active
          required: false
          in: query
          description: >-
            Filter for active stamp tokens only (default: true). Non-admin users
            always get active tokens only.
          schema:
            type: string
      responses:
        '200':
          description: Stamp tokens retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TokenDTO'
      tags:
        - Tokens
      security:
        - projectKey: []
  /tokens/types:
    get:
      operationId: TokensController_getAllTokenTypes
      summary: Get all token types
      description: Retrieve all available token types for the project
      parameters: []
      responses:
        '200':
          description: Token types retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TokenTypeDTO'
      tags:
        - Tokens
      security:
        - projectKey: []
    post:
      operationId: TokensController_createTokenType
      summary: Create new token type
      description: 'ADMIN: Create a new token type for the project'
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenTypeDTO'
      responses:
        '200':
          description: Token type created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenTypeDTO'
      tags:
        - Tokens
      security:
        - tenantAdminJWT: []
  /tokens/{id}:
    put:
      operationId: TokensController_updateToken
      summary: Update token contract
      description: 'ADMIN: Update token contract information'
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenUpdateRequestDTO'
      responses:
        '200':
          description: Token updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenDTO'
      tags:
        - Tokens
      security:
        - tenantAdminJWT: []
  /tokens/{id}/status:
    put:
      operationId: TokensController_toggleTokenStatus
      summary: Toggle token active status
      description: 'ADMIN: Toggle token active status to enable/disable usage'
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Token status updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenDTO'
      tags:
        - Tokens
      security:
        - tenantAdminJWT: []
  /tokens/{id}/mainnet:
    put:
      operationId: TokensController_setMainnetContract
      summary: Set mainnet contract address
      description: 'ADMIN: Associate mainnet contract address with existing testnet token'
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                contractAddress:
                  type: string
                  description: Mainnet contract address
                chainId:
                  type: number
                  description: Chain ID for the mainnet contract
              required:
                - contractAddress
                - chainId
      responses:
        '200':
          description: Mainnet contract address set successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenDTO'
      tags:
        - Tokens
      security:
        - tenantAdminJWT: []
  /tokens/{id}/metadata:
    post:
      operationId: TokensController_createTokenMetadata
      summary: Create token metadata
      description: 'ADMIN: Create metadata for a specific token contract'
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenMetadataCreateRequestDTO'
      responses:
        '200':
          description: Token metadata created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenMetadataDTO'
      tags:
        - Tokens
      security:
        - tenantAdminJWT: []
  /tokens/metadata/{id}/status:
    put:
      operationId: TokensController_toggleTokenMetadataStatus
      summary: Toggle token metadata status
      description: 'ADMIN: Toggle token metadata active status'
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Token metadata status updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenMetadataDTO'
      tags:
        - Tokens
      security:
        - tenantAdminJWT: []
  /tenants:
    post:
      operationId: TenantsController_createTenant
      summary: Create new tenant
      description: >-
        Create a new tenant (project) in the system. This is the initial setup
        step for new organizations.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantCreateRequestDTO'
      responses:
        '200':
          description: Tenant created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantDTO'
      tags:
        - Tenants
    put:
      operationId: TenantsController_updateTenant
      summary: Update tenant configuration
      description: 'ADMIN: Update tenant information and settings'
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantUpdateRequestDTO'
      responses:
        '200':
          description: Tenant updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantDTO'
      tags:
        - Tenants
      security:
        - tenantAdminJWT: []
  /tenants/public:
    get:
      operationId: TenantsController_getPublicTenant
      summary: Get public tenant information
      description: Retrieve public tenant information visible to all users
      parameters: []
      responses:
        '200':
          description: Public tenant information retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantPublicDTO'
      tags:
        - Tenants
      security:
        - projectKey: []
  /tenants/client-config:
    get:
      operationId: TenantsController_getClientConfig
      summary: Get client configuration
      description: Retrieve client-side configuration for the project
      parameters: []
      responses:
        '200':
          description: Client configuration retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantClientConfigDTO'
      tags:
        - Tenants
      security:
        - projectKey: []
  /tenants/login-token:
    get:
      operationId: TenantsController_getLoginToken
      summary: Get login token
      description: Generate a login token for the project
      parameters: []
      responses:
        '200':
          description: Login token generated successfully
          content:
            application/json:
              schema:
                type: string
      tags:
        - Tenants
      security:
        - projectKey: []
  /tenants/api-keys:
    post:
      operationId: TenantsController_createApiKey
      summary: Create new API key
      description: >-
        ADMIN: Create a new API key for the tenant. Store this key securely - it
        cannot be retrieved again.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantApiKeyRequestDTO'
      responses:
        '200':
          description: API key created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantDTO'
      tags:
        - Tenants
      security:
        - tenantAdminJWT: []
  /tenants/jwt-tokens:
    post:
      operationId: TenantsController_createJwtToken
      summary: Create new JWT token
      description: >-
        ADMIN: Create a new JWT token for the tenant. Store this token securely
        - it cannot be retrieved again.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantJWTRequestDTO'
      responses:
        '200':
          description: JWT token created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantDTO'
      tags:
        - Tenants
      security:
        - tenantAdminJWT: []
  /admins:
    get:
      operationId: AdminsController_getAdmins
      summary: Get all admins
      description: 'ADMIN: Retrieve all admins associated with the current tenant'
      parameters: []
      responses:
        '200':
          description: Admins retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AdminDTO'
      tags:
        - Admins
      security:
        - tenantAdminJWT: []
    post:
      operationId: AdminsController_createOrUpdateAdmin
      summary: Create or update admin
      description: >-
        ADMIN: Create a new admin or update an existing admin within the tenant
        scope
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminCreateRequestDTO'
      responses:
        '200':
          description: Admin created or updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminDTO'
      tags:
        - Admins
      security:
        - tenantAdminJWT: []
  /admins/{adminId}/tenant:
    put:
      operationId: AdminsController_toggleAdminTenantAssociation
      summary: Toggle admin-tenant association
      description: >-
        ADMIN: Associate or disassociate the specified admin with the current
        tenant. This affects admin tenant access.
      parameters:
        - name: adminId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Admin-tenant association updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminDTO'
      tags:
        - Admins
      security:
        - tenantAdminJWT: []
  /:
    get:
      operationId: RootController_get
      parameters: []
      responses:
        '200':
          description: ''
      tags:
        - Root
      security:
        - '': []
  /healthcheck:
    get:
      operationId: RootController_getCurrentTime
      parameters: []
      responses:
        '200':
          description: ''
      tags:
        - Root
  /system:
    get:
      operationId: RootController_getSystem
      summary: Check if tenant system api key is valid
      description: Check if tenant system api key is valid
      parameters: []
      responses:
        '200':
          description: ''
      tags:
        - Root
  /admin:
    get:
      operationId: RootController_getAdmin
      summary: 'ADMIN: Check if admin'
      description: Get if admin
      parameters: []
      responses:
        '200':
          description: ''
      tags:
        - Root
      security:
        - tenantAdminJWT: []
  /geolocation:
    get:
      operationId: RootController_testGeo
      parameters: []
      responses:
        '200':
          description: ''
      tags:
        - Root
  /.well-known/jwks.json:
    get:
      operationId: JwksController_getJwks
      summary: Get JWKS
      parameters: []
      responses:
        '200':
          description: ''
      tags:
        - Well-known
  /balances/accounts/{accountAddress}:
    get:
      operationId: BalancesController_getAccountBalance
      summary: Get account balance by address (Admin)
      description: >-
        Get detailed balance information including token metadata for any
        account address. Requires tenant admin privileges. Replaces GET
        /balance/admin/account/{accountAddress}
      parameters:
        - name: accountAddress
          required: true
          in: path
          schema:
            type: string
        - name: includeInactive
          required: false
          in: query
          description: 'Include inactive tokens in balance response (default: false)'
          schema:
            type: boolean
      responses:
        '200':
          description: Account balance retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountTokenMetadataBalancesDTO'
        '404':
          description: Account not found or invalid address format
      tags:
        - Balances
      security:
        - tenantAdminJWT: []
  /auth/token:
    post:
      operationId: AuthController_createToken
      summary: Create authentication token
      description: |2-

                Universal token creation supporting multiple authentication flows:
                
                **USER TOKEN CREATION (External Providers)**:
                - Header: X-API-Key (tenant identification)
                - Body: { authToken: "jwt_from_provider" }
                - Supported providers: DFNS, Firebase, Auth0, Okta
                
                **ADMIN TOKEN CREATION**:
                - Header: Authorization: Bearer admin_jwt
                - Body: {} (admin context from JWT)
                - Returns tenant-scoped admin tokens
                
                **FUTURE EXTENSIBILITY**:
                - Provider-specific token exchange flows
                - Multi-provider token creation patterns
                - Automatic provider detection and validation
                
      parameters: []
      responses:
        '200':
          description: >-
            Token created successfully - UserAuthResponseDTO for user
            authentication, AdminLoginResponseDTO for admin authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionAuthResponseDTO'
        '400':
          description: Malformed request or missing authentication data
        '401':
          description: Invalid credentials or authentication context
      tags:
        - Auth
      security:
        - authAdminJWT: []
        - projectKey: []
  /auth/refresh:
    post:
      operationId: AuthController_refresh
      summary: Refresh authentication tokens
      description: Refresh access tokens using valid refresh token
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshTokenRequestDTO'
      responses:
        '200':
          description: New access token created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionAuthResponseDTO'
        '401':
          description: Invalid or expired refresh token
      tags:
        - Auth
  /files/entity-storage-url:
    post:
      operationId: FilesController_getEntityStorageUrl
      summary: Generate signed URL for entity storage
      description: >-
        Creates S3 signed URLs for uploading or downloading entity files.
        Supports both business and admin authentication flows.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityStorageUrlDTO'
      responses:
        '201':
          description: Signed URL generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSignedURLResponseDTO'
      tags:
        - Files
      security:
        - JWT: []
        - ProjectApiKey: []
  /chains/{chainId}:
    get:
      operationId: Web3ChainsController_getChainData
      summary: Get Web3 chain data by chain ID
      description: >-
        Retrieve comprehensive chain data including authentication JWT token
        valid for 30 days. Supports both mainnet and testnet chains.
      parameters:
        - name: chainId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Web3 chain data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChainDataDTO'
      tags:
        - Web3 Chains
      security:
        - projectKey: []
  /contracts:
    post:
      operationId: Web3ContractsController_createContract
      summary: Create a new Web3 contract (Admin)
      description: >-
        Create a new Web3 contract with administrative privileges. Requires
        tenant admin access. Replaces POST /contract
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Web3ContractCreateRequestDTO'
      responses:
        '200':
          description: Contract created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Web3ContractDTO'
      tags:
        - Contracts
      security:
        - tenantAdminJWT: []
info:
  title: PERS-api docs
  description: ''
  version: 2.0.2
  contact: {}
tags:
  - name: Tenants
    description: |-
      ## Tenant Management
          <div style="font-size: 14px; line-height: 1.5;">
            Tenant management for multi-tenant PERS loyalty platform. Each tenant represents a business or organization running their own reward program with dedicated data isolation and configuration.
          </div>
          **Core Features:**
          <br/>• **Multi-Tenant Architecture:** Complete data isolation between tenant organizations
          <br/>• **Tenant Configuration:** Custom settings, branding, and program rules per tenant  
          <br/>• **Admin Dashboard Access:** Comprehensive management interface for tenant administrators
          <br/>• **Data Security:** Highest level confidentiality and security per tenant environment
          <br/>• **API Integration:** Seamless integration with existing business systems
  - name: Admins
    description: |-
      ## Administrative Management
          <div style="font-size: 14px; line-height: 1.5;">
            Administrative user management for tenant administrators. Handles admin authentication, permissions, and tenant-level administrative operations with secure access controls.
          </div>
          **Admin Features:**
          <br/>• **Admin Authentication:** Secure admin login and session management
          <br/>• **Permission Management:** Role-based access control for administrative functions
          <br/>• **Tenant Administration:** Full tenant configuration and management capabilities
          <br/>• **Security Controls:** Enhanced security measures for administrative access
          <br/>• **Multi-Level Access:** Support for different administrative privilege levels
  - name: Tokens
    description: |-
      ## Token Management System
          <div style="font-size: 14px; line-height: 1.5;">
            Token system for PERS loyalty platform managing various token types including Credits, Rewards, and Status tokens. Provides comprehensive token lifecycle management from creation to redemption.
          </div>
          **Token Operations:**
          <br/>• **Token Creation:** Define custom token types with specific properties and rules
          <br/>• **Token Distribution:** Mint and distribute tokens to users through campaigns
          <br/>• **Balance Management:** Track token balances across user accounts  
          <br/>• **Token Transfer:** Enable token transfers between users when configured
          <br/>• **Token Burning:** Remove tokens from circulation for deflationary mechanics
          ![Token Module](https://s3.eu-west-1.amazonaws.com/pers.assets.prod/tenant/a0df6ebf-51cc-4c18-afcd-0de355c250dc_DemoApp_eXplorins/Documentation/Tokens_image.png)
  - name: Campaigns
    description: |-
      ## Core Campaign Management
          <div style="font-size: 14px; line-height: 1.5;">
            Core campaign CRUD operations with intelligent access detection. Handles campaign lifecycle management including creation, updates, activation, and querying with role-based access control.
          </div>
          **Campaign Operations:**
          <br/>• **Campaign Discovery:** Public browsing of active campaigns without authentication
          <br/>• **Advanced Filtering:** Query campaigns by tags, status, and custom criteria
          <br/>• **Lifecycle Management:** Full campaign CRUD with proper state transitions
          <br/>• **Environment Control:** Toggle campaigns between testnet and mainnet modes
          <br/>• **Access Intelligence:** Automatic privilege detection for appropriate data exposure
          ![Campaign Module](https://s3.eu-west-1.amazonaws.com/pers.assets.prod/tenant/a0df6ebf-51cc-4c18-afcd-0de355c250dc_DemoApp_eXplorins/Documentation/Campaign_image.png)
  - name: Campaign Tags
    description: |-
      ## Campaign Organization System  
          <div style="font-size: 14px; line-height: 1.5;">
            Campaign tagging system for organization and categorization. Enables efficient campaign discovery through tag-based filtering and provides comprehensive tag management.
          </div>
          **Tag Management:**
          <br/>• **Tag Discovery:** Browse all unique tags across campaign catalog  
          <br/>• **Campaign Tagging:** Associate multiple descriptive tags with campaigns
          <br/>• **Tag-Based Filtering:** Enhanced campaign search and discovery via tags
          <br/>• **Tag Administration:** Complete tag CRUD operations for administrators
          <br/>• **Organization Tools:** Categorize campaigns by business criteria and themes
  - name: Campaign Tokens
    description: |-
      ## Campaign Reward Configuration
          <div style="font-size: 14px; line-height: 1.5;">
            Token unit management for campaign reward distribution. Defines specific token rewards that users receive when campaign participation conditions are met.
          </div>
          **Reward Configuration:**
          <br/>• **Token Association:** Link specific token types and amounts to campaigns
          <br/>• **Reward Rules:** Define token distribution rules and conditions
          <br/>• **Multi-Token Support:** Configure multiple token types per campaign
          <br/>• **Reward Calculation:** Set fixed or variable token amounts based on actions
          <br/>• **Distribution Management:** Control how and when tokens are distributed to users
  - name: Campaign Triggers
    description: |-
      ## Campaign Activation System
          <div style="font-size: 14px; line-height: 1.5;">
            Campaign trigger system managing activation rules and eligibility conditions. Defines when and how campaigns activate including complex condition management for sophisticated campaign logic.
          </div>
          **Trigger Features:**
          <br/>• **Trigger Catalog:** Public browsing of available campaign activation triggers
          <br/>• **Condition Management:** Create complex trigger conditions with multiple criteria  
          <br/>• **Campaign Assignment:** Link triggers to campaigns for automated activation
          <br/>• **Eligibility Rules:** Define sophisticated user participation requirements
          <br/>• **Event-Based Activation:** Trigger campaigns based on user actions and external events
  - name: Campaign Engagements
    description: |-
      ## Business Relationship Management
          <div style="font-size: 14px; line-height: 1.5;">
            B2B engagement management for multi-business campaign relationships. Handles business partnerships and enterprise-level campaign participation in complex loyalty ecosystems.
          </div>
          **B2B Features:**
          <br/>• **Partner Integration:** Manage business-to-business campaign relationships  
          <br/>• **Enterprise Programs:** Support complex multi-business loyalty initiatives
          <br/>• **Engagement Tracking:** Monitor business participation and performance metrics
          <br/>• **Partnership Management:** Configure B2B reward sharing and attribution
          <br/>• **Cross-Business Rewards:** Enable rewards that span multiple business partners
  - name: Campaign Claims
    description: |-
      ## 🔥 BUSINESS CRITICAL: Financial Claims Processing
          <div style="font-size: 14px; line-height: 1.5; color: #d73527; font-weight: bold;">
            BUSINESS CRITICAL: Multi-level reward claim processing with comprehensive fraud prevention and audit trails. Handles actual reward distribution with full financial security and compliance features.
          </div>
          **Critical Security Features:**
          <br/>• **Multi-Level Access:** USER, BUSINESS, SYSTEM, ADMIN claim processing levels
          <br/>• **Fraud Prevention:** IP tracking and behavioral analysis for security
          <br/>• **Audit Compliance:** Complete transaction history for regulatory requirements  
          <br/>• **Financial Attribution:** User and business context preservation for accounting
          <br/>• **Claim Verification:** Multi-step verification process for high-value rewards
          <br/>
          **Access Levels:**
          <br/>• **USER:** Direct customer reward claims with user authentication
          <br/>• **BUSINESS:** B2B reward processing with business context attribution  
          <br/>• **SYSTEM:** Automated claims processing via secure API integration
          <br/>• **ADMIN:** Complete administrative oversight and manual claim processing
  - name: Redemptions
    description: |-
      ## Token Exchange System
          <div style="font-size: 14px; line-height: 1.5;">
            Token exchange system facilitating conversion between different token types and redemption for rewards. Provides flexible reward experiences through diverse redemption options.
          </div>
          **Redemption Features:**
          <br/>• **Token Exchange:** Convert between different token types with exchange rates
          <br/>• **Reward Catalog:** Browse available rewards for token redemption
          <br/>• **Exchange Rules:** Configure conversion rates and redemption requirements  
          <br/>• **Partner Ecosystem:** Redemption options across business partner networks
          <br/>• **Flexible Rewards:** Support for products, services, and digital rewards
          ![Redemption Module](https://s3.eu-west-1.amazonaws.com/pers.assets.prod/tenant/a0df6ebf-51cc-4c18-afcd-0de355c250dc_DemoApp_eXplorins/Documentation/Redemption_image.png)
  - name: Purchases
    description: |-
      ## Payment Processing System
          <div style="font-size: 14px; line-height: 1.5;">
            Secure payment processing for account balance top-ups through credit card payments. Provides secure financial transactions for premium features and account funding within the loyalty ecosystem.
          </div>
          **Payment Features:**
          <br/>• **Secure Payments:** Credit card processing with industry-standard security
          <br/>• **Balance Top-Up:** Add funds to user accounts for premium features
          <br/>• **Payment Methods:** Support for multiple payment providers and methods
          <br/>• **Transaction Security:** Encrypted payment data and fraud protection
          <br/>• **Account Integration:** Seamless integration with token and reward systems
          ![Purchase Module](https://s3.eu-west-1.amazonaws.com/pers.assets.prod/tenant/a0df6ebf-51cc-4c18-afcd-0de355c250dc_DemoApp_eXplorins/Documentation/Purchase_image.png)
  - name: Businesses
    description: |-
      ## Partner Ecosystem Management
          <div style="font-size: 14px; line-height: 1.5;">
            Business partner management for multi-stakeholder loyalty programs. Handles partner onboarding, collaboration frameworks, and performance tracking within the reward ecosystem.
          </div>
          **Partner Management:**
          <br/>• **Partner Onboarding:** Register and configure business partners in the ecosystem
          <br/>• **Collaboration Tools:** Facilitate joint campaigns and cross-partner rewards
          <br/>• **Performance Analytics:** Track partner engagement and contribution metrics  
          <br/>• **Incentive Structures:** Configure partner-specific reward and commission models
          <br/>• **Community Building:** Foster collaborative relationships between ecosystem partners
  - name: Transactions
    description: |-
      ## Transaction Management System  
          <div style="font-size: 14px; line-height: 1.5;">
            Comprehensive transaction management for credits and tokens with secure processing and real-time balance updates. Handles all financial operations within the loyalty platform.
          </div>
          **Transaction Operations:**
          <br/>• **Token Minting:** Create new tokens and add to user accounts
          <br/>• **Token Transfers:** Secure peer-to-peer token transfers between users
          <br/>• **Token Burning:** Remove tokens from circulation with proper audit trails
          <br/>• **Balance Queries:** Real-time balance checks across multiple token types  
          <br/>• **Transaction Authorization:** Verify user permissions and sufficient balances
          <br/>• **Transaction History:** Complete audit logs for all financial operations
  - name: Users
    description: |-
      ## User Account Management
          <div style="font-size: 14px; line-height: 1.5;">
            User account management and profile operations for loyalty platform participants. Handles user registration, authentication, profile management, and account lifecycle.
          </div>
          **User Operations:**
          <br/>• **Account Registration:** User signup and profile creation with verification
          <br/>• **Authentication:** Secure login and session management  
          <br/>• **Profile Management:** User profile updates and preference configuration
          <br/>• **Account Security:** Password management and two-factor authentication
          <br/>• **Privacy Controls:** Data management and privacy settings for users
  - name: Balances
    description: |-
      ## Account Balance Management
          <div style="font-size: 14px; line-height: 1.5;">
            Real-time balance tracking and management across all token types and user accounts. Provides comprehensive balance queries and balance-related operations.
          </div>
          **Balance Features:**  
          <br/>• **Multi-Token Balances:** Track balances across different token types per user
          <br/>• **Real-Time Updates:** Instant balance updates from all transaction sources
          <br/>• **Balance History:** Historical balance tracking and change audit trails
          <br/>• **Balance Queries:** Flexible balance lookup with filtering and aggregation
          <br/>• **Balance Notifications:** Alert systems for balance changes and thresholds
  - name: Files
    description: |-
      ## File Management System
          <div style="font-size: 14px; line-height: 1.5;">
            File upload and management system for platform assets including campaign images, user avatars, and document attachments with secure storage and access control.
          </div>
          **File Operations:**
          <br/>• **Secure Upload:** File upload with type validation and security scanning
          <br/>• **Asset Management:** Organize and manage platform media assets
          <br/>• **Access Control:** Role-based file access and sharing permissions
          <br/>• **CDN Integration:** Fast global file delivery through content delivery networks
          <br/>• **File Processing:** Automatic image resizing and format optimization
  - name: Web3 Chains
    description: |-
      ## Blockchain Network Management  
          <div style="font-size: 14px; line-height: 1.5;">
            Blockchain network configuration and management for multi-chain token operations. Handles network connections, chain switching, and blockchain-specific operations.
          </div>
          **Chain Operations:**
          <br/>• **Multi-Chain Support:** Connect to multiple blockchain networks simultaneously  
          <br/>• **Network Configuration:** Configure blockchain endpoints and network parameters
          <br/>• **Chain Switching:** Dynamic switching between different blockchain networks
          <br/>• **Network Status:** Real-time monitoring of blockchain network health and status
          <br/>• **Gas Management:** Optimize transaction costs across different networks
  - name: Contracts
    description: |-
      ## Smart Contract Management
          <div style="font-size: 14px; line-height: 1.5;">
            Smart contract deployment and interaction management for blockchain-based loyalty operations. Handles contract lifecycle and blockchain integration.
          </div>
          **Contract Operations:**
          <br/>• **Contract Deployment:** Deploy loyalty-related smart contracts to blockchain networks
          <br/>• **Contract Interaction:** Execute smart contract functions for token operations
          <br/>• **Contract Monitoring:** Track contract events and transaction confirmations  
          <br/>• **Contract Upgrades:** Manage contract versioning and upgrade procedures
          <br/>• **Multi-Chain Contracts:** Deploy and manage contracts across multiple blockchains
  - name: Auth
    description: |-
      ## Authentication & Authorization  
          <div style="font-size: 14px; line-height: 1.5;">
            Comprehensive authentication and authorization system supporting multiple access levels including users, businesses, admins, and system-level access with JWT-based security.
          </div>
          **Auth Features:**
          <br/>• **Multi-Level Access:** Support for USER, BUSINESS, ADMIN, SYSTEM authentication levels
          <br/>• **JWT Security:** JSON Web Token-based authentication with secure key management
          <br/>• **Role-Based Access:** Fine-grained permission system with role hierarchy  
          <br/>• **API Key Management:** Secure API key generation and validation for system integrations
          <br/>• **Session Management:** Secure session handling with automatic expiration and refresh
  - name: Root
    description: |-
      ## Platform Infrastructure  
          <div style="font-size: 14px; line-height: 1.5;">
            Core platform infrastructure endpoints including health checks, system status, and platform configuration. Provides essential system-level operations and monitoring.
          </div>
          **Infrastructure Operations:**
          <br/>• **Health Monitoring:** System health checks and status reporting
          <br/>• **Platform Status:** Real-time platform operational status
          <br/>• **Configuration Access:** System configuration and environment information
          <br/>• **Diagnostic Tools:** Platform diagnostics and troubleshooting endpoints
          <br/>• **System Integration:** Core infrastructure for system-level operations
  - name: Well-known
    description: |-
      ## Security Infrastructure
          <div style="font-size: 14px; line-height: 1.5;">
            JSON Web Key Set (JWKS) endpoints for JWT token verification. Provides public keys for secure authentication token validation across the platform ecosystem.
          </div>
          **Security Features:**
          <br/>• **JWKS Endpoints:** Standard JSON Web Key Set for JWT verification
          <br/>• **Public Key Distribution:** Secure distribution of verification keys
          <br/>• **Token Validation:** Enable third-party JWT token verification
          <br/>• **Security Standards:** Compliance with OAuth 2.0 and OpenID Connect
          <br/>• **Cross-Platform Auth:** Support for distributed authentication verification
  - name: webhooks
    description: |-
      ## Webhook Integration System
          <div style="font-size: 14px; line-height: 1.5;">
            Webhook proxy and integration system for external service notifications. Handles incoming webhook events and integrates with external platforms for real-time data synchronization.
          </div>
          **Webhook Features:**
          <br/>• **Webhook Proxy:** Secure proxy for external webhook integrations
          <br/>• **Event Processing:** Real-time processing of external service events
          <br/>• **Integration Management:** Manage connections with external platforms
          <br/>• **Security Validation:** Webhook signature verification and authentication
          <br/>• **Event Routing:** Intelligent routing of webhook events to appropriate handlers
servers:
  - url: https://api.pers.ninja/v2
components:
  securitySchemes:
    tenantAdminJWT:
      scheme: bearer
      bearerFormat: JWT
      type: http
    authUserJWT:
      scheme: bearer
      bearerFormat: JWT
      type: http
    authAdminJWT:
      scheme: bearer
      bearerFormat: JWT
      type: http
    projectKey:
      type: apiKey
      in: header
      name: x-project-key
      description: Project API key
    businessApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Business API key
  schemas:
    TokenMetadataDTO:
      type: object
      properties:
        imageUrl:
          type: string
          description: ' This is the URL to the image of the item. Can be just about any type of image (including SVGs, which will be cached into PNGs by OpenSea), IPFS or Arweave URLs or paths. We recommend using a minimum 3000 x 3000 image.'
        externalUrl:
          type: string
          description: This is the URL that will appear below the asset's image
        description:
          type: string
          description: A human-readable description of the item. Markdown is supported.
        name:
          type: string
          description: Name of the item.
        expiryDate:
          format: date-time
          type: string
          description: expiry date in case of an utility reward
        animationUrl:
          type: string
          description: >-
            A URL to a multi-media attachment for the item. The file extensions
            GLTF, GLB, WEBM, MP4, M4V, OGV, and OGG are supported, along with
            the audio-only extensions MP3, WAV, and OGA. Animation_url also
            supports HTML pages, allowing you to build rich experiences and
            interactive NFTs using JavaScript canvas, WebGL, and more. Scripts
            and relative paths within the HTML page are now supported. However,
            access to browser extensions is not supported.
        youtubeUrl:
          type: string
          description: A URL to a YouTube video (only used if animation_url is not provide
        creatorAccountAddress:
          type: string
          description: Creator Address
        previewUrl:
          type: string
          description: Preview Url
        id:
          type: string
          description: Token Metadata id
        animationWeb3StorageUrl:
          type: string
          description: web3 storage url for the animation file
        imageWeb3StorageUrl:
          type: string
          description: web3 storage url for the image
        web3StorageUrl:
          type: string
          description: Storage Url
        tokenMetadataIncrementalId:
          type: number
          description: Token Metadata Incremental Id
        isActive:
          type: boolean
          description: Is active
      required:
        - id
        - tokenMetadataIncrementalId
        - isActive
    TokenDTO:
      type: object
      properties:
        id:
          type: string
          description: Id of the token
        contractAddress:
          type: string
          description: Address of the token
        metadata:
          description: >-
            Metadata of the token, this is optional and can be null in case of
            Point token
          type: array
          items:
            $ref: '#/components/schemas/TokenMetadataDTO'
        abi:
          type: object
          description: >-
            this is the abi of the contract, this is the interface of the
            contract to interact with it
        chainId:
          type: number
          description: this is the chain id of the chain where the token is deployed
        abiUrl:
          type: object
          description: >-
            this is the url of the abi of the contract, to be used to fetch the
            abi of the contract
        name:
          type: string
          description: this is the name of the token contract
        symbol:
          type: string
          description: >-
            this is the symbol of the token contract, this is optional and can
            be null
        decimals:
          type: number
          description: >-
            this is the decimals of the token. This is optional and only used
            for ERC20 tokens (Points)
        isActive:
          type: boolean
          description: This can be used to enable or disable the token
        isGallery:
          type: boolean
          description: This can be used to enable or disable the token for gallery
        type:
          type: string
          description: This is the underlying web3 native type of the token contract
          enum:
            - ERC20
            - ERC1155
            - ERC721
      required:
        - id
        - contractAddress
        - abi
        - chainId
        - abiUrl
        - isActive
        - isGallery
        - type
    PurchaseTypeDTO:
      type: object
      properties:
        conversionRate:
          type: number
          description: Conversion Rate of the token
        currency:
          type: string
          description: Currency of the token
          enum:
            - eur
        id:
          type: number
          description: Purchase Type id
      required:
        - conversionRate
        - currency
        - id
    PurchaseTokenDTO:
      type: object
      properties:
        id:
          type: string
          description: Purchase Token id
        description:
          type: string
          description: Purchase Token description
        token:
          description: Token
          allOf:
            - $ref: '#/components/schemas/TokenDTO'
        contractTokenId:
          type: object
          description: optional contract token id
        purchaseType:
          description: Purchase Type
          allOf:
            - $ref: '#/components/schemas/PurchaseTypeDTO'
        isActive:
          type: boolean
          description: Purchase Token isActive
      required:
        - id
        - description
        - token
        - contractTokenId
        - purchaseType
        - isActive
    DonationTypeDTO:
      type: object
      properties:
        percentage:
          type: number
          description: Percentage of donation
        id:
          type: number
          description: Id of the donation type
      required:
        - percentage
        - id
    PaymentIntentCreateDTO:
      type: object
      properties:
        amount:
          type: number
          description: Amount in cents
        currency:
          type: string
          description: Currency
        receiptEmail:
          type: string
          description: Receipt Email
        description:
          type: string
          description: Description
      required:
        - amount
        - currency
        - receiptEmail
        - description
    PaymentIntentDTO:
      type: object
      properties:
        paymentClientSecret:
          type: object
          description: Payment Intent ClientSecrete to complete Stripe payment
        paymentIntentId:
          type: string
          description: Payment Intent Id
      required:
        - paymentClientSecret
        - paymentIntentId
    PurchaseCreateRequestDTO:
      type: object
      properties:
        quantity:
          type: number
          description: Quantity of tokens to purchase
        paymentIntentId:
          type: string
          description: Payment Intent Id
        purchaseTokenId:
          type: string
          description: Purchase Token id
        donationTypeId:
          type: number
          description: Donation Type
        donationAccountAddress:
          type: string
          description: Donation Account Address
      required:
        - quantity
        - paymentIntentId
        - purchaseTokenId
    WalletDTO:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the internal wallet
        ownerType:
          type: number
          description: Owner type for polymorphic ownership
          example: user
          enum:
            - USER: user
              BUSINESS: business
              TENANT: tenant
              SYSTEM: system
              EXTERNAL: external
        ownerId:
          type: string
          description: Owner ID for polymorphic ownership
          example: user_123
        walletManagementType:
          type: number
          description: Type of internal wallet
          enum:
            - CUSTODIAL: custodial
              NON_CUSTODIAL: non-custodial
        address:
          type: string
          description: CREATE2 generated address that can receive tokens
        chainId:
          type: number
          description: Blockchain network chain identifier
        status:
          type: number
          description: Current status of the wallet
          enum:
            - PENDING: pending
              ACTIVE: active
              SUSPENDED: suspended
              ARCHIVED: archived
        salt:
          type: string
          description: CREATE2 salt used for deterministic address generation
        ownerSigningAccountId:
          type: object
          description: ID of signing account that owns this internal wallet
          nullable: true
        tags:
          description: Tags associated with the wallet for categorization
          type: array
          items:
            type: string
        createdAt:
          format: date-time
          type: string
          description: Timestamp when the wallet was created
        updatedAt:
          format: date-time
          type: string
          description: Timestamp when the wallet was last updated
      required:
        - id
        - ownerType
        - ownerId
        - walletManagementType
        - address
        - chainId
        - status
        - salt
        - tags
        - createdAt
        - updatedAt
    UserDTO:
      type: object
      properties:
        id:
          type: string
        email:
          type: object
        firstName:
          type: object
          description: User first name
          nullable: true
        lastName:
          type: object
          description: User last name
          nullable: true
        externalId:
          type: object
          description: User external id
          nullable: true
        accountAddress:
          type: object
          description: User account address
          nullable: true
          deprecated: true
        instagramAccountId:
          type: object
          description: Instagram account id
          nullable: true
        googleAccountName:
          type: object
          description: Google account name
          nullable: true
        customData:
          type: object
          description: Custom data
        publicProfile:
          type: object
          description: Public profile data
          nullable: true
        isActive:
          type: boolean
          description: Is active
        currentSigningAccountId:
          type: object
          description: Current active signing account ID for external wallet operations
        wallets:
          description: >-
            User-owned counterfactual smart contract wallets that can receive
            tokens
          type: array
          items:
            $ref: '#/components/schemas/WalletDTO'
      required:
        - id
        - firstName
        - lastName
        - externalId
        - accountAddress
        - instagramAccountId
        - googleAccountName
        - customData
        - publicProfile
        - isActive
        - wallets
    BusinessTypeDTO:
      type: object
      properties:
        id:
          type: number
          description: Business type id
        name:
          type: string
          description: Business type name
          nullable: true
        description:
          type: string
          description: Business type description
          nullable: true
        code:
          type: string
          description: Business type code
          nullable: true
        iconUrl:
          type: string
          description: Business type icon url
          nullable: true
      required:
        - name
        - description
        - code
        - iconUrl
    BusinessDTO:
      type: object
      properties:
        id:
          type: string
          description: >-
            The id of the business, this is unique and will be used to identify
            the business.
        email:
          type: object
          description: >-
            The email of the business, this is unique and will be used to
            identify the business.
          nullable: true
        accountAddress:
          type: object
          description: >-
            The address of the business, this is the address that will be shown
            to the public.
          nullable: true
        businessLegalName:
          type: object
          description: >-
            The legal name of the business, this is the name that will be used
            for legal purposes.
          nullable: true
        displayName:
          type: object
          description: >-
            The display name of the business, this is the name that will be
            shown to the public.
          nullable: true
        description:
          type: object
          description: >-
            The description of the business, this is the description that will
            be shown to the public.
          nullable: true
        shortDescription:
          type: object
          description: >-
            The short description of the business, this is the description that
            will be shown to the public.
          nullable: true
        websiteUrl:
          type: object
          description: >-
            The website of the business, this is the website that will be shown
            to the public.
          nullable: true
        imageUrl:
          type: object
          description: >-
            The image of the business, this is the image that will be shown to
            the public.
          nullable: true
        streetAddress:
          type: object
          description: >-
            The address of the business, this is the address that will be shown
            to the public.
          nullable: true
        city:
          type: object
          description: >-
            The city of the business, this is the city that will be shown to the
            public.
          nullable: true
        postalCode:
          type: object
          description: >-
            The postal code of the business, this is the postal code that will
            be shown to the public.
          nullable: true
        coordsLatitude:
          type: object
          description: >-
            The latitude of the business, this is the latitude that will be
            shown to the public.
          nullable: true
        coordsLongitude:
          type: object
          description: >-
            The longitude of the business, this is the longitude that will be
            shown to the public.
          nullable: true
        businessType:
          description: >-
            The business type of the business, this is the business type that
            will be shown to the public.
          nullable: true
          allOf:
            - $ref: '#/components/schemas/BusinessTypeDTO'
        isActive:
          type: boolean
          description: >-
            The status of the business, this is the status that will be shown to
            the public.
        canMintToken:
          type: boolean
          description: >-
            The ability to mint token for the business, this is the ability that
            will be shown to the public.
        canChargeToken:
          type: boolean
          description: >-
            The ability to charge token for the business, this is the ability
            that will be shown to the public.
        canManageUsers:
          type: boolean
          description: >-
            The ability to manage users for the business, this is the ability
            that will be shown to the public.
        canReceiveDonation:
          type: boolean
          description: >-
            The ability to receive donation for the business, this is the
            ability that will be shown to the public.
      required:
        - id
        - email
        - accountAddress
        - businessLegalName
        - displayName
        - description
        - shortDescription
        - websiteUrl
        - imageUrl
        - streetAddress
        - city
        - postalCode
        - coordsLatitude
        - coordsLongitude
        - businessType
        - isActive
        - canMintToken
        - canChargeToken
        - canManageUsers
        - canReceiveDonation
    PurchaseCreateResponseDTO:
      type: object
      properties:
        id:
          type: string
          description: Purchase id
        stripePaymentIntentId:
          type: string
          description: Stripe Payment Intent id
        status:
          type: object
          description: Purchase status
        amount:
          type: number
          description: Amount to pay in cents
        currency:
          type: string
          description: Currency
          enum:
            - eur
        quantity:
          type: number
          description: Quantity of tokens to purchase
        purchaseToken:
          description: Purchase Token
          allOf:
            - $ref: '#/components/schemas/PurchaseTokenDTO'
        user:
          description: User
          allOf:
            - $ref: '#/components/schemas/UserDTO'
        business:
          description: Business
          allOf:
            - $ref: '#/components/schemas/BusinessDTO'
        donationAccountAddress:
          type: string
          description: Donation Account Address
        donationType:
          description: Donation Type
          allOf:
            - $ref: '#/components/schemas/DonationTypeDTO'
        createdAt:
          format: date-time
          type: string
          description: create date
        updatedAt:
          format: date-time
          type: string
          description: update date
        paymentClientSecret:
          type: object
          description: Stripe payment intent client secret
      required:
        - id
        - stripePaymentIntentId
        - status
        - amount
        - currency
        - quantity
        - purchaseToken
        - user
        - business
        - paymentClientSecret
    PurchaseDTO:
      type: object
      properties:
        id:
          type: string
          description: Purchase id
        stripePaymentIntentId:
          type: string
          description: Stripe Payment Intent id
        status:
          type: object
          description: Purchase status
        amount:
          type: number
          description: Amount to pay in cents
        currency:
          type: string
          description: Currency
          enum:
            - eur
        quantity:
          type: number
          description: Quantity of tokens to purchase
        purchaseToken:
          description: Purchase Token
          allOf:
            - $ref: '#/components/schemas/PurchaseTokenDTO'
        user:
          description: User
          allOf:
            - $ref: '#/components/schemas/UserDTO'
        business:
          description: Business
          allOf:
            - $ref: '#/components/schemas/BusinessDTO'
        donationAccountAddress:
          type: string
          description: Donation Account Address
        donationType:
          description: Donation Type
          allOf:
            - $ref: '#/components/schemas/DonationTypeDTO'
        createdAt:
          format: date-time
          type: string
          description: create date
        updatedAt:
          format: date-time
          type: string
          description: update date
      required:
        - id
        - stripePaymentIntentId
        - status
        - amount
        - currency
        - quantity
        - purchaseToken
        - user
        - business
    PurchaseTokenCreateRequestDTO:
      type: object
      properties:
        tokenId:
          type: string
          description: Token id
        description:
          type: string
          description: Purchase Token description
        purchaseTypeId:
          type: number
          description: Purchase Type id
      required:
        - tokenId
        - description
        - purchaseTypeId
    PurchaseTokenUpdateRequestDTO:
      type: object
      properties:
        description:
          type: string
          description: Purchase Token description
        isActive:
          type: boolean
          description: Purchase Token isActive
    PurchaseTypeCreateRequestDTO:
      type: object
      properties:
        conversionRate:
          type: number
          description: Conversion Rate of the token
        currency:
          type: string
          description: Currency of the token
          enum:
            - eur
      required:
        - conversionRate
        - currency
    CampaignTriggerConditionDTO:
      type: object
      properties:
        conditionType:
          type: string
          description: Trigger condition type
          enum:
            - EQUALS
            - NOT_EQUALS
            - GREATER_THAN
            - LESS_THAN
            - CONTAINS
            - IS_PART_OF
        value:
          type: object
          description: Trigger condition value
        key:
          type: string
          description: Trigger condition key
        id:
          type: string
      required:
        - conditionType
        - value
        - key
        - id
    CampaignTriggerDTO:
      type: object
      properties:
        name:
          type: string
          description: Campaign trigger name
        description:
          type: string
          description: Campaign trigger description
        maxPerDay:
          type: number
          nullable: true
          description: Campaign trigger max per day
        maxPerUser:
          type: number
          nullable: true
          description: Campaign trigger max per user
        minCooldownSeconds:
          type: number
          nullable: true
          description: Campaign trigger min cooldown seconds
        maxGeoDistanceInMeters:
          type: number
          nullable: true
          description: Campaign trigger max geo distance to Business in meters
        requiredUserInfo:
          type: string
          enum:
            - id
            - email
            - instagramAccountId
            - externalId
            - firstName
            - lastName
            - accountAddress
            - publicProfile
            - customData
            - isActive
            - currentSigningAccountId
          description: Campaign trigger required user info
        triggerType:
          type: string
          description: Campaign trigger type
          enum:
            - CLAIM_BY_USER
            - CLAIM_BY_SYSTEM
            - CLAIM_BY_BUSINESS
        maxMultiplier:
          type: number
          nullable: true
          description: Campaign trigger max multiplier
        completionThreshold:
          type: number
          nullable: true
          description: >-
            Campaign trigger completion threshold. This indicates the number of
            completions required before the reward is granted
        id:
          type: string
          description: Campaign trigger id
        conditions:
          description: Campaign trigger conditions
          type: array
          items:
            $ref: '#/components/schemas/CampaignTriggerConditionDTO'
      required:
        - name
        - id
        - conditions
    TokenUnitDTO:
      type: object
      properties:
        id:
          type: string
          description: Token unit id
        token:
          description: TokenDTO object
          allOf:
            - $ref: '#/components/schemas/TokenDTO'
        tokenMetadataIncrementalId:
          type: number
          nullable: true
          description: >-
            token metadata incremental id for the token unit, this is used to
            identify the specific token metadata that should be minted 
        amount:
          type: number
          description: >-
            Token unit amount is the amount of tokens that the user will receive
            when aquiring the token unit
        maxAmount:
          type: number
          nullable: true
          description: >-
            Token unit max amount, this is the maximum amount of tokens that the
            user can receive when aquiring the token unit. This is relevant e.g.
            in campaigns where a user may receive token units per revenue spent
            etc
      required:
        - id
        - token
        - amount
    CampaignBusinessEngagementDTO:
      type: object
      properties:
        id:
          type: string
          description: id
        shortDescription:
          type: number
          nullable: true
          description: >-
            A short description of the business engagement with indications what
            to do etc
        businesses:
          description: businesses
          type: array
          items:
            $ref: '#/components/schemas/BusinessDTO'
        campaignId:
          type: string
          description: Campaign id
        maxPerBusiness:
          type: number
          nullable: true
          description: >-
            max per business, the maximum number of times a user can engage with
            the buisness in the campaign
        maxPerDay:
          type: number
          nullable: true
          description: >-
            max per day, the maximum number of times a user can engage with the
            buisness in the campaign per day
        externalUrl:
          type: string
          nullable: true
          description: >-
            The external URL for the business engagement, e.g. a link to a
            website or app
      required:
        - id
        - shortDescription
        - businesses
        - campaignId
        - maxPerBusiness
        - maxPerDay
        - externalUrl
    CampaignDTO:
      type: object
      properties:
        name:
          type: string
          description: Campaign name
          nullable: true
        description:
          type: string
          description: Campaign description
          nullable: true
        beneficiaryAccountAddress:
          type: string
          description: Campaign beneficiary account address
          nullable: true
        startDate:
          format: date-time
          type: string
          description: Campaign start date, default is the current date
          nullable: true
        endDate:
          format: date-time
          type: string
          description: Campaign end date
          nullable: true
        imageUrl:
          type: string
          description: img url
          nullable: true
        externalUrl:
          type: string
          description: Campaign url
          nullable: true
        id:
          type: string
          description: Campaign id
        isActive:
          type: boolean
          description: Campaign isActive
          default: false
        isTestnet:
          type: boolean
          description: >-
            Campaign isTestnet, this means that the campaign is running on
            testnet, not mainnet
          default: false
        trigger:
          description: >-
            Campaign trigger: what triggers the campaign, and what are the
            conditions for the trigger to be activated
          nullable: true
          allOf:
            - $ref: '#/components/schemas/CampaignTriggerDTO'
        tokenUnits:
          type: array
          items:
            description: 'Campaign reward: what are the rewards'
            type: array
            items:
              $ref: '#/components/schemas/TokenUnitDTO'
        businessEngagements:
          description: 'Campaign businesses: what businesses are involved in the campaign'
          type: array
          items:
            $ref: '#/components/schemas/CampaignBusinessEngagementDTO'
        createdAt:
          format: date-time
          type: string
          description: create date
          default: '2025-10-22T19:05:50.493Z'
        updatedAt:
          format: date-time
          type: string
          description: update date
          nullable: true
          default: null
        order:
          type: number
          description: Campaign order
          default: 1
        tags:
          description: Campaign tags
          default: []
          type: array
          items:
            type: string
        countryCodeRestrictions:
          type: object
          description: >-
            Country code restrictions as an array of strings (e.g., ["NOT_ES",
            "FR"])
          example:
            - NOT_ES
            - FR
      required:
        - name
        - description
        - beneficiaryAccountAddress
        - startDate
        - endDate
        - imageUrl
        - externalUrl
        - id
        - isActive
        - trigger
        - tokenUnits
        - businessEngagements
        - createdAt
        - updatedAt
        - order
        - tags
    CampaignCreateRequestDTO:
      type: object
      properties:
        name:
          type: string
          description: Campaign name
        description:
          type: string
          description: Campaign description
          nullable: true
        beneficiaryAccountAddress:
          type: string
          description: Campaign beneficiary account address
          nullable: true
        startDate:
          format: date-time
          type: string
          description: Campaign start date, default is the current date
          nullable: true
        endDate:
          format: date-time
          type: string
          description: Campaign end date
          nullable: true
        imageUrl:
          type: string
          description: img url
          nullable: true
        externalUrl:
          type: string
          description: Campaign url
          nullable: true
        order:
          type: number
          description: 'Campaign order '
          default: false
        countryCodeRestrictions:
          type: object
          description: >-
            Country code restrictions as an array of strings (e.g., ["NOT_ES",
            "FR"])
          example:
            - NOT_ES
            - FR
      required:
        - name
    AddTagsRequestDTO:
      type: object
      properties:
        tags:
          description: List of tags to add to campaign
          example:
            - summer
            - discount
            - limited-time
          type: array
          items:
            type: string
      required:
        - tags
    TokenUnitCreateRequestDTO:
      type: object
      properties:
        tokenId:
          type: string
          description: Token id
        tokenMetadataIncrementalId:
          type: number
          description: >-
            token metadata incremental id for the token unit, this is used to
            identify the specific token metadata that should be minted 
        amount:
          type: number
          description: >-
            Token unit amount is the amount of tokens that the user will receive
            when aquiring the token unit
        maxAmount:
          type: number
          description: >-
            Token unit max amount, this is the maximum amount of tokens that the
            user can receive when aquiring the token unit. This is relevant e.g.
            in campaigns where a user may receive token units per revenue spent
            etc
      required:
        - tokenId
        - amount
    CampaignTriggerCreateRequestDTO:
      type: object
      properties:
        name:
          type: string
          description: Campaign trigger name
        description:
          type: string
          description: Campaign trigger description
        maxPerDay:
          type: number
          nullable: true
          description: Campaign trigger max per day
        maxPerUser:
          type: number
          nullable: true
          description: Campaign trigger max per user
        minCooldownSeconds:
          type: number
          nullable: true
          description: Campaign trigger min cooldown seconds
        maxGeoDistanceInMeters:
          type: number
          nullable: true
          description: Campaign trigger max geo distance to Business in meters
        requiredUserInfo:
          type: string
          enum:
            - id
            - email
            - instagramAccountId
            - externalId
            - firstName
            - lastName
            - accountAddress
            - publicProfile
            - customData
            - isActive
            - currentSigningAccountId
          description: Campaign trigger required user info
        triggerType:
          type: string
          description: Campaign trigger type
          enum:
            - CLAIM_BY_USER
            - CLAIM_BY_SYSTEM
            - CLAIM_BY_BUSINESS
        maxMultiplier:
          type: number
          nullable: true
          description: Campaign trigger max multiplier
        completionThreshold:
          type: number
          nullable: true
          description: >-
            Campaign trigger completion threshold. This indicates the number of
            completions required before the reward is granted
      required:
        - name
    CampaignTriggerConditionCreateRequestDTO:
      type: object
      properties:
        conditionType:
          type: string
          description: Trigger condition type
          enum:
            - EQUALS
            - NOT_EQUALS
            - GREATER_THAN
            - LESS_THAN
            - CONTAINS
            - IS_PART_OF
        value:
          type: object
          description: Trigger condition value
        key:
          type: string
          description: Trigger condition key
      required:
        - conditionType
        - value
        - key
    CampaignBusinessEngagementCreateRequestDTO:
      type: object
      properties:
        businessIds:
          description: The business ids to engage with
          type: array
          items:
            type: string
        shortDescription:
          type: string
          description: >-
            A short description of the business engagement, with indications
            what to do etc
        maxPerBusiness:
          type: number
          description: max per user at the business
        maxPerDay:
          type: number
          description: >-
            max per day, the maximum number of times a user can engage with the
            buisness in the campaign per day
        externalUrl:
          type: string
          description: >-
            The external URL for the business engagement, e.g. a link to a
            website or app
      required:
        - businessIds
    CampaignClaimBusinessRequestDTO:
      type: object
      properties:
        campaignId:
          type: string
          description: The campaign id
        conditionsData:
          type: object
          description: The campaign condition data
        multiplier:
          type: number
          description: >-
            The campaign multiplier that will be applied to the reward. Default
            is 1.0
        businessId:
          type: string
          description: Business identifier
        latitude:
          type: number
          description: geolocation latitude
        longitude:
          type: number
          description: geolocation longitude
        userIdentifier:
          type: string
          description: The user identifier
        startDate:
          format: date-time
          type: string
          description: The start date of the claim
        endDate:
          format: date-time
          type: string
          description: The end date of the claim
        id:
          type: string
          description: The id of the user
        email:
          type: string
          description: The email of the user
        instagramAccountId:
          type: string
          description: The instagramAccountId of the user
        externalId:
          type: string
          description: The externalId of the user
      required:
        - campaignId
    CampaignUserClaimDTO:
      type: object
      properties:
        id:
          type: string
          description: The id of the campaign user claim
        createdAt:
          type: object
          description: The date the campaign user claim was created
        user:
          description: User
          allOf:
            - $ref: '#/components/schemas/UserDTO'
        campaign:
          description: The campaign that the user is claiming
          allOf:
            - $ref: '#/components/schemas/CampaignDTO'
        userCountryCode:
          type: string
          description: Country code of the user claiming the campaign
          nullable: true
        business:
          description: The business that the user claimed the campaign for
          allOf:
            - $ref: '#/components/schemas/BusinessDTO'
      required:
        - id
        - createdAt
        - user
        - campaign
        - userCountryCode
    CampaignClaimRequestDTO:
      type: object
      properties:
        campaignId:
          type: string
          description: The campaign id
        conditionsData:
          type: object
          description: The campaign condition data
        multiplier:
          type: number
          description: >-
            The campaign multiplier that will be applied to the reward. Default
            is 1.0
        businessId:
          type: string
          description: Business identifier
        latitude:
          type: number
          description: geolocation latitude
        longitude:
          type: number
          description: geolocation longitude
      required:
        - campaignId
    RedemptionTypeDTO:
      type: object
      properties:
        name:
          type: string
          description: Redemption type name
        description:
          type: string
          description: Redemption type description
        imageUrl:
          type: string
          description: Redemption type image url
        id:
          type: number
          description: Redemption type id
      required:
        - name
        - id
    UserStatusTypeDTO:
      type: object
      properties:
        name:
          type: string
          description: User Status Type name
        description:
          type: string
          description: User Status Type description
        minTokenBalance:
          type: number
          description: User Status Type eligible Token Addresses
        discountPercentage:
          type: number
          description: User Status Type discount Rate in percentage
        imageUrl:
          type: string
          description: User Status Type image Url
        id:
          type: number
          description: User Status Type id
        eligibleTokenAddresses:
          description: User Status Type eligible Token Addresses
          type: array
          items:
            type: string
      required:
        - name
        - minTokenBalance
        - discountPercentage
        - id
        - eligibleTokenAddresses
    RedemptionDTO:
      type: object
      properties:
        id:
          type: string
          description: Redemption id
        description:
          type: string
          description: Description of the redemption
          nullable: true
        name:
          type: string
          description: Name of the redemption
          nullable: true
        imageUrl:
          type: string
          description: Image url of the redemption
          nullable: true
        isActive:
          type: boolean
          description: Redemptio is active
        creditTokenAmount:
          type: number
          description: The amount of credit tokens needed to redeem the redemption tokens
        type:
          description: The redemption type
          nullable: true
          allOf:
            - $ref: '#/components/schemas/RedemptionTypeDTO'
        tokenUnits:
          description: The redemption tokens to be redeemed
          type: array
          items:
            $ref: '#/components/schemas/TokenUnitDTO'
        maxTotalSupply:
          type: number
          nullable: true
          description: The maximum total supply of the redemption
        order:
          type: number
          nullable: true
          description: The order of the redemption
        availableSupply:
          type: number
          nullable: true
          description: The available supply of the redemption
        maxPerUser:
          type: object
          description: The maximum redemption per user
        minUserStatusType:
          description: The minimum user status type to redeem the redemption
          nullable: true
          allOf:
            - $ref: '#/components/schemas/UserStatusTypeDTO'
        countryCodeRestrictions:
          type: object
          description: >-
            Country code restrictions as an array of strings (e.g., ["NOT_ES",
            "FR"])
          example:
            - NOT_ES
            - FR
        tags:
          description: Redemption tags
          default: []
          type: array
          items:
            type: string
      required:
        - id
        - description
        - name
        - imageUrl
        - isActive
        - creditTokenAmount
        - type
        - tokenUnits
        - maxTotalSupply
        - order
        - maxPerUser
        - minUserStatusType
        - tags
    TransactionDTO:
      type: object
      properties:
        amount:
          type: number
          description: Transaction amount
        id:
          type: string
          description: Transaction id
        tokenAddress:
          type: string
          description: Transaction token address
        contractTokenId:
          type: object
          description: >-
            Transaction token contract id, this is the blockchain contract id of
            the token
          nullable: true
        tokenType:
          type: string
          description: Transaction token type
        senderAddress:
          type: string
          description: Sender address
        recipientAddress:
          type: object
          description: Recipient address
        transactionHash:
          type: object
          description: Transaction hash
        type:
          type: string
          description: Transaction type
          enum:
            - MINT
            - TRANSFER
            - BURN
        triggerProcessType:
          type: string
          description: Trigger process type
          enum:
            - PURCHASE
            - SPEND
            - TRANSFER
            - EARN
            - CAMPAIGN_USER_CLAIM
            - CAMPAIGN_SYSTEM_CLAIM
            - CAMPAIGN_BUSINESS_CLAIM
            - REDEMPTION_SPEND
            - REDEMPTION_RECEIVE
            - MIGRATION
            - ADMIN_TRIGGERED
        triggerProcessId:
          type: object
          description: >-
            Trigger process id, this is the id of the entity that triggered the
            transaction if applicable (e.g. CampaignUserClaim id)
        status:
          type: string
          description: Transaction status
          enum:
            - created
            - processing
            - pending_signature
            - broadcasted
            - succeeded
            - failed
        createdAt:
          type: object
          description: create date
        updatedAt:
          type: object
          description: update date
        tenantId:
          type: string
          description: Tenant ID for multi-tenant isolation
        chainId:
          type: number
          description: Blockchain chain ID
        senderId:
          type: object
          description: Sender entity ID (polymorphic reference)
          nullable: true
        senderOwnerType:
          type: string
          description: Sender entity type (user, business, system etc.)
          nullable: true
          enum:
            - user
            - business
            - tenant
            - system
            - external
        recipientId:
          type: object
          description: Recipient entity ID (polymorphic reference)
          nullable: true
        recipientOwnerType:
          type: string
          description: Recipient entity type (user, Business, system, etc.)
          nullable: true
          enum:
            - user
            - business
            - tenant
            - system
            - external
      required:
        - amount
        - id
        - tokenAddress
        - contractTokenId
        - tokenType
        - senderAddress
        - recipientAddress
        - transactionHash
        - type
        - triggerProcessType
        - triggerProcessId
        - status
        - createdAt
        - updatedAt
        - tenantId
        - chainId
        - senderId
        - senderOwnerType
        - recipientId
        - recipientOwnerType
    RedemptionUserRedeemDetailedDTO:
      type: object
      properties:
        id:
          type: string
          description: The id of the redemption user redeem
        userId:
          type: string
          description: The user id that is claiming the redemption
        redemptionId:
          type: string
          description: The redemption that the user is redeeming
        transactionIds:
          description: >-
            The transaction ids that resulted from the user redeeming the
            redemption
          type: array
          items:
            type: string
        userCountryCode:
          type: string
          description: The country code of the user redeeming the redemption
          nullable: true
        transactions:
          type: array
          items:
            description: >-
              The transactions that resulted from the user redeeming the
              redemption
            type: array
            items:
              $ref: '#/components/schemas/TransactionDTO'
      required:
        - id
        - userId
        - redemptionId
        - transactionIds
        - userCountryCode
        - transactions
    RedemptionUserRedeemDTO:
      type: object
      properties:
        id:
          type: string
          description: The id of the redemption user redeem
        userId:
          type: string
          description: The user id that is claiming the redemption
        redemptionId:
          type: string
          description: The redemption that the user is redeeming
        transactionIds:
          description: >-
            The transaction ids that resulted from the user redeeming the
            redemption
          type: array
          items:
            type: string
        userCountryCode:
          type: string
          description: The country code of the user redeeming the redemption
          nullable: true
      required:
        - id
        - userId
        - redemptionId
        - transactionIds
        - userCountryCode
    RedemptionCreateRequestDTO:
      type: object
      properties:
        creditTokenAmount:
          type: number
          description: The amount of credit tokens needed to redeem the redemption tokens
        description:
          type: string
          description: Description of the redemption
          nullable: true
        name:
          type: string
          description: Name of the redemption
        imageUrl:
          type: string
          description: Image url of the redemption
          nullable: true
        redemptionTypeId:
          type: number
          description: Redemption type id
          nullable: true
        minUserStatusTypeId:
          type: number
          description: min user status type id to redeem the redemption
          nullable: true
        maxTotalSupply:
          type: number
          description: The maximum total supply of the redemption
          nullable: true
        order:
          type: number
          description: The order of the redemption
          nullable: true
        maxPerUser:
          type: number
          description: The maximum redemption per user
          nullable: true
        countryCodeRestrictions:
          description: >-
            Country code restrictions as an array of strings (e.g., ["NOT_ES",
            "FR"])
          example:
            - NOT_ES
            - FR
          nullable: true
          type: array
          items:
            type: string
    RedemptionTypeCreateRequestDTO:
      type: object
      properties:
        name:
          type: string
          description: Redemption type name
        description:
          type: string
          description: Redemption type description
        imageUrl:
          type: string
          description: Redemption type image url
      required:
        - name
    TokenBalanceDTO:
      type: object
      properties:
        contractAddress:
          type: string
        chainId:
          type: number
        balance:
          type: number
        tokenName:
          type: string
        tokenSymbol:
          type: string
        tokenType:
          type: string
        tokenId:
          type: string
          nullable: true
        metadataUri:
          type: string
          nullable: true
      required:
        - contractAddress
        - chainId
        - balance
        - tokenType
        - tokenId
        - metadataUri
    AccountTokenBalancesDTO:
      type: object
      properties:
        accountAddress:
          type: string
        tokenBalances:
          type: array
          items:
            $ref: '#/components/schemas/TokenBalanceDTO'
      required:
        - accountAddress
        - tokenBalances
    UserTokenBalancesDTO:
      type: object
      properties:
        id:
          type: string
        email:
          type: object
        firstName:
          type: object
          description: User first name
          nullable: true
        lastName:
          type: object
          description: User last name
          nullable: true
        externalId:
          type: object
          description: User external id
          nullable: true
        accountAddress:
          type: object
          description: User account address
          nullable: true
          deprecated: true
        instagramAccountId:
          type: object
          description: Instagram account id
          nullable: true
        googleAccountName:
          type: object
          description: Google account name
          nullable: true
        customData:
          type: object
          description: Custom data
        publicProfile:
          type: object
          description: Public profile data
          nullable: true
        isActive:
          type: boolean
          description: Is active
        currentSigningAccountId:
          type: object
          description: Current active signing account ID for external wallet operations
        wallets:
          description: >-
            User-owned counterfactual smart contract wallets that can receive
            tokens
          type: array
          items:
            $ref: '#/components/schemas/WalletDTO'
        tokenBalances:
          type: array
          items:
            $ref: '#/components/schemas/AccountTokenBalancesDTO'
      required:
        - id
        - firstName
        - lastName
        - externalId
        - accountAddress
        - instagramAccountId
        - googleAccountName
        - customData
        - publicProfile
        - isActive
        - wallets
        - tokenBalances
    UserCreateRequestDTO:
      type: object
      properties:
        email:
          type: string
        instagramAccountId:
          type: string
          description: User Instagram account id
        googleAccountName:
          type: string
          description: User Google account name
        firstName:
          type: string
          description: User first name
        lastName:
          type: string
          description: User last name
        externalId:
          type: string
          description: User external id
        customData:
          type: object
          description: Custom data
        publicProfile:
          type: object
          description: Public profile data
        isActive:
          type: boolean
          description: User active status
    PublicUserDTO:
      type: object
      properties:
        id:
          type: string
        publicProfile:
          type: object
          description: Public profile data
      required:
        - id
        - publicProfile
    UserStatusTypeCreateRequestDTO:
      type: object
      properties:
        name:
          type: string
          description: User Status Type name
        description:
          type: string
          description: User Status Type description
        minTokenBalance:
          type: number
          description: User Status Type eligible Token Addresses
        discountPercentage:
          type: number
          description: User Status Type discount Rate in percentage
        imageUrl:
          type: string
          description: User Status Type image Url
      required:
        - name
        - minTokenBalance
        - discountPercentage
    UrlRequestDTO:
      type: object
      properties:
        url:
          type: string
          example: https://example.com/user-data
      required:
        - url
    BusinessTypeCreateRequestDTO:
      type: object
      properties:
        name:
          type: string
          description: Business type name
        description:
          type: string
          description: Business type description
        code:
          type: string
          description: Business type code
        iconUrl:
          type: string
          description: Business type icon url
      required:
        - name
        - description
    BusinessTokenBalancesDTO:
      type: object
      properties:
        id:
          type: string
          description: >-
            The id of the business, this is unique and will be used to identify
            the business.
        email:
          type: object
          description: >-
            The email of the business, this is unique and will be used to
            identify the business.
          nullable: true
        accountAddress:
          type: object
          description: >-
            The address of the business, this is the address that will be shown
            to the public.
          nullable: true
        businessLegalName:
          type: object
          description: >-
            The legal name of the business, this is the name that will be used
            for legal purposes.
          nullable: true
        displayName:
          type: object
          description: >-
            The display name of the business, this is the name that will be
            shown to the public.
          nullable: true
        description:
          type: object
          description: >-
            The description of the business, this is the description that will
            be shown to the public.
          nullable: true
        shortDescription:
          type: object
          description: >-
            The short description of the business, this is the description that
            will be shown to the public.
          nullable: true
        websiteUrl:
          type: object
          description: >-
            The website of the business, this is the website that will be shown
            to the public.
          nullable: true
        imageUrl:
          type: object
          description: >-
            The image of the business, this is the image that will be shown to
            the public.
          nullable: true
        streetAddress:
          type: object
          description: >-
            The address of the business, this is the address that will be shown
            to the public.
          nullable: true
        city:
          type: object
          description: >-
            The city of the business, this is the city that will be shown to the
            public.
          nullable: true
        postalCode:
          type: object
          description: >-
            The postal code of the business, this is the postal code that will
            be shown to the public.
          nullable: true
        coordsLatitude:
          type: object
          description: >-
            The latitude of the business, this is the latitude that will be
            shown to the public.
          nullable: true
        coordsLongitude:
          type: object
          description: >-
            The longitude of the business, this is the longitude that will be
            shown to the public.
          nullable: true
        businessType:
          description: >-
            The business type of the business, this is the business type that
            will be shown to the public.
          nullable: true
          allOf:
            - $ref: '#/components/schemas/BusinessTypeDTO'
        isActive:
          type: boolean
          description: >-
            The status of the business, this is the status that will be shown to
            the public.
        canMintToken:
          type: boolean
          description: >-
            The ability to mint token for the business, this is the ability that
            will be shown to the public.
        canChargeToken:
          type: boolean
          description: >-
            The ability to charge token for the business, this is the ability
            that will be shown to the public.
        canManageUsers:
          type: boolean
          description: >-
            The ability to manage users for the business, this is the ability
            that will be shown to the public.
        canReceiveDonation:
          type: boolean
          description: >-
            The ability to receive donation for the business, this is the
            ability that will be shown to the public.
        tokenBalances:
          description: >-
            The token balances of the business, this is the token balances that
            will be shown to the public.
          type: array
          items:
            $ref: '#/components/schemas/TokenBalanceDTO'
      required:
        - id
        - email
        - accountAddress
        - businessLegalName
        - displayName
        - description
        - shortDescription
        - websiteUrl
        - imageUrl
        - streetAddress
        - city
        - postalCode
        - coordsLatitude
        - coordsLongitude
        - businessType
        - isActive
        - canMintToken
        - canChargeToken
        - canManageUsers
        - canReceiveDonation
        - tokenBalances
    BusinessCreateRequestDTO:
      type: object
      properties:
        email:
          type: string
          description: >-
            The email of the business, this is unique and will be used to
            identify the business.
        businessLegalName:
          type: string
          description: >-
            The legal name of the business, this is the name that will be used
            for legal purposes.
        displayName:
          type: string
          description: >-
            The display name of the business, this is the name that will be
            shown to the public.
        description:
          type: string
          description: >-
            The description of the business, this is the description that will
            be shown to the public.
        shortDescription:
          type: string
          description: >-
            The short description of the business, this is the description that
            will be shown to the public.
        websiteUrl:
          type: string
          description: >-
            The website of the business, this is the website that will be shown
            to the public.
        imageUrl:
          type: string
          description: >-
            The image of the business, this is the image that will be shown to
            the public.
        streetAddress:
          type: string
          description: >-
            The address of the business, this is the address that will be shown
            to the public.
        city:
          type: string
          description: >-
            The city of the business, this is the city that will be shown to the
            public.
        postalCode:
          type: string
          description: >-
            The postal code of the business, this is the postal code that will
            be shown to the public.
        coordsLatitude:
          type: number
          description: >-
            The latitude of the business, this is the latitude that will be
            shown to the public.
        coordsLongitude:
          type: number
          description: >-
            The longitude of the business, this is the longitude that will be
            shown to the public
        businessTypeId:
          type: number
          description: >-
            The business type of the business, this is the business type that
            will be shown to the public.
    BusinessApiKeyDTO:
      type: object
      properties:
        id:
          type: string
          description: >-
            The id of the business, this is unique and will be used to identify
            the business.
        email:
          type: object
          description: >-
            The email of the business, this is unique and will be used to
            identify the business.
          nullable: true
        accountAddress:
          type: object
          description: >-
            The address of the business, this is the address that will be shown
            to the public.
          nullable: true
        businessLegalName:
          type: object
          description: >-
            The legal name of the business, this is the name that will be used
            for legal purposes.
          nullable: true
        displayName:
          type: object
          description: >-
            The display name of the business, this is the name that will be
            shown to the public.
          nullable: true
        description:
          type: object
          description: >-
            The description of the business, this is the description that will
            be shown to the public.
          nullable: true
        shortDescription:
          type: object
          description: >-
            The short description of the business, this is the description that
            will be shown to the public.
          nullable: true
        websiteUrl:
          type: object
          description: >-
            The website of the business, this is the website that will be shown
            to the public.
          nullable: true
        imageUrl:
          type: object
          description: >-
            The image of the business, this is the image that will be shown to
            the public.
          nullable: true
        streetAddress:
          type: object
          description: >-
            The address of the business, this is the address that will be shown
            to the public.
          nullable: true
        city:
          type: object
          description: >-
            The city of the business, this is the city that will be shown to the
            public.
          nullable: true
        postalCode:
          type: object
          description: >-
            The postal code of the business, this is the postal code that will
            be shown to the public.
          nullable: true
        coordsLatitude:
          type: object
          description: >-
            The latitude of the business, this is the latitude that will be
            shown to the public.
          nullable: true
        coordsLongitude:
          type: object
          description: >-
            The longitude of the business, this is the longitude that will be
            shown to the public.
          nullable: true
        businessType:
          description: >-
            The business type of the business, this is the business type that
            will be shown to the public.
          nullable: true
          allOf:
            - $ref: '#/components/schemas/BusinessTypeDTO'
        isActive:
          type: boolean
          description: >-
            The status of the business, this is the status that will be shown to
            the public.
        canMintToken:
          type: boolean
          description: >-
            The ability to mint token for the business, this is the ability that
            will be shown to the public.
        canChargeToken:
          type: boolean
          description: >-
            The ability to charge token for the business, this is the ability
            that will be shown to the public.
        canManageUsers:
          type: boolean
          description: >-
            The ability to manage users for the business, this is the ability
            that will be shown to the public.
        canReceiveDonation:
          type: boolean
          description: >-
            The ability to receive donation for the business, this is the
            ability that will be shown to the public.
        apiPrivateKey:
          type: string
          description: >-
            The api private key of the business, this is the api private key
            that will be used to identify the business with the api.
      required:
        - id
        - email
        - accountAddress
        - businessLegalName
        - displayName
        - description
        - shortDescription
        - websiteUrl
        - imageUrl
        - streetAddress
        - city
        - postalCode
        - coordsLatitude
        - coordsLongitude
        - businessType
        - isActive
        - canMintToken
        - canChargeToken
        - canManageUsers
        - canReceiveDonation
        - apiPrivateKey
    BusinessUpdateRequestDTO:
      type: object
      properties:
        email:
          type: string
          description: >-
            The email of the business, this is unique and will be used to
            identify the business.
        businessLegalName:
          type: string
          description: >-
            The legal name of the business, this is the name that will be used
            for legal purposes.
        displayName:
          type: string
          description: >-
            The display name of the business, this is the name that will be
            shown to the public.
        description:
          type: string
          description: >-
            The description of the business, this is the description that will
            be shown to the public.
        shortDescription:
          type: string
          description: >-
            The short description of the business, this is the description that
            will be shown to the public.
        websiteUrl:
          type: string
          description: >-
            The website of the business, this is the website that will be shown
            to the public.
        imageUrl:
          type: string
          description: >-
            The image of the business, this is the image that will be shown to
            the public.
        streetAddress:
          type: string
          description: >-
            The address of the business, this is the address that will be shown
            to the public.
        city:
          type: string
          description: >-
            The city of the business, this is the city that will be shown to the
            public.
        postalCode:
          type: string
          description: >-
            The postal code of the business, this is the postal code that will
            be shown to the public.
        coordsLatitude:
          type: number
          description: >-
            The latitude of the business, this is the latitude that will be
            shown to the public.
        coordsLongitude:
          type: number
          description: >-
            The longitude of the business, this is the longitude that will be
            shown to the public
        businessTypeId:
          type: number
          description: >-
            The business type of the business, this is the business type that
            will be shown to the public.
    BusinessToggleActiveRequestDTO:
      type: object
      properties:
        isActive:
          type: boolean
        canMintToken:
          type: boolean
        canChargeToken:
          type: boolean
        canManageUsers:
          type: boolean
        canReceiveDonation:
          type: boolean
      required:
        - isActive
    PaginatedResponseDTO:
      type: object
      properties:
        data:
          type: array
          description: Array of data items
        pagination:
          type: object
          description: Pagination metadata
          example:
            page: 1
            limit: 50
            total: 150
            pages: 3
            hasNext: true
            hasPrev: false
      required:
        - data
        - pagination
    AccountSelectorDTO:
      type: object
      properties:
        accountId:
          type: string
          description: >-
            Account ID (businessId or userId). System will auto-detect account
            type.
          example: user123
        accountType:
          type: string
          description: 'Account type '
          enum:
            - user
            - business
            - tenant
            - system
            - external
          example: user
        accountAddress:
          type: string
          description: Direct account address (fallback if account ID not found)
          example: '0x742d35Cc5dB3dC0F0e8f0b0d2fA0c3fA2ed5D0f8'
      required:
        - accountType
    TokenSelectorDTO:
      type: object
      properties:
        tokenDbId:
          type: string
          description: Database token UUID - highest priority for resolution
          example: uuid-12345-67890
        contractAddress:
          type: string
          description: Smart contract address on blockchain
          example: '0x742d35Cc5dB3dC0F0e8f0b0d2fA0c3fA2ed5D0f8'
        nftTokenId:
          type: string
          description: Blockchain NFT token ID (on-chain identifier) - STANDARDIZED FIELD
          example: '721'
        chainId:
          type: number
          description: Blockchain chain ID - auto-resolved from token if not provided
          example: 1
    TransactionRequestDTO:
      type: object
      properties:
        web3TransactionType:
          type: string
          description: Transaction type for easier detection and routing
          enum:
            - MINT
            - TRANSFER
            - BURN
          example: TRANSFER
        sender:
          description: Transaction sender (not required for MINT operations)
          allOf:
            - $ref: '#/components/schemas/AccountSelectorDTO'
        recipient:
          description: Transaction recipient (not required for BURN operations)
          allOf:
            - $ref: '#/components/schemas/AccountSelectorDTO'
        token:
          description: >-
            Token identification with multiple resolution strategies. If not
            provided, defaults to active credit token.
          allOf:
            - $ref: '#/components/schemas/TokenSelectorDTO'
        amount:
          type: number
          description: Transaction amount
          example: 100
      required:
        - web3TransactionType
        - amount
    ClientTransactionRequestDTO:
      type: object
      properties:
        contractAddress:
          type: string
          description: Token address for the transaction
        contractTokenId:
          type: string
          description: Contract token ID, can be null for burn transactions
        amount:
          type: number
          description: Amount of tokens to transfer in the transaction
        recipientAddress:
          type: string
          description: Recipient address, can be null for burn transactions
        senderAddress:
          type: string
          description: Sender address
      required:
        - contractAddress
        - amount
        - senderAddress
    ClientTransactionRequestResponseDto:
      type: object
      properties:
        transactionId:
          type: string
          description: Transaction ID, this is the transaction hash or identifier
        data:
          type: object
          description: Prepared transaction data ready for signing
        walletStatus:
          type: string
          description: Current status of the wallet signing process
          enum:
            - WALLET_AND_SIGNING_READY
            - WALLET_MISSING_SIGNING_ACCOUNT
            - WALLET_NOT_FOUND
      required:
        - transactionId
        - data
        - walletStatus
    ClientTransactionConfirmationDTO:
      type: object
      properties:
        type:
          type: string
          description: Transaction format type for submission
          enum:
            - legacy
            - EIP-2930
            - EIP-1559
            - EIP-712
          example: legacy
        signature:
          type: string
          description: >-
            EIP-712 structured data for smart wallet meta-transactions (required
            when type is EIP-712)
          example: 0x1234567890abcdef...
        signedTransaction:
          type: string
          description: >-
            Pre-signed blockchain transaction in RLP encoded hex format
            (required for legacy, EIP-2930, EIP-1559)
          example: 0xf86c0a8255f0...
      required:
        - type
    GroupByExpressionDTO:
      type: object
      properties:
        expression:
          type: string
          description: SQL CASE WHEN expression for complex grouping logic
          example: >-
            CASE WHEN senderOwnerType = user THEN senderId WHEN
            recipientOwnerType = user THEN recipientId END
        alias:
          type: string
          description: Alias name for the expression result in SELECT clause
          example: userId
        label:
          type: string
          description: Human-readable label for frontend display
          example: User ID
      required:
        - expression
        - alias
    TransactionAnalyticsRequestDTO:
      type: object
      properties:
        filters:
          type: object
          description: >-
            Dynamic filters based on TransactionDTO fields - all transaction
            fields available
          example:
            status: SUCCEEDED
            tokenType: STAMP
            triggerProcessType: MINT
            tenantId: tenant-123
            chainId: 1
        groupBy:
          description: >-
            Fields to group by - any TransactionDTO field plus computed time
            fields
          example:
            - tokenType
            - month
            - status
            - chainId
          type: array
          items:
            type: string
        groupByExpressions:
          description: Complex CASE WHEN expressions for advanced grouping scenarios
          example:
            - expression: >-
                CASE WHEN senderOwnerType = user THEN senderId WHEN
                recipientOwnerType = user THEN recipientId END
              alias: userId
              label: User ID
          type: array
          items:
            $ref: '#/components/schemas/GroupByExpressionDTO'
        metrics:
          type: string
          description: Metrics to calculate
          enum:
            - count
            - sum
            - avg
            - min
            - max
          example:
            - count
        sortBy:
          type: string
          description: Field to order results by (supports expression aliases)
          enum:
            - count
            - sum
            - avg
            - min
            - max
            - createdAt
          example: count
        sortOrder:
          type: number
          description: Order direction
          enum:
            - ASC: ASC
              DESC: DESC
          example: DESC
        limit:
          type: number
          description: Maximum number of results to return
          minimum: 1
          maximum: 100
          example: 10
        startDate:
          format: date-time
          type: string
          description: Start date for analytics (ISO format)
          example: '2024-01-01T00:00:00.000Z'
        endDate:
          format: date-time
          type: string
          description: End date for analytics (ISO format)
          example: '2024-12-31T23:59:59.999Z'
    TransactionAnalyticsResponseDTO:
      type: object
      properties:
        results:
          type: array
          description: Analytics results array with dynamic fields and expression aliases
          example:
            - userId: user-123
              count: 45
            - userAddress: 0xabc...def
              count: 32
            - tokenType: STAMP
              count: 150
              month: '2024-01-01T00:00:00.000Z'
        totalGroups:
          type: number
          description: Total number of result groups
          example: 3
        metadata:
          type: object
          description: Query execution metadata
          example:
            executionTime: 45ms
      required:
        - results
        - totalGroups
        - metadata
    TokenTypeDTO:
      type: object
      properties:
        nativeTokenType:
          type: string
          description: |-
            Token native Types: 
                    - ERC20: used for credits 
                    - ERC721: used for stamps and NFTs 
                    - ERC1155: used for rewards
          enum:
            - ERC20
            - ERC1155
            - ERC721
        name:
          type: string
          description: Token type name
        imageUrl:
          type: string
          description: Token type image url
        description:
          type: string
          description: Token type description
      required:
        - nativeTokenType
    TokenCreateRequestDTO:
      type: object
      properties:
        contractAddress:
          type: string
          description: Contract address is the address of the token contract on chain.
        abiUrl:
          type: string
          description: >-
            The ABI URL is the URL to the contract ABI. This is an optional
            field. If not provided, the contract ABI will be fetched from PERS
            instance depending on selected token type.
        type:
          type: string
          enum:
            - ERC20
            - ERC1155
            - ERC721
        decimals:
          type: number
          description: >-
            Decimals is the number of decimals the token uses. This is useful
            for ERC20 tokens.
      required:
        - contractAddress
        - type
    TokenUpdateRequestDTO:
      type: object
      properties:
        isGallery:
          type: boolean
          description: >-
            This indicates if token should be included as a gallery. This is
            useful for ERC721 or ERC1155 tokens.
        name:
          type: string
          description: The name of the token
        symbol:
          type: string
          description: The symbol of the token
    TokenMetadataCreateRequestDTO:
      type: object
      properties:
        imageUrl:
          type: string
          description: ' This is the URL to the image of the item. Can be just about any type of image (including SVGs, which will be cached into PNGs by OpenSea), IPFS or Arweave URLs or paths. We recommend using a minimum 3000 x 3000 image.'
        externalUrl:
          type: string
          description: This is the URL that will appear below the asset's image
        description:
          type: string
          description: A human-readable description of the item. Markdown is supported.
        name:
          type: string
          description: Name of the item.
        expiryDate:
          format: date-time
          type: string
          description: expiry date in case of an utility reward
        animationUrl:
          type: string
          description: >-
            A URL to a multi-media attachment for the item. The file extensions
            GLTF, GLB, WEBM, MP4, M4V, OGV, and OGG are supported, along with
            the audio-only extensions MP3, WAV, and OGA. Animation_url also
            supports HTML pages, allowing you to build rich experiences and
            interactive NFTs using JavaScript canvas, WebGL, and more. Scripts
            and relative paths within the HTML page are now supported. However,
            access to browser extensions is not supported.
        youtubeUrl:
          type: string
          description: A URL to a YouTube video (only used if animation_url is not provide
        creatorAccountAddress:
          type: string
          description: Creator Address
        previewUrl:
          type: string
          description: Preview Url
    TenantCreateRequestDTO:
      type: object
      properties:
        projectName:
          type: string
      required:
        - projectName
    TenantDTO:
      type: object
      properties:
        projectName:
          type: string
          description: Name of the tenant.
        acronym:
          type: string
          description: Acronym of the tenant.
        id:
          type: string
          description: >-
            Unique identifier for tenant. This id is used to identify tenant in
            the system for client requests.
        createdAt:
          format: date-time
          type: string
          description: Date when tenant was created.
        projectDescription:
          type: string
          description: Description of the tenant.
        projectWebsite:
          type: string
          description: Website of the tenant.
        projectEmail:
          type: string
          description: Email of the tenant.
        projectImageUrl:
          type: string
          description: Image URL of the tenant.
        projectApiKey:
          type: string
          description: >-
            Unique identifier for tenant. This id is used to identify tenant in
            the system for client requests.
        testnetProjectApiKey:
          type: string
          description: Testnet project API key for tenant. Used in case of testnet project.
        stripeApiKey:
          type: string
          description: Stripe API key for tenant. Used in case of stripe payment.
        stripeWebhookSecret:
          type: string
          description: Stripe webhook secret for tenant. Used in case of stripe payment.
        loginToken:
          type: string
          description: >-
            This is an optional field for any extra login requirements for your
            users.
        allowJWTForUnauthenticatedUsers:
          type: boolean
          description: >-
            This is an optional field for any extra login requirements for your
            users.
        firebaseTenantId:
          type: string
        jwt:
          type: string
          description: >-
            JWT token for tenant admin user. This token is used to authenticate
            tenant admin user. It is generated when tenant is created. Please
            store it securely, you will not be able to see this again. However,
            you can generate a new one if needed.
        apiPrivateKey:
          type: string
          description: >-
            API private key for tenant. This key is used to authenticate tenant
            when making API requests. It is generated on demand. Please store it
            securely, you will not be able to see this again. However, you can
            generate a new one if needed.
        defaultWalletManagementType:
          type: string
          description: >-
            Default wallet management type for tenant. This is used when
            creating a new wallet for the tenant. It can be either CUSTODIAL or
            NON_CUSTODIAL. CUSTODIAL means that the wallet is managed by the
            platform, while NON_CUSTODIAL means that the wallet is managed by
            the user.
          enum:
            - custodial
            - non-custodial
          default: custodial
      required:
        - projectName
        - acronym
        - id
        - createdAt
        - projectApiKey
        - testnetProjectApiKey
        - allowJWTForUnauthenticatedUsers
        - defaultWalletManagementType
    TenantPublicDTO:
      type: object
      properties:
        projectName:
          type: string
          description: Name of the tenant.
        acronym:
          type: string
          description: Acronym of the tenant.
        id:
          type: string
          description: >-
            Unique identifier for tenant. This id is used to identify tenant in
            the system for client requests.
        createdAt:
          format: date-time
          type: string
          description: Date when tenant was created.
        projectDescription:
          type: string
          description: Description of the tenant.
        projectWebsite:
          type: string
          description: Website of the tenant.
        projectEmail:
          type: string
          description: Email of the tenant.
        projectImageUrl:
          type: string
          description: Image URL of the tenant.
      required:
        - projectName
        - acronym
        - id
        - createdAt
    TenantClientConfigDTO:
      type: object
      properties:
        projectName:
          type: string
          description: The project name
          example: My Project
        id:
          type: string
          description: The project id
          example: ererf-erf-erf-erf
        stripePublishableKey:
          type: string
          description: Stripe publishable key for tenant. Used in case of stripe payment.
        firebaseTenantId:
          type: string
          description: >-
            Firebase tenant ID for tenant. This id is needed, if you choose to
            setup Firebase for user authentification for your project.
        infuraApiKey:
          type: string
          description: >-
            Infura API key for tenant. Used in for client interaction with web3
            provider.
        polyScanApiKey:
          type: string
          description: >-
            PolyScan API key for tenant. Used in for client interaction with
            PolyScan.
        clientIpLocation:
          type: object
          description: Geolocation information derived from the client IP address
          properties:
            country_code:
              type: string
            country_name:
              type: string
            region_code:
              type: string
            region_name:
              type: string
            city_name:
              type: string
            postal_code:
              type: string
            latitude:
              type: number
              example: 37.7749
            longitude:
              type: number
              example: -122.4194
            accuracy_radius:
              type: number
              example: 5
          nullable: true
      required:
        - projectName
        - id
    TenantUpdateRequestDTO:
      type: object
      properties:
        projectName:
          type: string
          description: The project name
          example: My Project
        projectDescription:
          type: string
          description: The project description
        stripeApiKey:
          type: string
        stripeWebhookSecret:
          type: string
        stripePublishableKey:
          type: string
        loginToken:
          type: string
        allowJWTForUnauthenticatedUsers:
          type: boolean
          description: >-
            This is an optional field for any extra login requirements for your
            users.
        firebaseTenantId:
          type: string
        projectWebsite:
          type: string
        projectEmail:
          type: string
        projectImageUrl:
          type: string
    TenantApiKeyRequestDTO:
      type: object
      properties:
        keyName:
          type: string
          description: name of the key
      required:
        - keyName
    TenantJWTRequestDTO:
      type: object
      properties:
        isTestnet:
          type: boolean
          description: wheter the key is for testnet or mainnet
      required:
        - isTestnet
    AdminDTO:
      type: object
      properties:
        id:
          type: string
          description: Id of the admin
        email:
          type: string
          description: Email of the admin
        displayName:
          type: object
          description: Display name of the admin
        type:
          type: string
          description: Type of the admin
          enum:
            - SUPER_ADMIN
            - TENANT_ADMIN
        tenants:
          description: Tenant of the admin
          type: array
          items:
            $ref: '#/components/schemas/TenantDTO'
      required:
        - id
        - email
        - displayName
        - type
    AdminCreateRequestDTO:
      type: object
      properties:
        email:
          type: string
          description: Email of the admin
        displayName:
          type: string
          description: Display name of the admin
        type:
          type: string
          description: Type of the admin
          enum:
            - SUPER_ADMIN
            - TENANT_ADMIN
      required:
        - email
        - type
    TokenMetadataBalanceDTO:
      type: object
      properties:
        contractAddress:
          type: string
        chainId:
          type: number
        balance:
          type: number
        tokenName:
          type: string
        tokenSymbol:
          type: string
        tokenType:
          type: string
        tokenId:
          type: string
          nullable: true
        metadataUri:
          type: string
          nullable: true
        metadata:
          type: object
      required:
        - contractAddress
        - chainId
        - balance
        - tokenType
        - tokenId
        - metadataUri
        - metadata
    AccountTokenMetadataBalancesDTO:
      type: object
      properties:
        accountAddress:
          type: string
        tokenBalances:
          type: array
          items:
            $ref: '#/components/schemas/TokenMetadataBalanceDTO'
      required:
        - accountAddress
        - tokenBalances
    SessionAuthResponseDTO:
      type: object
      properties:
        accessToken:
          type: string
          description: >-
            JWT access token this token is used to authenticate the user, by
            default it expires in 15 minutes, and it should be sent in the
            Authorization header as Bearer token.
        refreshToken:
          type: string
          description: >-
            JWT refresh token this token is used to get a new access token when
            the current one expires. It is valid for 1 day.
        admin:
          description: Admin (present if admin authentication)
          allOf:
            - $ref: '#/components/schemas/AdminDTO'
        user:
          description: User (present if user authentication)
          allOf:
            - $ref: '#/components/schemas/UserDTO'
      required:
        - accessToken
        - refreshToken
    RefreshTokenRequestDTO:
      type: object
      properties:
        refreshToken:
          type: string
          description: refresh token
          example: >-
            eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnRJZCI6IjEiLCJpYXQiOjE2MjYxNzUwNzksImV4cCI6MTYyNjE3NTI3OX0.5w8A6t7b5lBx8D3FmLwJQgJ9z1D9c9Vz7A3f7BvzH2A
      required:
        - refreshToken
    EntityStorageUrlDTO:
      type: object
      properties:
        entityType:
          type: string
          description: The entity type
          enum:
            - token
            - campaign
            - redemption
            - business
            - tenant
            - user
        entityId:
          type: string
          description: The entity id
        signedUrlType:
          type: string
          description: >-
            The signed url type, GET or PUT. PUT is used for uploading files,
            GET is used for downloading files
          enum:
            - GET
            - PUT
        fileExtension:
          type: string
          description: The file extension
        fileName:
          type: string
          description: The file name
      required:
        - entityType
        - entityId
        - signedUrlType
        - fileExtension
    CreateSignedURLResponseDTO:
      type: object
      properties:
        signedUrl:
          type: string
          description: The signed url
      required:
        - signedUrl
    ChainDataDTO:
      type: object
      properties:
        name:
          type: string
          description: Name of the chain
        shortName:
          type: string
          description: Short name of the chain
        chain:
          type: string
          description: Chain name
        network:
          type: string
          description: Network name
        chainId:
          type: number
          description: Chain ID
        explorerUrl:
          type: string
          description: explorer URL
        networkId:
          type: number
          description: Network ID
        rpcUrl:
          type: string
          description: RPC URL
        authHeader:
          type: string
          description: Authorization header
        chainType:
          type: string
          description: Chain type
      required:
        - name
        - rpcUrl
        - chainType
    Web3ContractCreateRequestDTO:
      type: object
      properties:
        implementationAddress:
          type: string
          description: >-
            this is implementation address, the address of the contract that is
            being used as implementation for the proxy. This is only used for
            proxy contracts
        contractAddress:
          type: string
          description: this is the address of the contract
        ownerAddress:
          type: string
          description: this is the address of the owner of the contract
        factoryAddress:
          type: string
          description: >-
            this is the address of the factory contract that deploys this
            contract
          nullable: true
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        chainId:
          type: number
          description: this is the chain id of the contract
        contractVersion:
          type: string
          description: this is the version of the contract
        contractType:
          type: string
          description: this is the type of the contract
          enum:
            - SMART_WALLET_FACTORY
            - SMART_WALLET_IMPLEMENTATION
            - SMART_WALLET_PROXY
            - COUNTERFACTUAL_WALLET_FACTORY
            - COUNTERFACTUAL_WALLET_IMPLEMENTATION
            - COUNTERFACTUAL_WALLET_PROXY
            - TOKEN_CONTRACT
        nativeTokenType:
          type: string
          description: >-
            this is the native token type of the contract, this is only used for
            native tokens
          enum:
            - ERC20
            - ERC1155
            - ERC721
          nullable: true
        salt:
          type: string
          description: >-
            this is the salt of the contract, this is only used for proxy
            contract factories to generate unique contracts
        txHash:
          type: string
          description: >-
            this is the transaction hash of the contract deployment, this is
            only used for deployed contracts
          nullable: true
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        isProxy:
          type: boolean
          description: this is the flag to check if the contract is a proxy contract
        abiUrl:
          type: string
          description: >-
            this is the url of the abi of the contract, to be used to fetch the
            abi of the contract
        deploymentStatus:
          type: string
          description: current deployment status of the contract
          enum:
            - COMPUTED
            - DEPLOYED
            - FAILED
      required:
        - contractAddress
        - chainId
        - contractType
        - nativeTokenType
        - isProxy
        - deploymentStatus
    Web3ContractDTO:
      type: object
      properties:
        implementationAddress:
          type: string
          description: >-
            this is implementation address, the address of the contract that is
            being used as implementation for the proxy. This is only used for
            proxy contracts
        contractAddress:
          type: string
          description: this is the address of the contract
        ownerAddress:
          type: string
          description: this is the address of the owner of the contract
        factoryAddress:
          type: string
          description: >-
            this is the address of the factory contract that deploys this
            contract
          nullable: true
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        chainId:
          type: number
          description: this is the chain id of the contract
        contractVersion:
          type: string
          description: this is the version of the contract
        contractType:
          type: string
          description: this is the type of the contract
          enum:
            - SMART_WALLET_FACTORY
            - SMART_WALLET_IMPLEMENTATION
            - SMART_WALLET_PROXY
            - COUNTERFACTUAL_WALLET_FACTORY
            - COUNTERFACTUAL_WALLET_IMPLEMENTATION
            - COUNTERFACTUAL_WALLET_PROXY
            - TOKEN_CONTRACT
        nativeTokenType:
          type: string
          description: >-
            this is the native token type of the contract, this is only used for
            native tokens
          enum:
            - ERC20
            - ERC1155
            - ERC721
          nullable: true
        salt:
          type: string
          description: >-
            this is the salt of the contract, this is only used for proxy
            contract factories to generate unique contracts
        txHash:
          type: string
          description: >-
            this is the transaction hash of the contract deployment, this is
            only used for deployed contracts
          nullable: true
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        isProxy:
          type: boolean
          description: this is the flag to check if the contract is a proxy contract
        abiUrl:
          type: string
          description: >-
            this is the url of the abi of the contract, to be used to fetch the
            abi of the contract
        deploymentStatus:
          type: string
          description: current deployment status of the contract
          enum:
            - COMPUTED
            - DEPLOYED
            - FAILED
        id:
          type: string
          description: this is the id of the contract
        abi:
          type: object
          description: >-
            this is the abi of the contract, this is the interface of the
            contract to interact with it
        tenantId:
          type: object
          description: >-
            this is the tenant id of the contract, this can be null for generic
            contracts
      required:
        - contractAddress
        - chainId
        - contractType
        - nativeTokenType
        - isProxy
        - deploymentStatus
        - id
        - abi
        - tenantId
security:
  - projectKey: []
    businessApiKey: []
