openapi: 3.0.3
info:
  title: Decentraland Events Notifier API
  description: |
    ## Overview
    The Events Notifier API is a service that processes and forwards blockchain and web events from the Decentraland ecosystem. 
    It handles events from various sources including the Decentraland Explorer, web applications, and blockchain data sources.

    ### Key Features
    - **Event Processing**: Processes and validates events from multiple sources
    - **Blockchain Integration**: Monitors blockchain events for marketplace activities, rentals, and collections
    - **Web Event Handling**: Processes web analytics events with user validation
    - **Admin Operations**: Provides administrative endpoints for managing event producers and user data
    - **Security**: Implements signature validation and authentication for secure event processing

    ### Event Types
    - **Client Events**: User interactions within the Decentraland Explorer (movement, emotes, login, etc.)
    - **Web Events**: Analytics events from web applications
    - **Blockchain Events**: Marketplace transactions, rentals, and collection activities

    ### Authentication
    Most endpoints require authentication via bearer tokens or signature validation. Admin endpoints require additional authorization

    ### Endpoints
    - **Forward Explorer Events**: `/forward`
    - **Forward Web Events**: `/forward-web`
    - **Forward Blockchain Events**: `/forward-blockchain`
    - **Set Producer Cursor**: `/producers/{producer}/set-since`
    - **Retrieve Anonymous IDs**: `/admin/anonids`
    - **Unflag Anonymous IDs**: `/admin/anonids/unflag`

    ### Security
    - **Signature Validation**: HMAC-SHA1 signature validation for event validation
    - **Bearer Token Authentication**: Bearer token authentication for admin endpoints
    - **Anonymous ID Validation**: Anonymous ID validation and flagging for web events
    - **Event Validation**: Event validation for client events
    - **Web Event Validation**: Web event validation for web events
  version: 1.0.0
  contact:
    name: Decentraland Foundation
    url: https://decentraland.org
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: https://events-notifier.decentraland.org
    description: Production server
  - url: https://events-notifier.decentraland.zone
    description: Development server
tags:
  - name: Event Forwarding
    description: Endpoints for forwarding events from external sources
  - name: Admin
    description: Administrative endpoints for managing the service
  - name: Producer Management
    description: Endpoints for managing event producers
  - name: Blockchain Events
    description: Endpoints for forwarding blockchain events with signed fetch authentication
