openapi: 3.0.3
info:
  title: Decentraland Referral Service API
  description: |
    ## Overview
    The Decentraland Referral Service API provides a comprehensive reward and campaign management system for the Decentraland ecosystem. This service enables users to create campaigns, manage rewards, assign tokens to users, and handle the complete lifecycle of referral-based incentives

    ### Key Features

    - **Campaign Management**: Create and manage reward campaigns with configurable parameters
    - **Reward System**: Assign and distribute various types of rewards (NFTs, tokens) to users
    - **Blockchain Integration**: Support for multiple blockchain networks (Ethereum, Polygon)
    - **Authentication**: Secure user authentication and authorization
    - **Transaction Management**: Handle reward claims and blockchain transactions
    - **Referral System**: Track and manage user referrals and codes

    ### Architecture

    The service is built on a microservices architecture with the following main components:

    - **Campaigns**: Core campaign management and configuration
    - **Rewards**: Reward assignment, tracking, and distribution
    - **Transactions**: Blockchain transaction handling and monitoring
    - **Users**: User management and authentication
    - **Referrals**: Referral tracking and code management

    ### Authentication

    Most endpoints require authentication using Decentraland's authentication system. Users must sign requests with their wallet to access protected resources.

    ### Rate Limiting

    The API implements rate limiting to ensure fair usage. Please refer to response headers for current rate limit information.

    ### Error Handling

    The API uses standard HTTP status codes and provides detailed error information in the response body when errors occur.
  version: 1.0.0
  contact:
    name: Decentraland Team
    url: https://decentraland.org
    email: support@decentraland.org
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://rewards.decentraland.org
    description: Production server
  - url: https://rewards.decentraland.zone
    description: Development server
  - url: http://localhost:8000
    description: Local Development server
security:
  - bearerAuth: []
tags:
  - name: Campaigns
    description: Campaign management operations
  - name: Campaign Keys
    description: Campaign key management operations
  - name: Rewards
    description: Reward management operations
  - name: Campaign Rewards
    description: Campaign-specific reward operations
  - name: Claims
    description: Claim management operations
  - name: Referrals
    description: Referral system operations
  - name: Codes
    description: Referral code management
  - name: Captcha
    description: Captcha verification operations
  - name: Campaign Wallets
    description: Campaign wallet management
  - name: Campaign Users
    description: Campaign user management
  - name: Campaign Transactions
    description: Campaign transaction operations
  - name: Collection Transactions
    description: Collection transaction operations
  - name: Claim Transactions
    description: Claim transaction operations
  - name: System
    description: System status and health operations
