{
  "openapi": "3.1.0",
  "info": {
    "title": "Phylax iG — Outbound Webhook Contract",
    "version": "1.0.0",
    "description": "Phylax sends signed, idempotent webhook events to your PAM receiver. Verify the X-Phylax-Signature header (HMAC-SHA256 of the raw body using your endpoint signing secret), then map event_type to the corresponding action in your wallet/PAM. Phylax never holds player funds."
  },
  "servers": [
    {
      "url": "https://your-pam.example.com",
      "description": "Your PAM receiver"
    }
  ],
  "paths": {
    "/phylax/webhook": {
      "post": {
        "summary": "Receive a signed Phylax interaction event",
        "parameters": [
          {
            "name": "X-Phylax-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "sha256=<hex>"
            },
            "description": "HMAC-SHA256 of the raw request body using your endpoint signing secret."
          },
          {
            "name": "X-Phylax-Event-Id",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "evt_3f9a2b…"
            },
            "description": "Idempotency key. Process each event id at most once."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PhylaxEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event accepted and applied to the PAM."
          },
          "401": {
            "description": "Signature verification failed."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PhylaxEvent": {
        "type": "object",
        "required": [
          "id",
          "type",
          "operator",
          "player_hash_id",
          "fee_eur",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique event / idempotency id."
          },
          "type": {
            "type": "string",
            "enum": [
              "profit_shield",
              "p2p_swap",
              "instant_claim",
              "karma_reseed",
              "win_certificate",
              "piggybank"
            ],
            "description": "Event type → PAM action."
          },
          "operator": {
            "type": "string",
            "description": "Operator slug."
          },
          "player_hash_id": {
            "type": "string",
            "description": "Anonymized player id (no PII)."
          },
          "provider": {
            "type": [
              "string",
              "null"
            ]
          },
          "amount_eur": {
            "type": [
              "number",
              "null"
            ],
            "description": "Amount for money-actions, if any."
          },
          "fee_eur": {
            "type": "number",
            "example": 0.1,
            "description": "Phylax platform micro-fee."
          },
          "pam_action": {
            "type": "string",
            "description": "Plain-English action to perform on the PAM."
          },
          "pii_processed": {
            "type": "boolean",
            "example": false
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    }
  },
  "x-phylax-event-catalog": [
    {
      "type": "profit_shield",
      "label": "Profit Shield Lock",
      "pamAction": "Lock funds in a time-boxed vault",
      "description": "Player elects to lock part of their balance for a fixed window. PAM moves funds from spendable to locked."
    },
    {
      "type": "p2p_swap",
      "label": "P2P Loyalty Swap",
      "pamAction": "Transfer loyalty points between players",
      "description": "Escrowed peer-to-peer loyalty asset swap. PAM debits points from one player and credits another."
    },
    {
      "type": "instant_claim",
      "label": "Instant Claim Insurance",
      "pamAction": "Credit insurance payout to player wallet",
      "description": "On a qualifying disrupted round, PAM credits the insured amount back to the player wallet."
    },
    {
      "type": "karma_reseed",
      "label": "Session Karma Reseed",
      "pamAction": "Rotate provably-fair seed token",
      "description": "Player pays a micro-fee to regenerate their provably-fair seed token."
    },
    {
      "type": "win_certificate",
      "label": "Win Certificate Mint",
      "pamAction": "Mint a permanent win certificate record",
      "description": "Mints a shareable certificate of a notable win to the player profile."
    },
    {
      "type": "piggybank",
      "label": "Piggybank Sweep",
      "pamAction": "Sweep rounding remainder into savings vault",
      "description": "Rounds the player balance down and sweeps the remainder into a savings vault."
    }
  ]
}