paths:
  /forward:
    post:
      tags:
        - Event Forwarding
      summary: Forward Explorer Events
      description: |
        Forwards events from the Decentraland Explorer client. This endpoint processes and validates 
        client-side events such as user movement, emotes, login events, and other in-world interactions.

        Events are validated for:
        - Signature authenticity using HMAC-SHA1
        - AuthChain validation for user authentication
        - Event structure and content validation
        - User address verification

        Supported event types:
        - `move_to_parcel`: User movement between parcels
        - `used_emote`: Emote usage events
        - `passport_opened`: Passport interaction events
        - `walked_distance`: Movement tracking
        - `vertical_height_reached`: Height-based achievements
        - `logged_in`: User login events
        - `logged_in_cached`: Cached login events
      operationId: forwardExplorerEvents
      security:
        - SignatureAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Explorer client event data
              properties:
                event:
                  type: string
                  description: Event type identifier
                  example: move_to_parcel
                messageId:
                  type: string
                  description: Unique message identifier
                  example: msg_123456789
                anonymousId:
                  type: string
                  description: Anonymous user identifier
                  example: anon_abc123
                userId:
                  type: string
                  description: User identifier (if available)
                  example: '0x1234567890abcdef'
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp
                sentAt:
                  type: string
                  format: date-time
                  description: When the event was sent
                receivedAt:
                  type: string
                  format: date-time
                  description: When the event was received
                context:
                  type: object
                  description: Event context information
                  properties:
                    auth_chain:
                      type: string
                      description: JSON string of authentication chain
                    dcl_eth_address:
                      type: string
                      description: User's Ethereum address
                      example: '0x1234567890abcdef'
                    session_id:
                      type: string
                      description: Session identifier
                    realm:
                      type: string
                      description: Realm identifier
                      example: main
                    realm_url:
                      type: string
                      description: Realm URL
                    dcl_renderer_type:
                      type: string
                      description: Renderer type
                      example: Desktop
                    launcher_anonymous_id:
                      type: string
                      description: Launcher anonymous ID
                    ip:
                      type: string
                      description: IP address
                    parcel:
                      type: string
                      description: Parcel coordinates (for movement events)
                    position:
                      type: string
                      description: 3D position coordinates
                    runtime:
                      type: string
                      description: Runtime information
                properties:
                  type: object
                  description: Event-specific properties
                  additionalProperties: true
      responses:
        '200':
          description: Event successfully processed and forwarded
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
        '400':
          description: Invalid event data
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid event
                  ok:
                    type: boolean
                    example: false
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid signature
                  ok:
                    type: boolean
                    example: false
  /forward-web:
    post:
      tags:
        - Event Forwarding
      summary: Forward Web Events
      description: |
        Forwards events from web applications and analytics platforms. This endpoint processes 
        web-based events such as page views, user interactions, and analytics data.

        Events are validated for:
        - Signature authenticity using HMAC-SHA1
        - Event structure validation
        - User context validation (if Ethereum address is present)
        - Anonymous ID validation and flagging

        This endpoint supports Segment-compatible web events and includes special handling
        for authentication events that link anonymous IDs to Ethereum addresses.
      operationId: forwardWebEvents
      security:
        - SignatureAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Web event data
              properties:
                type:
                  type: string
                  description: Event type
                  example: track
                messageId:
                  type: string
                  description: Unique message identifier
                  example: msg_web_123456
                anonymousId:
                  type: string
                  description: Anonymous user identifier
                  example: anon_web_abc123
                userId:
                  type: string
                  description: User identifier (if available)
                  example: '0x1234567890abcdef'
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp
                sentAt:
                  type: string
                  format: date-time
                  description: When the event was sent
                receivedAt:
                  type: string
                  format: date-time
                  description: When the event was received
                originalTimestamp:
                  type: string
                  format: date-time
                  description: Original event timestamp
                context:
                  type: object
                  description: Event context information
                  properties:
                    page:
                      type: object
                      properties:
                        path:
                          type: string
                          description: Page path
                        url:
                          type: string
                          description: Full page URL
                        title:
                          type: string
                          description: Page title
                        referrer:
                          type: string
                          description: Referrer URL
                        search:
                          type: string
                          description: Query parameters
                    userAgent:
                      type: string
                      description: User agent string
                    userAgentData:
                      type: object
                      description: User agent data
                    locale:
                      type: string
                      description: User locale
                    library:
                      type: object
                      properties:
                        name:
                          type: string
                        version:
                          type: string
                    timezone:
                      type: string
                      description: User timezone
                    ip:
                      type: string
                      description: IP address
                traits:
                  type: object
                  description: User traits
                  properties:
                    ethAddress:
                      type: string
                      description: Ethereum address
                      example: '0x1234567890abcdef'
                    chainId:
                      type: integer
                      description: Blockchain chain ID
                integrations:
                  type: object
                  description: Integration settings
                projectId:
                  type: string
                  description: Project identifier (for specific event types)
      responses:
        '200':
          description: Event successfully processed and forwarded
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  validationPassed:
                    type: integer
                    description: Whether validation passed (1) or failed (0)
                    example: 1
        '400':
          description: Invalid event data
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid web event
                  ok:
                    type: boolean
                    example: false
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid signature
                  ok:
                    type: boolean
                    example: false
  /forward-blockchain:
    post:
      tags:
        - Blockchain Events
      summary: Forward Blockchain Events
      description: |
        Forwards blockchain events using ADR-44 signed fetch authentication.
        Currently supports tip events (MANA transfers). Validates the transaction on-chain
        by decoding the meta-transaction to verify sender, receiver, and amount.

        Supported event types:
        - `tip_received`: MANA tip transfers via meta-transaction

        Requests from scenes (`decentraland-kernel-scene`) are blocked.
      operationId: forwardBlockchainEvents
      security:
        - SignedFetchAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
                - transactionHash
              properties:
                type:
                  type: string
                  description: Blockchain event type
                  enum:
                    - tip_received
                  example: tip_received
                transactionHash:
                  type: string
                  description: Transaction hash of the meta-transaction. The receiver and amount are extracted from the transaction data.
                  example: '0x5e9f2231e36f3c7a1c23f1485d2f61b7718f9830b0b5a7d37c07f1e4f2c6d1aa'
      responses:
        '204':
          description: Blockchain event accepted and forwarded
        '400':
          description: Invalid request data or transaction mismatch
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid transactionHash
        '401':
          description: Signed fetch authentication failed or expired
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Missing signer address
        '403':
          description: Transaction sender mismatch
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Transaction sender mismatch
        '409':
          description: Transaction not mined or not sufficiently confirmed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Transaction not confirmed yet
        '500':
          description: Internal error publishing the event
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Failed to publish blockchain event
  /producers/{producer}/set-since:
    post:
      tags:
        - Producer Management
      summary: Set Producer Cursor
      description: |
        Sets the cursor (timestamp) for a specific event producer to control from which point 
        the producer should start processing events. This is useful for:
        - Resetting a producer to a specific point in time
        - Recovering from errors by reprocessing events
        - Manual intervention in event processing

        Available producers:
        - `item-sold`: Processes item sale events
        - `item-published`: Processes item publication events
        - `royalties-earned`: Processes royalty earning events
        - `bid-received`: Processes bid received events
        - `bid-accepted`: Processes bid accepted events
        - `rental-started`: Processes rental start events
        - `rental-ended`: Processes rental end events
        - `collection-created`: Processes collection creation events
      operationId: setProducerCursor
      security:
        - BearerAuth: []
      parameters:
        - name: producer
          in: path
          required: true
          description: Producer identifier
          schema:
            type: string
            enum:
              - item-sold
              - item-published
              - royalties-earned
              - bid-received
              - bid-accepted
              - rental-started
              - rental-ended
              - collection-created
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - since
              properties:
                since:
                  type: string
                  format: date-time
                  description: ISO 8601 timestamp from which to start processing events
                  example: '2024-01-01T00:00:00.000Z'
      responses:
        '204':
          description: Producer cursor successfully set
        '400':
          description: Invalid request data
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Invalid request: missing ''since''.'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not authorized
        '404':
          description: Producer not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Invalid producer: unknown-producer'
  /admin/anonids:
    post:
      tags:
        - Admin
      summary: Retrieve Anonymous IDs
      description: |
        Retrieves anonymous ID associations for given wallet addresses. This endpoint allows 
        administrators to query the relationship between anonymous IDs and wallet addresses 
        for investigation and management purposes.

        The response includes:
        - All anonymous IDs associated with each provided wallet
        - All wallet addresses linked to each anonymous ID
        - This data is useful for detecting multi-accounting and fraud patterns
      operationId: retrieveAnonymousIds
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - wallets
              properties:
                wallets:
                  type: array
                  items:
                    type: string
                    pattern: ^0x[a-fA-F0-9]{40}$
                    description: Ethereum wallet address
                  description: Array of wallet addresses to query
                  example:
                    - '0x1234567890abcdef1234567890abcdef12345678'
                    - '0xabcdef1234567890abcdef1234567890abcdef12'
      responses:
        '200':
          description: Anonymous ID associations retrieved successfully
          content:
            application/json:
              schema:
                type: object
                description: Mapping of wallet addresses to their anonymous ID associations
                additionalProperties:
                  type: array
                  items:
                    type: object
                    properties:
                      anonId:
                        type: string
                        description: Anonymous ID
                        example: anon_abc123
                      walletsLinkedToAnonId:
                        type: array
                        items:
                          type: string
                        description: All wallet addresses linked to this anonymous ID
                        example:
                          - '0x1234567890abcdef1234567890abcdef12345678'
                          - '0xabcdef1234567890abcdef1234567890abcdef12'
        '400':
          description: Invalid request data
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Missing or invalid wallets.
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not authorized
  /admin/anonids/unflag:
    post:
      tags:
        - Admin
      summary: Unflag Anonymous IDs
      description: |
        Removes flags from anonymous IDs by clearing their associated cache entries. This 
        endpoint is used to reset the flagging status of anonymous IDs that have been 
        flagged for multi-accounting or other suspicious activities.

        The operation:
        - Clears cache entries for the specified anonymous IDs
        - Removes wallet associations from the cache
        - Returns detailed information about what was cleared
        - Does not affect the underlying blockchain data
      operationId: unflagAnonymousIds
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - anonIds
              properties:
                anonIds:
                  type: array
                  items:
                    type: string
                  description: Array of anonymous IDs to unflag
                  example:
                    - anon_abc123
                    - anon_def456
      responses:
        '200':
          description: Anonymous IDs unflagged successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Anonymous IDs unflagged successfully by clearing cache entries
                  unflaggedData:
                    type: array
                    items:
                      type: object
                      properties:
                        anonId:
                          type: string
                          description: Anonymous ID that was unflagged
                          example: anon_abc123
                        walletsUnflagged:
                          type: array
                          items:
                            type: string
                          description: Wallet addresses that were unflagged
                          example:
                            - '0x1234567890abcdef1234567890abcdef12345678'
                        cachesCleared:
                          type: array
                          items:
                            type: string
                          description: Cache keys that were cleared
                          example:
                            - wallets:anonids:anon_abc123
                  totalAnonIds:
                    type: integer
                    description: Total number of anonymous IDs processed
                    example: 2
                  totalWalletsAffected:
                    type: integer
                    description: Total number of wallets affected
                    example: 3
        '400':
          description: Invalid request data
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Missing or invalid anonIds. All anonIds must be strings.
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not authorized
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token authentication for admin endpoints
    SignatureAuth:
      type: apiKey
      in: header
      name: x-signature
      description: HMAC-SHA1 signature for event validation
    SignedFetchAuth:
      type: apiKey
      in: header
      name: X-Identity-AuthChain-0
      description: |
        ADR-44 signed fetch headers (X-Identity-AuthChain-*, X-Identity-Timestamp, X-Identity-Metadata).
  schemas: {}