paths:
  /api/campaigns:
    get:
      tags:
        - Campaigns
      summary: Get user campaigns
      description: Retrieve a list of campaigns for the authenticated user with optional filtering
      security: []
      parameters:
        - name: status
          in: query
          description: Filter campaigns by status
          schema:
            type: string
            enum:
              - Enabled
              - Disable
        - name: limit
          in: query
          description: Maximum number of results per request
          schema:
            type: string
            default: '25'
        - name: offset
          in: query
          description: Number of results to skip
          schema:
            type: string
            default: '0'
      responses:
        '200':
          description: List of campaigns
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      required: &ref_3
                        - id
                        - name
                        - enabled
                        - chain_id
                        - created_at
                        - updated_at
                      properties: &ref_4
                        id:
                          type: string
                          format: uuid
                          description: Campaign ID
                          example: 123e4567-e89b-12d3-a456-426614174000
                        name:
                          type: string
                          description: Campaign name
                          example: Summer Rewards Campaign
                        enabled:
                          type: boolean
                          description: Whether the campaign is enabled to give rewards
                          example: true
                        active_since:
                          type: string
                          format: date-time
                          nullable: true
                          description: The moment from which the campaign will start to give rewards
                          example: '2024-01-01T00:00:00Z'
                        active_until:
                          type: string
                          format: date-time
                          nullable: true
                          description: The moment from which the campaign stops giving rewards
                          example: '2024-12-31T23:59:59Z'
                        max_gas:
                          type: number
                          description: Maximum gas fee able to expend per transaction
                          example: 200
                        chain_id:
                          type: string
                          enum: &ref_2
                            - '1'
                            - '3'
                            - '4'
                            - '5'
                            - '42'
                            - '137'
                            - '80001'
                            - '80002'
                            - '11155111'
                          description: Blockchain chain ID
                          example: '137'
                        created_at:
                          type: string
                          format: date-time
                          description: The time the campaign was created
                          example: '2024-01-01T00:00:00Z'
                        updated_at:
                          type: string
                          format: date-time
                          description: The time the campaign was last updated
                          example: '2024-01-01T00:00:00Z'
                  total:
                    type: number
                    description: Total number of campaigns matching the filter
        '401':
          description: Unauthorized
          content: &ref_5
            application/json:
              schema:
                type: object
                required: &ref_0
                  - ok
                  - error
                properties: &ref_1
                  ok:
                    type: boolean
                    example: false
                    description: Whether the request was successful
                  error:
                    type: string
                    description: Error message
                    example: Campaign not found
                  code:
                    type: string
                    description: Error code
                    example: CAMPAIGN_NOT_FOUND
                  data:
                    type: object
                    description: Additional error data
                    example: {}
              example:
                ok: false
                error: Authentication required
                code: UNAUTHORIZED
        '500':
          description: Internal server error
          content: &ref_6
            application/json:
              schema:
                type: object
                required: *ref_0
                properties: *ref_1
              example:
                ok: false
                error: Internal server error
                code: INTERNAL_SERVER_ERROR
    post:
      tags:
        - Campaigns
      summary: Create a new campaign
      description: Create a new reward campaign with specified configuration
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: &ref_32
                - name
              properties: &ref_33
                name:
                  type: string
                  description: Campaign name
                  minLength: 3
                  example: Summer Rewards Campaign
                chain_id:
                  type: string
                  enum: *ref_2
                  description: Blockchain chain ID
                  example: '137'
                enabled:
                  type: boolean
                  description: Whether the campaign is enabled
                  default: true
                  example: true
                max_gas:
                  type: number
                  description: Maximum gas fee per transaction
                  default: 200
                  example: 200
                active_since:
                  type: string
                  format: date-time
                  nullable: true
                  description: Campaign start time
                  example: '2024-01-01T00:00:00Z'
                active_until:
                  type: string
                  format: date-time
                  nullable: true
                  description: Campaign end time
                  example: '2024-12-31T23:59:59Z'
      responses:
        '201':
          description: Campaign created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: *ref_3
                    properties: *ref_4
        '400':
          description: Bad request
          content: &ref_7
            application/json:
              schema:
                type: object
                required: *ref_0
                properties: *ref_1
              example:
                ok: false
                error: Invalid request data
                code: BAD_REQUEST
        '401':
          description: Unauthorized
          content: *ref_5
        '500':
          description: Internal server error
          content: *ref_6
  /api/campaigns/publics:
    get:
      tags:
        - Campaigns
      summary: Get public campaigns
      description: Retrieve public campaign information by IDs
      security: []
      parameters:
        - name: id
          in: query
          required: true
          description: Array of campaign IDs to retrieve
          schema:
            type: array
            items:
              type: string
              format: uuid
            minItems: 1
            maxItems: 100
      responses:
        '200':
          description: Public campaign information
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      allOf: &ref_31
                        - type: object
                          required: *ref_3
                          properties: *ref_4
                        - type: object
                          properties:
                            role:
                              type: string
                              enum: &ref_22
                                - owner
                                - manager
                                - viewer
                              description: User role in the campaign
                              example: owner
        '400':
          description: Bad request
          content: *ref_7
        '500':
          description: Internal server error
          content: *ref_6
  /api/campaigns/{campaign_id}:
    get:
      tags:
        - Campaigns
      summary: Get campaign details
      description: Retrieve detailed information about a specific campaign
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Campaign details
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: *ref_3
                    properties: *ref_4
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: &ref_8
            application/json:
              schema:
                type: object
                required: *ref_0
                properties: *ref_1
              example:
                ok: false
                error: Resource not found
                code: NOT_FOUND
        '500':
          description: Internal server error
          content: *ref_6
    patch:
      tags:
        - Campaigns
      summary: Update campaign
      description: Update campaign configuration and settings
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: &ref_34
                name:
                  type: string
                  description: Campaign name
                  minLength: 3
                  example: Updated Campaign Name
                chain_id:
                  type: string
                  enum: *ref_2
                  description: Blockchain chain ID
                  example: '137'
                enabled:
                  type: boolean
                  description: Whether the campaign is enabled
                  example: true
                max_gas:
                  type: number
                  description: Maximum gas fee per transaction
                  example: 200
                active_since:
                  type: string
                  format: date-time
                  nullable: true
                  description: Campaign start time
                  example: '2024-01-01T00:00:00Z'
                active_until:
                  type: string
                  format: date-time
                  nullable: true
                  description: Campaign end time
                  example: '2024-12-31T23:59:59Z'
      responses:
        '200':
          description: Campaign updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: *ref_3
                    properties: *ref_4
        '400':
          description: Bad request
          content: *ref_7
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
  /api/campaigns/{campaign_id}/claim_funds:
    post:
      tags:
        - Campaigns
      summary: Claim campaign funds
      description: Claim funds from a campaign to a specified address
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: &ref_35
                - address
              properties: &ref_36
                address:
                  type: string
                  format: address
                  description: Address to send funds to
                  example: '0x1234567890123456789012345678901234567890'
      responses:
        '200':
          description: Funds claimed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    description: Transaction details
        '400':
          description: Bad request
          content: *ref_7
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
  /api/campaigns/keys:
    get:
      tags:
        - Campaign Keys
      summary: Get campaign keys by key
      description: Retrieve campaign keys by key value
      security: []
      responses:
        '200':
          description: Campaign keys
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      required: &ref_9
                        - id
                        - campaign_id
                        - key
                        - enabled
                        - created_at
                        - updated_at
                      properties: &ref_10
                        id:
                          type: string
                          format: uuid
                          description: Campaign Key ID
                          example: 123e4567-e89b-12d3-a456-426614174000
                        campaign_id:
                          type: string
                          format: uuid
                          description: Campaign ID
                          example: 123e4567-e89b-12d3-a456-426614174000
                        key:
                          type: string
                          description: Campaign key value
                          example: summer2024
                        enabled:
                          type: boolean
                          description: Whether the key is enabled
                          example: true
                        active_since:
                          type: string
                          format: date-time
                          nullable: true
                          description: Key activation time
                          example: '2024-01-01T00:00:00Z'
                        active_until:
                          type: string
                          format: date-time
                          nullable: true
                          description: Key expiration time
                          example: '2024-12-31T23:59:59Z'
                        requires_authentication:
                          type: boolean
                          description: Whether the key requires user authentication
                          example: false
                        requires_captcha:
                          type: boolean
                          description: Whether the key requires captcha verification
                          example: false
                        requires_catalyst:
                          type: boolean
                          description: Whether the key requires catalyst verification
                          example: false
                        requires_position:
                          type: string
                          nullable: true
                          description: Required position for catalyst verification
                          example: '*'
                        assign_target:
                          type: string
                          format: address
                          nullable: true
                          description: Target contract for reward assignment
                          example: '0x1234567890123456789012345678901234567890'
                        assign_value:
                          type: string
                          nullable: true
                          description: Value for reward assignment
                          example: '1'
                        assign_group:
                          type: string
                          nullable: true
                          description: Group for reward assignment
                          example: premium
                        assign_limit:
                          type: number
                          nullable: true
                          description: Assignment limit for the key
                          example: 100
                        created_at:
                          type: string
                          format: date-time
                          description: Key creation time
                          example: '2024-01-01T00:00:00Z'
                        updated_at:
                          type: string
                          format: date-time
                          description: Key last update time
                          example: '2024-01-01T00:00:00Z'
        '500':
          description: Internal server error
          content: *ref_6
  /api/campaigns/{campaign_id}/keys:
    get:
      tags:
        - Campaign Keys
      summary: Get campaign keys
      description: Retrieve all keys for a specific campaign
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Campaign keys
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      required: *ref_9
                      properties: *ref_10
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
    post:
      tags:
        - Campaign Keys
      summary: Create campaign key
      description: Create a new key for a campaign
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: &ref_37
                - key
              properties: &ref_38
                key:
                  type: string
                  description: Campaign key value
                  minLength: 1
                  example: summer2024
                enabled:
                  type: boolean
                  description: Whether the key is enabled
                  default: true
                  example: true
                active_since:
                  type: string
                  format: date-time
                  nullable: true
                  description: Key activation time
                  example: '2024-01-01T00:00:00Z'
                active_until:
                  type: string
                  format: date-time
                  nullable: true
                  description: Key expiration time
                  example: '2024-12-31T23:59:59Z'
                requires_authentication:
                  type: boolean
                  description: Whether the key requires user authentication
                  default: false
                  example: false
                requires_captcha:
                  type: boolean
                  description: Whether the key requires captcha verification
                  default: false
                  example: false
                requires_catalyst:
                  type: boolean
                  description: Whether the key requires catalyst verification
                  default: false
                  example: false
                requires_position:
                  type: string
                  nullable: true
                  description: Required position for catalyst verification
                  example: '*'
                assign_target:
                  type: string
                  format: address
                  nullable: true
                  description: Target contract for reward assignment
                  example: '0x1234567890123456789012345678901234567890'
                assign_value:
                  type: string
                  nullable: true
                  description: Value for reward assignment
                  example: '1'
                assign_group:
                  type: string
                  nullable: true
                  description: Group for reward assignment
                  example: premium
                assign_limit:
                  type: number
                  nullable: true
                  description: Assignment limit for the key
                  example: 100
      responses:
        '201':
          description: Campaign key created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: *ref_9
                    properties: *ref_10
        '400':
          description: Bad request
          content: *ref_7
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
  /api/campaigns/{campaign_id}/keys/{campaign_key_id}:
    get:
      tags:
        - Campaign Keys
      summary: Get campaign key details
      description: Retrieve detailed information about a specific campaign key
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
        - name: campaign_key_id
          in: path
          required: true
          description: Campaign Key ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Campaign key details
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: *ref_9
                    properties: *ref_10
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
    patch:
      tags:
        - Campaign Keys
      summary: Update campaign key
      description: Update campaign key configuration
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
        - name: campaign_key_id
          in: path
          required: true
          description: Campaign Key ID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: &ref_39
                key:
                  type: string
                  description: Campaign key value
                  minLength: 1
                  example: summer2024
                enabled:
                  type: boolean
                  description: Whether the key is enabled
                  example: true
                active_since:
                  type: string
                  format: date-time
                  nullable: true
                  description: Key activation time
                  example: '2024-01-01T00:00:00Z'
                active_until:
                  type: string
                  format: date-time
                  nullable: true
                  description: Key expiration time
                  example: '2024-12-31T23:59:59Z'
                requires_authentication:
                  type: boolean
                  description: Whether the key requires user authentication
                  example: false
                requires_captcha:
                  type: boolean
                  description: Whether the key requires captcha verification
                  example: false
                requires_catalyst:
                  type: boolean
                  description: Whether the key requires catalyst verification
                  example: false
                requires_position:
                  type: string
                  nullable: true
                  description: Required position for catalyst verification
                  example: '*'
                assign_target:
                  type: string
                  format: address
                  nullable: true
                  description: Target contract for reward assignment
                  example: '0x1234567890123456789012345678901234567890'
                assign_value:
                  type: string
                  nullable: true
                  description: Value for reward assignment
                  example: '1'
                assign_group:
                  type: string
                  nullable: true
                  description: Group for reward assignment
                  example: premium
                assign_limit:
                  type: number
                  nullable: true
                  description: Assignment limit for the key
                  example: 100
      responses:
        '200':
          description: Campaign key updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: *ref_9
                    properties: *ref_10
        '400':
          description: Bad request
          content: *ref_7
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
    delete:
      tags:
        - Campaign Keys
      summary: Delete campaign key
      description: Delete a campaign key
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
        - name: campaign_key_id
          in: path
          required: true
          description: Campaign Key ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Campaign key deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
  /api/rewards:
    get:
      tags:
        - Rewards
      summary: Get user rewards
      description: Retrieve rewards for the authenticated user with optional filtering
      security: []
      parameters:
        - name: status
          in: query
          description: Filter rewards by status
          schema:
            type: string
            enum:
              - assigned
              - sending
              - success
              - rejected
              - unassigned
              - pending
              - available
              - claimed
              - successful
              - failed
              - confirmed
        - name: limit
          in: query
          description: Maximum number of results per request
          schema:
            type: string
            default: '100'
        - name: offset
          in: query
          description: Number of results to skip
          schema:
            type: string
            default: '0'
      responses:
        '200':
          description: List of rewards
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      required: &ref_11
                        - id
                        - campaign_id
                        - user
                        - status
                        - chain_id
                        - target
                        - value
                        - token
                        - airdrop_type
                        - created_at
                        - updated_at
                      properties: &ref_12
                        id:
                          type: string
                          format: uuid
                          description: Reward ID
                          example: 123e4567-e89b-12d3-a456-426614174000
                        campaign_id:
                          type: string
                          format: uuid
                          description: Campaign ID
                          example: 123e4567-e89b-12d3-a456-426614174000
                        campaign_key:
                          type: string
                          format: uuid
                          nullable: true
                          description: Campaign Key ID
                          example: 123e4567-e89b-12d3-a456-426614174000
                        user:
                          type: string
                          format: address
                          nullable: true
                          description: User address assigned to this reward
                          example: '0x1234567890123456789012345678901234567890'
                        status:
                          type: string
                          enum: &ref_63
                            - unassigned
                            - pending
                            - assigned
                            - sending
                            - success
                            - rejected
                            - confirmed
                            - available
                            - claimed
                            - successful
                            - failed
                          description: Reward delivery status
                          example: assigned
                        chain_id:
                          type: string
                          enum: *ref_2
                          description: Blockchain chain ID
                          example: '137'
                        transaction_hash:
                          type: string
                          nullable: true
                          description: Hash of the transaction in which the reward was sent
                          example: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
                        block_number:
                          type: integer
                          nullable: true
                          description: Block number of the transaction
                          example: 12345678
                        airdrop_type:
                          type: string
                          enum: &ref_13
                            - None
                            - ERC20Transfer
                            - ERC721Mint
                            - ERC721Transfer
                            - ERC721Kitty
                            - CollectionV2IssueToken
                          description: Delivery strategy for the reward
                          example: CollectionV2IssueToken
                        target:
                          type: string
                          format: address
                          description: Target contract for the reward
                          example: '0x1234567890123456789012345678901234567890'
                        value:
                          type: string
                          description: Value in the contract for the reward
                          example: '1'
                        priority:
                          type: number
                          description: Assignment priority for the reward
                          example: 1
                        group:
                          type: string
                          nullable: true
                          description: Assignment group for the reward
                          example: premium
                        token:
                          type: string
                          description: Human-readable name for the reward
                          example: Summer Hat
                        image:
                          type: string
                          format: uri
                          nullable: true
                          description: Image that visually represents this reward
                          example: https://example.com/image.png
                        rarity:
                          type: string
                          enum: &ref_66
                            - common
                            - uncommon
                            - rare
                            - epic
                            - legendary
                            - mythic
                            - unique
                          description: Item rarity
                          example: rare
                        category:
                          type: string
                          enum: &ref_67
                            - eyebrows
                            - eyes
                            - facial_hair
                            - hair
                            - mouth
                            - upper_body
                            - lower_body
                            - feet
                            - earring
                            - eyewear
                            - hat
                            - helmet
                            - mask
                            - tiara
                            - top_head
                            - dance
                            - stunt
                            - greeting
                            - fun
                            - poses
                            - reactions
                            - horror
                            - miscellaneous
                          description: Item category
                          example: hat
                        from_referral:
                          type: string
                          format: address
                          nullable: true
                          description: Address of the user who referred this reward
                          example: '0x1234567890123456789012345678901234567890'
                        payload:
                          type: string
                          nullable: true
                          description: Transaction payload (L1 only)
                          example: '0x1234567890abcdef'
                        signature:
                          type: string
                          nullable: true
                          description: Transaction signature (L1 only)
                          example: '0xabcdef1234567890'
                        expires_at:
                          type: string
                          format: date-time
                          nullable: true
                          description: Reward expiration time (L1 only)
                          example: '2024-12-31T23:59:59Z'
                        created_at:
                          type: string
                          format: date-time
                          description: The time the reward was created
                          example: '2024-01-01T00:00:00Z'
                        updated_at:
                          type: string
                          format: date-time
                          description: The time the reward was last updated
                          example: '2024-01-01T00:00:00Z'
                        assigned_at:
                          type: string
                          format: date-time
                          nullable: true
                          description: The time the reward was assigned
                          example: '2024-01-01T00:00:00Z'
                  total:
                    type: number
                    description: Total number of rewards matching the filter
        '401':
          description: Unauthorized
          content: *ref_5
        '500':
          description: Internal server error
          content: *ref_6
    post:
      tags:
        - Rewards
      summary: Assign reward
      description: Assign a reward to a user using a campaign key
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: &ref_40
                - campaign_key
              properties: &ref_41
                campaign_key:
                  type: string
                  description: Campaign key
                  minLength: 1
                  example: summer2024
                beneficiary:
                  type: string
                  format: address
                  description: User address to assign the reward to
                  example: '0x1234567890123456789012345678901234567890'
                captcha_id:
                  type: string
                  format: uuid
                  description: Captcha identifier
                  example: 123e4567-e89b-12d3-a456-426614174000
                captcha_value:
                  type: string
                  description: Captcha value
                  minLength: 6
                  maxLength: 6
                  example: ABC123
                catalyst:
                  type: string
                  format: uri
                  description: Catalyst URL where the user is connected
                  example: https://peer.decentraland.org
                assign_target:
                  type: string
                  format: address
                  description: Target contract for reward assignment
                  example: '0x1234567890123456789012345678901234567890'
                assign_value:
                  type: string
                  description: Value for reward assignment
                  minLength: 1
                  example: '1'
                assign_group:
                  type: string
                  description: Group for reward assignment
                  minLength: 1
                  example: premium
      responses:
        '200':
          description: Reward assigned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      required: *ref_11
                      properties: *ref_12
        '400':
          description: Bad request
          content: *ref_7
        '401':
          description: Unauthorized
          content: *ref_5
        '500':
          description: Internal server error
          content: *ref_6
  /api/rewards/{reward_id}:
    get:
      tags:
        - Rewards
      summary: Get reward details
      description: Retrieve detailed information about a specific reward
      security: []
      parameters:
        - name: reward_id
          in: path
          required: true
          description: Reward ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Reward details
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: *ref_11
                    properties: *ref_12
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
  /api/campaigns/{campaign_id}/supply:
    get:
      tags:
        - Campaign Rewards
      summary: Get campaign supply
      description: Retrieve supply information for a campaign
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Campaign supply information
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      required: &ref_14
                        - campaign_id
                        - target
                        - value
                        - group
                        - total
                        - remaining
                      properties: &ref_15
                        campaign_id:
                          type: string
                          format: uuid
                          description: Campaign ID
                          example: 123e4567-e89b-12d3-a456-426614174000
                        target:
                          type: string
                          format: address
                          description: Target contract
                          example: '0x1234567890123456789012345678901234567890'
                        value:
                          type: string
                          description: Value in the contract
                          example: '1'
                        group:
                          type: string
                          nullable: true
                          description: Supply group
                          example: premium
                        total:
                          type: number
                          description: Total supply
                          example: 1000
                        remaining:
                          type: number
                          description: Remaining supply
                          example: 500
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
    post:
      tags:
        - Campaign Rewards
      summary: Create campaign supply
      description: Add supply items to a campaign
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: &ref_46
                - target
                - value
                - airdrop_type
              properties: &ref_47
                target:
                  type: string
                  format: address
                  description: Target contract
                  example: '0x1234567890123456789012345678901234567890'
                value:
                  type: string
                  description: Value in the contract
                  minLength: 1
                  maxLength: 128
                  example: '1'
                airdrop_type:
                  type: string
                  enum: *ref_13
                  description: Delivery strategy for the reward
                  example: CollectionV2IssueToken
                token:
                  type: string
                  nullable: true
                  description: Human-readable name
                  example: Summer Hat
                image:
                  type: string
                  format: uri
                  nullable: true
                  description: Image URL
                  example: https://example.com/image.png
                supply:
                  type: integer
                  minimum: 0
                  description: Supply amount
                  example: 1000
                group:
                  type: string
                  nullable: true
                  description: Supply group
                  example: premium
                priority:
                  oneOf:
                    - type: number
                      minimum: -2147483647
                      maximum: 2147483647
                    - type: string
                      enum:
                        - random
                  description: Assignment priority
                  example: 1
      responses:
        '201':
          description: Supply created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: *ref_14
                    properties: *ref_15
        '400':
          description: Bad request
          content: *ref_7
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
    patch:
      tags:
        - Campaign Rewards
      summary: Remove campaign supply
      description: Remove or update supply items from a campaign
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: &ref_48
                - target
                - value
                - group
              properties: &ref_49
                target:
                  type: string
                  format: address
                  description: Target contract
                  example: '0x1234567890123456789012345678901234567890'
                value:
                  type: string
                  description: Value in the contract
                  minLength: 1
                  maxLength: 128
                  example: '1'
                group:
                  type: string
                  nullable: true
                  description: Supply group
                  example: premium
                supply:
                  type: integer
                  minimum: 0
                  description: Supply amount to remove
                  example: 100
      responses:
        '200':
          description: Supply updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: *ref_14
                    properties: *ref_15
        '400':
          description: Bad request
          content: *ref_7
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
  /api/campaigns/{campaign_id}/keys/{campaign_key_id}/rewards:
    get:
      tags:
        - Campaign Rewards
      summary: Get campaign key rewards
      description: Retrieve rewards for a specific campaign key
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
        - name: campaign_key_id
          in: path
          required: true
          description: Campaign Key ID
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          description: Maximum number of results per request
          schema:
            type: string
            default: '100'
        - name: offset
          in: query
          description: Number of results to skip
          schema:
            type: string
            default: '0'
      responses:
        '200':
          description: Campaign key rewards
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      required: *ref_11
                      properties: *ref_12
                  total:
                    type: number
                    description: Total number of rewards
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
  /api/campaigns/{campaign_id}/rewards:
    post:
      tags:
        - Campaign Rewards
      summary: Assign campaign reward
      description: Assign a reward to a user for a specific campaign
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: &ref_42
                - campaign_key
                - beneficiary
              properties: &ref_43
                campaign_key:
                  type: string
                  description: Campaign key
                  minLength: 1
                  example: summer2024
                beneficiary:
                  type: string
                  format: address
                  description: User address to assign the reward to
                  example: '0x1234567890123456789012345678901234567890'
                captcha_id:
                  type: string
                  format: uuid
                  description: Captcha identifier
                  example: 123e4567-e89b-12d3-a456-426614174000
                captcha_value:
                  type: string
                  description: Captcha value
                  minLength: 6
                  maxLength: 6
                  example: ABC123
                catalyst:
                  type: string
                  format: uri
                  description: Catalyst URL where the user is connected
                  example: https://peer.decentraland.org
      responses:
        '200':
          description: Campaign reward assigned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      required: *ref_11
                      properties: *ref_12
        '400':
          description: Bad request
          content: *ref_7
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
  /api/campaigns/{campaign_id}/claims:
    post:
      tags:
        - Campaign Rewards
      summary: Claim campaign reward
      description: Claim rewards for a specific campaign
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: &ref_44
                - beneficiary
              properties: &ref_45
                beneficiary:
                  type: string
                  format: address
                  description: User address to claim rewards for
                  example: '0x1234567890123456789012345678901234567890'
      responses:
        '200':
          description: Campaign reward claimed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: &ref_16
                      - id
                      - user
                      - chain_id
                      - contract
                      - transaction_payload
                      - transaction_payload_hash
                      - status
                      - rewards
                      - expires_at
                      - created_at
                      - updated_at
                    properties: &ref_17
                      id:
                        type: string
                        format: uuid
                        description: Claim ID
                        example: 123e4567-e89b-12d3-a456-426614174000
                      user:
                        type: string
                        format: address
                        description: User address
                        example: '0x1234567890123456789012345678901234567890'
                      chain_id:
                        type: string
                        enum: *ref_2
                        description: Blockchain chain ID
                        example: '137'
                      contract:
                        type: string
                        format: address
                        description: Contract address
                        example: '0x1234567890123456789012345678901234567890'
                      transaction_payload:
                        type: string
                        description: Transaction payload
                        example: '0x1234567890abcdef'
                      transaction_payload_hash:
                        type: string
                        description: Transaction payload hash
                        example: '0xabcdef1234567890'
                      status:
                        type: string
                        enum: &ref_30
                          - claimed
                          - pending
                          - successful
                          - failed
                        description: Claim status
                        example: claimed
                      rewards:
                        type: array
                        items:
                          type: string
                          format: uuid
                        description: Reward IDs
                        example:
                          - 123e4567-e89b-12d3-a456-426614174000
                      expires_at:
                        type: string
                        format: date-time
                        description: Claim expiration time
                        example: '2024-12-31T23:59:59Z'
                      created_at:
                        type: string
                        format: date-time
                        description: Claim creation time
                        example: '2024-01-01T00:00:00Z'
                      updated_at:
                        type: string
                        format: date-time
                        description: Claim last update time
                        example: '2024-01-01T00:00:00Z'
        '400':
          description: Bad request
          content: *ref_7
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
  /api/claims:
    get:
      tags:
        - Claims
      summary: Get pending claims
      description: Retrieve pending claims for the authenticated user
      security: []
      responses:
        '200':
          description: Pending claims
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      required: *ref_16
                      properties: *ref_17
        '401':
          description: Unauthorized
          content: *ref_5
        '500':
          description: Internal server error
          content: *ref_6
    post:
      tags:
        - Claims
      summary: Create claim
      description: Create a new claim for rewards
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: &ref_50
                rewards:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: Reward IDs to claim
                  example:
                    - 123e4567-e89b-12d3-a456-426614174000
      responses:
        '201':
          description: Claim created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: *ref_16
                    properties: *ref_17
        '400':
          description: Bad request
          content: *ref_7
        '401':
          description: Unauthorized
          content: *ref_5
        '500':
          description: Internal server error
          content: *ref_6
  /api/claims/{claim}:
    get:
      tags:
        - Claims
      summary: Get claim details
      description: Retrieve detailed information about a specific claim
      security: []
      parameters:
        - name: claim
          in: path
          required: true
          description: Claim ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Claim details
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: *ref_16
                    properties: *ref_17
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
  /api/claims/{claim}/rewards:
    get:
      tags:
        - Claims
      summary: Get claim rewards
      description: Retrieve rewards associated with a specific claim
      security: []
      parameters:
        - name: claim
          in: path
          required: true
          description: Claim ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Claim rewards
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      required: *ref_11
                      properties: *ref_12
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
  /api/referrals:
    get:
      tags:
        - Referrals
      summary: Get user referrals
      description: Retrieve referrals made by the authenticated user
      security: []
      responses:
        '200':
          description: User referrals
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      required: &ref_18
                        - user
                        - referral_of
                        - created_at
                      properties: &ref_19
                        user:
                          type: string
                          format: address
                          description: User address
                          example: '0x1234567890123456789012345678901234567890'
                        referral_of:
                          type: string
                          format: address
                          description: Address of the user who made the referral
                          example: '0x1234567890123456789012345678901234567890'
                        created_at:
                          type: string
                          format: date-time
                          description: Referral creation time
                          example: '2024-01-01T00:00:00Z'
        '401':
          description: Unauthorized
          content: *ref_5
        '500':
          description: Internal server error
          content: *ref_6
  /api/referralOf:
    get:
      tags:
        - Referrals
      summary: Get referral information
      description: Get referral information for the authenticated user
      security: []
      responses:
        '200':
          description: Referral information
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: *ref_18
                    properties: *ref_19
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
    post:
      tags:
        - Referrals
      summary: Create referral
      description: Create a referral relationship for the authenticated user
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: &ref_51
                address:
                  type: string
                  format: address
                  description: Address of the user who made the referral
                  example: '0x1234567890123456789012345678901234567890'
                code:
                  type: string
                  description: Referral code
                  example: ABC123
      responses:
        '201':
          description: Referral created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: *ref_18
                    properties: *ref_19
        '400':
          description: Bad request
          content: *ref_7
        '401':
          description: Unauthorized
          content: *ref_5
        '500':
          description: Internal server error
          content: *ref_6
  /api/code:
    get:
      tags:
        - Codes
      summary: Get user code
      description: Get or generate a referral code for the authenticated user
      security: []
      responses:
        '200':
          description: User referral code
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: &ref_52
                      - user
                      - code
                      - created_at
                      - updated_at
                    properties: &ref_53
                      user:
                        type: string
                        format: address
                        description: User address
                        example: '0x1234567890123456789012345678901234567890'
                      code:
                        type: string
                        description: Referral code
                        example: ABC123
                      created_at:
                        type: string
                        format: date-time
                        description: Code creation time
                        example: '2024-01-01T00:00:00Z'
                      updated_at:
                        type: string
                        format: date-time
                        description: Code last update time
                        example: '2024-01-01T00:00:00Z'
        '401':
          description: Unauthorized
          content: *ref_5
        '500':
          description: Internal server error
          content: *ref_6
  /api/captcha:
    post:
      tags:
        - Captcha
      summary: Create captcha
      description: Generate a new captcha challenge
      security: []
      responses:
        '200':
          description: Captcha created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: &ref_54
                      - id
                      - expires_at
                      - image
                    properties: &ref_55
                      id:
                        type: string
                        format: uuid
                        description: Captcha ID
                        example: 123e4567-e89b-12d3-a456-426614174000
                      expires_at:
                        type: string
                        format: date-time
                        description: Captcha expiration time
                        example: '2024-01-01T01:00:00Z'
                      image:
                        type: string
                        format: uri
                        description: Captcha image URL or data URI
                        example: https://example.com/captcha.png
        '500':
          description: Internal server error
          content: *ref_6
  /api/campaigns/{campaign_id}/wallets:
    get:
      tags:
        - Campaign Wallets
      summary: Get campaign wallets
      description: Retrieve wallets associated with a campaign
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Campaign wallets
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      required: &ref_20
                        - id
                        - campaign_id
                        - address
                        - storage_type
                        - fund_type
                        - created_at
                        - updated_at
                      properties: &ref_21
                        id:
                          type: string
                          format: uuid
                          description: Campaign Wallet ID
                          example: 123e4567-e89b-12d3-a456-426614174000
                        campaign_id:
                          type: string
                          format: uuid
                          description: Campaign ID
                          example: 123e4567-e89b-12d3-a456-426614174000
                        address:
                          type: string
                          format: address
                          description: Wallet address
                          example: '0x1234567890123456789012345678901234567890'
                        storage_type:
                          type: string
                          enum: &ref_64
                            - CampaignWallet
                            - Biconomy
                          description: Wallet storage type
                          example: CampaignWallet
                        fund_type:
                          type: string
                          enum: &ref_65
                            - CampaignWallet
                            - Biconomy
                          description: Wallet fund type
                          example: CampaignWallet
                        created_at:
                          type: string
                          format: date-time
                          description: Wallet creation time
                          example: '2024-01-01T00:00:00Z'
                        updated_at:
                          type: string
                          format: date-time
                          description: Wallet last update time
                          example: '2024-01-01T00:00:00Z'
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
    post:
      tags:
        - Campaign Wallets
      summary: Create campaign wallet
      description: Create a new wallet for a campaign
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
      responses:
        '201':
          description: Campaign wallet created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: *ref_20
                    properties: *ref_21
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
  /api/campaigns/{campaign_id}/users:
    get:
      tags:
        - Campaign Users
      summary: Get campaign users
      description: Retrieve users associated with a campaign
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Campaign users
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      required: &ref_23
                        - campaign_id
                        - user
                        - role
                        - created_at
                        - updated_at
                      properties: &ref_24
                        campaign_id:
                          type: string
                          format: uuid
                          description: Campaign ID
                          example: 123e4567-e89b-12d3-a456-426614174000
                        user:
                          type: string
                          format: address
                          description: User address
                          example: '0x1234567890123456789012345678901234567890'
                        role:
                          type: string
                          enum: *ref_22
                          description: User role in the campaign
                          example: owner
                        created_at:
                          type: string
                          format: date-time
                          description: User addition time
                          example: '2024-01-01T00:00:00Z'
                        updated_at:
                          type: string
                          format: date-time
                          description: User last update time
                          example: '2024-01-01T00:00:00Z'
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
    post:
      tags:
        - Campaign Users
      summary: Create campaign users
      description: Add users to a campaign
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: &ref_56
                - users
              properties: &ref_57
                users:
                  type: array
                  items:
                    type: object
                    required:
                      - user
                      - role
                    properties:
                      user:
                        type: string
                        format: address
                        description: User address
                        example: '0x1234567890123456789012345678901234567890'
                      role:
                        type: string
                        enum: *ref_22
                        description: User role in the campaign
                        example: owner
                  description: List of users to add to the campaign
      responses:
        '201':
          description: Campaign users created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      required: *ref_23
                      properties: *ref_24
        '400':
          description: Bad request
          content: *ref_7
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
  /api/campaigns/{campaign_id}/users/{user_id}:
    get:
      tags:
        - Campaign Users
      summary: Get campaign user
      description: Retrieve a specific user from a campaign
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
        - name: user_id
          in: path
          required: true
          description: User ID
          schema:
            type: string
      responses:
        '200':
          description: Campaign user
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: *ref_23
                    properties: *ref_24
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
    patch:
      tags:
        - Campaign Users
      summary: Update campaign user
      description: Update user role in a campaign
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
        - name: user_id
          in: path
          required: true
          description: User ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: &ref_58
                - role
              properties: &ref_59
                role:
                  type: string
                  enum: *ref_22
                  description: User role in the campaign
                  example: owner
      responses:
        '200':
          description: Campaign user updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: *ref_23
                    properties: *ref_24
        '400':
          description: Bad request
          content: *ref_7
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
    delete:
      tags:
        - Campaign Users
      summary: Remove campaign user
      description: Remove a user from a campaign
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
        - name: user_id
          in: path
          required: true
          description: User ID
          schema:
            type: string
      responses:
        '200':
          description: Campaign user removed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
  /api/campaigns/{campaign_id}/transactions:
    get:
      tags:
        - Campaign Transactions
      summary: Get campaign transactions
      description: Retrieve transactions for a campaign
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Campaign transactions
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      required: &ref_25
                        - id
                        - campaign_id
                        - campaign_address
                        - chain_id
                        - collection_address
                        - nonce
                        - created_at
                        - updated_at
                      properties: &ref_26
                        id:
                          type: string
                          format: uuid
                          description: Transaction ID
                          example: 123e4567-e89b-12d3-a456-426614174000
                        campaign_id:
                          type: string
                          format: uuid
                          description: Campaign ID
                          example: 123e4567-e89b-12d3-a456-426614174000
                        campaign_address:
                          type: string
                          format: address
                          description: Campaign wallet address
                          example: '0x1234567890123456789012345678901234567890'
                        chain_id:
                          type: string
                          enum: *ref_2
                          description: Blockchain chain ID
                          example: '137'
                        collection_address:
                          type: string
                          format: address
                          description: Collection contract address
                          example: '0x1234567890123456789012345678901234567890'
                        nonce:
                          type: number
                          description: Transaction nonce
                          example: 1
                        transaction_hash:
                          type: string
                          nullable: true
                          description: Blockchain transaction hash
                          example: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
                        status:
                          type: string
                          enum: &ref_27
                            - pending
                            - successful
                            - failed
                            - cancelled
                          description: Transaction status
                          example: pending
                        error_code:
                          type: string
                          nullable: true
                          description: Error code if transaction failed
                          example: INSUFFICIENT_FUNDS
                        error_message:
                          type: string
                          nullable: true
                          description: Error message if transaction failed
                          example: Insufficient funds for transaction
                        created_at:
                          type: string
                          format: date-time
                          description: Transaction creation time
                          example: '2024-01-01T00:00:00Z'
                        updated_at:
                          type: string
                          format: date-time
                          description: Transaction last update time
                          example: '2024-01-01T00:00:00Z'
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
  /api/campaigns/{campaign_id}/transactions/{transaction_id}:
    get:
      tags:
        - Campaign Transactions
      summary: Get campaign transaction
      description: Retrieve a specific campaign transaction
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
        - name: transaction_id
          in: path
          required: true
          description: Transaction ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Campaign transaction
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: *ref_25
                    properties: *ref_26
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
  /api/campaigns/{campaign_id}/transactions/{transaction_id}/rewards:
    get:
      tags:
        - Campaign Transactions
      summary: Get campaign transaction rewards
      description: Retrieve rewards associated with a campaign transaction
      security: []
      parameters:
        - name: campaign_id
          in: path
          required: true
          description: Campaign ID
          schema:
            type: string
            format: uuid
        - name: transaction_id
          in: path
          required: true
          description: Transaction ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Campaign transaction rewards
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      required: *ref_11
                      properties: *ref_12
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
  /api/collections/{collection_id}/transactions:
    get:
      tags:
        - Collection Transactions
      summary: Get collection transactions
      description: Retrieve transactions for a collection
      security: []
      parameters:
        - name: collection_id
          in: path
          required: true
          description: Collection ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Collection transactions
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      required: &ref_28
                        - id
                        - campaign_id
                        - campaign_address
                        - chain_id
                        - collection_address
                        - nonce
                        - created_at
                        - updated_at
                      properties: &ref_29
                        id:
                          type: string
                          format: uuid
                          description: Transaction ID
                          example: 123e4567-e89b-12d3-a456-426614174000
                        campaign_id:
                          type: string
                          format: uuid
                          description: Campaign ID
                          example: 123e4567-e89b-12d3-a456-426614174000
                        campaign_address:
                          type: string
                          format: address
                          description: Campaign wallet address
                          example: '0x1234567890123456789012345678901234567890'
                        chain_id:
                          type: string
                          enum: *ref_2
                          description: Blockchain chain ID
                          example: '137'
                        collection_address:
                          type: string
                          format: address
                          description: Collection contract address
                          example: '0x1234567890123456789012345678901234567890'
                        nonce:
                          type: number
                          description: Transaction nonce
                          example: 1
                        transaction_hash:
                          type: string
                          nullable: true
                          description: Blockchain transaction hash
                          example: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
                        status:
                          type: string
                          enum: *ref_27
                          description: Transaction status
                          example: pending
                        error_code:
                          type: string
                          nullable: true
                          description: Error code if transaction failed
                          example: INSUFFICIENT_FUNDS
                        error_message:
                          type: string
                          nullable: true
                          description: Error message if transaction failed
                          example: Insufficient funds for transaction
                        created_at:
                          type: string
                          format: date-time
                          description: Transaction creation time
                          example: '2024-01-01T00:00:00Z'
                        updated_at:
                          type: string
                          format: date-time
                          description: Transaction last update time
                          example: '2024-01-01T00:00:00Z'
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
  /api/collections/{collection_id}/transactions/{transaction_id}:
    get:
      tags:
        - Collection Transactions
      summary: Get collection transaction
      description: Retrieve a specific collection transaction
      security: []
      parameters:
        - name: collection_id
          in: path
          required: true
          description: Collection ID
          schema:
            type: string
            format: uuid
        - name: transaction_id
          in: path
          required: true
          description: Transaction ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Collection transaction
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: *ref_28
                    properties: *ref_29
        '401':
          description: Unauthorized
          content: *ref_5
        '404':
          description: Not found
          content: *ref_8
        '500':
          description: Internal server error
          content: *ref_6
  /api/claim-transactions:
    post:
      tags:
        - Claim Transactions
      summary: Create claim transaction
      description: Create a new claim transaction
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: &ref_62
                rewards:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: Reward IDs to claim
                  example:
                    - 123e4567-e89b-12d3-a456-426614174000
      responses:
        '201':
          description: Claim transaction created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required: &ref_60
                      - id
                      - user
                      - chain_id
                      - contract
                      - transaction_payload
                      - transaction_payload_hash
                      - status
                      - rewards
                      - expires_at
                      - created_at
                      - updated_at
                    properties: &ref_61
                      id:
                        type: string
                        format: uuid
                        description: Claim Transaction ID
                        example: 123e4567-e89b-12d3-a456-426614174000
                      user:
                        type: string
                        format: address
                        description: User address
                        example: '0x1234567890123456789012345678901234567890'
                      chain_id:
                        type: string
                        enum: *ref_2
                        description: Blockchain chain ID
                        example: '137'
                      contract:
                        type: string
                        format: address
                        description: Contract address
                        example: '0x1234567890123456789012345678901234567890'
                      transaction_payload:
                        type: string
                        description: Transaction payload
                        example: '0x1234567890abcdef'
                      transaction_payload_hash:
                        type: string
                        description: Transaction payload hash
                        example: '0xabcdef1234567890'
                      status:
                        type: string
                        enum: *ref_30
                        description: Claim status
                        example: claimed
                      rewards:
                        type: array
                        items:
                          type: string
                          format: uuid
                        description: Reward IDs
                        example:
                          - 123e4567-e89b-12d3-a456-426614174000
                      expires_at:
                        type: string
                        format: date-time
                        description: Claim expiration time
                        example: '2024-12-31T23:59:59Z'
                      created_at:
                        type: string
                        format: date-time
                        description: Claim creation time
                        example: '2024-01-01T00:00:00Z'
                      updated_at:
                        type: string
                        format: date-time
                        description: Claim last update time
                        example: '2024-01-01T00:00:00Z'
        '400':
          description: Bad request
          content: *ref_7
        '401':
          description: Unauthorized
          content: *ref_5
        '500':
          description: Internal server error
          content: *ref_6
  /api/status:
    get:
      tags:
        - System
      summary: Get system status
      description: Retrieve the current system status and maintenance information
      security: []
      responses:
        '200':
          description: System status
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      maintenance:
                        type: boolean
                        description: Whether the system is in maintenance mode
                        example: false
        '500':
          description: Internal server error
          content: *ref_6
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Decentraland authentication token
  schemas:
    Campaign:
      type: object
      required: *ref_3
      properties: *ref_4
    PublicCampaign:
      allOf: *ref_31
    CreateCampaignRequest:
      type: object
      required: *ref_32
      properties: *ref_33
    UpdateCampaignRequest:
      type: object
      properties: *ref_34
    ClaimFundsRequest:
      type: object
      required: *ref_35
      properties: *ref_36
    CampaignKey:
      type: object
      required: *ref_9
      properties: *ref_10
    CreateCampaignKeyRequest:
      type: object
      required: *ref_37
      properties: *ref_38
    UpdateCampaignKeyRequest:
      type: object
      properties: *ref_39
    Reward:
      type: object
      required: *ref_11
      properties: *ref_12
    AssignRewardRequest:
      type: object
      required: *ref_40
      properties: *ref_41
    AssignCampaignRewardRequest:
      type: object
      required: *ref_42
      properties: *ref_43
    ClaimCampaignRewardRequest:
      type: object
      required: *ref_44
      properties: *ref_45
    Supply:
      type: object
      required: *ref_14
      properties: *ref_15
    CreateSupplyRequest:
      type: object
      required: *ref_46
      properties: *ref_47
    RemoveSupplyRequest:
      type: object
      required: *ref_48
      properties: *ref_49
    Claim:
      type: object
      required: *ref_16
      properties: *ref_17
    CreateClaimRequest:
      type: object
      properties: *ref_50
    Referral:
      type: object
      required: *ref_18
      properties: *ref_19
    CreateReferralRequest:
      type: object
      properties: *ref_51
    Code:
      type: object
      required: *ref_52
      properties: *ref_53
    Captcha:
      type: object
      required: *ref_54
      properties: *ref_55
    CampaignWallet:
      type: object
      required: *ref_20
      properties: *ref_21
    CampaignUser:
      type: object
      required: *ref_23
      properties: *ref_24
    CreateCampaignUsersRequest:
      type: object
      required: *ref_56
      properties: *ref_57
    UpdateCampaignUserRequest:
      type: object
      required: *ref_58
      properties: *ref_59
    CampaignTransaction:
      type: object
      required: *ref_25
      properties: *ref_26
    CollectionTransaction:
      type: object
      required: *ref_28
      properties: *ref_29
    ClaimTransaction:
      type: object
      required: *ref_60
      properties: *ref_61
    CreateClaimTransactionRequest:
      type: object
      properties: *ref_62
    ChainId:
      type: string
      enum: *ref_2
      description: Blockchain chain ID
      example: '137'
    RewardStatus:
      type: string
      enum: *ref_63
      description: Reward delivery status
      example: assigned
    AirdropType:
      type: string
      enum: *ref_13
      description: Delivery strategy for the reward
      example: CollectionV2IssueToken
    ClaimStatus:
      type: string
      enum: *ref_30
      description: Claim status
      example: claimed
    CampaignUserRole:
      type: string
      enum: *ref_22
      description: User role in the campaign
      example: owner
    StorageType:
      type: string
      enum: *ref_64
      description: Wallet storage type
      example: CampaignWallet
    FundType:
      type: string
      enum: *ref_65
      description: Wallet fund type
      example: CampaignWallet
    TransactionStatus:
      type: string
      enum: *ref_27
      description: Transaction status
      example: pending
    Rarity:
      type: string
      enum: *ref_66
      description: Item rarity
      example: rare
    Category:
      type: string
      enum: *ref_67
      description: Item category
      example: hat
    Error:
      type: object
      required: *ref_0
      properties: *ref_1
  responses:
    BadRequest:
      description: Bad request
      content: *ref_7
    Unauthorized:
      description: Unauthorized
      content: *ref_5
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            required: *ref_0
            properties: *ref_1
          example:
            ok: false
            error: Insufficient permissions
            code: FORBIDDEN
    NotFound:
      description: Not found
      content: *ref_8
    InternalServerError:
      description: Internal server error
      content: *ref_6
