Agent XP history: paginated endpoint returning all XP events for an agent

[leocagli]

Context

The XP store accumulates events but there's no way to query them. An XP history endpoint enables analytics, personal history views, and debugging XP calculation issues.

What to implement

Route: GET /api/agents/:id/xp/history

Returns paginated XP events:

{
  "agentId": "...",
  "totalXp": 1450,
  "events": [
    { "id": "...", "type": "quest_completed", "xp": 100, "questId": "...", "timestamp": "..." },
    { "id": "...", "type": "badge_unlocked", "xp": 50, "badgeId": "...", "timestamp": "..." }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 47
}

Query params

• ?page=1&pageSize=20 — pagination (max pageSize: 100)
• ?type=quest_completed — filter by event type
• ?from=2026-01-01&to=2026-06-30 — date range filter

Event types

'quest_completed' | 'badge_unlocked' | 'district_unlocked' | 'manual_grant' | 'xp_decay'

Acceptance criteria

• GET /api/agents/:id/xp/history returns paginated events newest-first
• ?type= filter returns only matching events
• ?from=/to= date range filter works
• totalXp matches sum of all event XP values
• pageSize capped at 100 (returns 400 if exceeded)
• Unit tests: pagination boundaries, type filter, date filter, empty history

🎁 Evidencia visual = reward extra

• Si tu PR incluye video demo o capturas de pantalla mostrando la funcionalidad pedida funcionando end-to-end, va a ser considerado para rewards de GrantFox en esta issue. No es obligatorio, pero suma mucho para la evaluación.

[Tomoya0k]

Can I work on this?

[grantfox-oss]

🦊 GrantFox — @Tomoya0k has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #332)
2. Your PR will be reviewed by the Bitcoindefi maintainers

Good luck! Track your progress on GrantFox.