Python

pip install mmolove-referral

from mmolove_referral import ReferralClient

client = ReferralClient(
    server_id=os.environ["MMOLOVE_SERVER_ID"],
    secret=os.environ["MMOLOVE_REFERRAL_SECRET"],  # Referrals tab
    # endpoint defaults to https://mmolove.gg/api/referral/events
)

# referee_identity is REQUIRED on registered — the first-touch anchor:
client.registered(token, referee_identity="player-7842", server_event_id="reg-7842")

# When they hit your "qualified" bar:
res = client.qualified(token, server_event_id="qual-7842")
if not res.ok:
    print(res.status, res.body)

# config.py — load from env; NEVER hardcode secrets.
import os

MMOLOVE_ENDPOINT = "https://mmolove.com/api/referral/events"
MMOLOVE_SECRET = os.environ["MMOLOVE_REFERRAL_SECRET"]  # from the Referrals tab
MMOLOVE_SERVER_ID = os.environ["MMOLOVE_SERVER_ID"]     # your server id

import hashlib
import hmac
import json
import time
import urllib.error
import urllib.request

ENDPOINT = "https://mmolove.com/api/referral/events"


def mmolove_send_event(secret: str, server_id: str, event: str, extra: dict) -> tuple[int, str]:
    """Report a referral lifecycle event to MMOLove with an HMAC-signed body.

    Returns (status_code, response_body). status_code 0 means a transport error.
    """
    # Build the body ONCE. Sign these exact bytes; send these exact bytes.
    payload = {"event": event, "server_id": server_id, "ts": int(time.time()), **extra}
    raw = json.dumps(payload, separators=(",", ":"))   # compact, stable

    # HMAC-SHA256 over "<t>.<rawBody>" (timestamp, a dot, then the raw body).
    t = int(time.time())
    mac = hmac.new(secret.encode(), f"{t}.{raw}".encode(), hashlib.sha256).hexdigest()
    sig = f"t={t},v1=sha256={mac}"

    req = urllib.request.Request(
        ENDPOINT,
        data=raw.encode(),                              # the SAME bytes we signed
        headers={"Content-Type": "application/json", "X-MMOLove-Signature": sig},
        method="POST",
    )
    try:
        with urllib.request.urlopen(req, timeout=10) as res:  # noqa: S310 (trusted)
            return res.status, res.read().decode()
    except urllib.error.HTTPError as e:
        # 4xx / 5xx come back here — read the JSON error body.
        return e.code, e.read().decode()
    except urllib.error.URLError as e:
        # Transport failure (DNS/timeout). Treat like a 5xx: retry with backoff.
        return 0, str(e)

from flask import request

# In your registration view, BEFORE creating the account.
def capture_mmref():
    return request.args.get("mmref") or request.cookies.get("mmref")

@app.post("/register")
def register():
    mmref = capture_mmref()
    account = create_account(**request.form, mmref=mmref)   # store it
    # ... continue to step 2

from mmolove_referral import mmolove_send_event
from config import MMOLOVE_SECRET, MMOLOVE_SERVER_ID

if account.mmref:
    status, body = mmolove_send_event(MMOLOVE_SECRET, MMOLOVE_SERVER_ID, "registered", {
        "token": account.mmref,                  # the captured token
        "referee_identity": str(account.id),     # STABLE id
        "server_event_id": f"reg-{account.id}",  # idempotency key
    })
    handle_result(status, body)                  # see error handling below

def on_player_qualified(player):
    if not player.mmref:
        return                                   # not a referred player

    status, body = mmolove_send_event(MMOLOVE_SECRET, MMOLOVE_SERVER_ID, "qualified", {
        "token": player.mmref,                   # SAME token as register
        "server_event_id": f"qual-{player.id}",  # NEW idempotency key
    })

    if handle_result(status, body):
        # MMOLove credited the referrer. Now YOU grant the reward in-game.
        grant_referrer_reward(player)

import json

def handle_result(status: int, body: str) -> bool:
    """Return True if the event was accepted (any 200)."""
    try:
        data = json.loads(body)
    except ValueError:
        data = {}

    if status == 200:
        # {"ok": true, ...} — advanced, duplicate, first_touch_conflict, or test.
        # All terminal; do NOT retry.
        return True

    if status == 0 or status >= 500:
        enqueue_retry(status, body)              # backoff; same server_event_id
        return False

    # 4xx — a request bug; retrying won't help.
    print(f"[mmolove] event rejected ({status}): {data.get('error', body)}")
    return False

status, body = mmolove_send_event(MMOLOVE_SECRET, MMOLOVE_SERVER_ID, "registered", {
    "token": "<mmref>",
    "referee_identity": "<player>",
    "server_event_id": "test-1",
    "test": True,                                # dry run — verified, not written
})
# Expect: 200, {"ok":true,"test":true}