Agent district map: visual-friendly API endpoint returning district unlock state as GeoJSON-like structure

[leocagli]

Context

Issue #300 adds district unlock progress tracking. This companion issue adds a map-oriented endpoint that returns all districts in a format suitable for visualization — UI clients can render a map of unlocked vs locked districts per agent.

What to implement

Route: GET /api/agents/[id]/districts/map

Response (GeoJSON-like, renderer-agnostic):

{
  "agentId": "bot-1",
  "districts": [
    {
      "id": "sector-alpha",
      "label": "Sector Alpha",
      "status": "unlocked",
      "unlockedAt": 1719432000000,
      "xpRequired": 500,
      "xpAtUnlock": 531
    },
    {
      "id": "sector-beta",
      "label": "Sector Beta",
      "status": "locked",
      "xpRequired": 1500,
      "xpCurrent": 531,
      "progressPct": 35
    }
  ]
}

Static district metadata (lib/districts/district-registry.ts)

Labels and any future display metadata (color, icon slug) live here. Separate from unlock logic.

Acceptance criteria

• Unlocked districts have status: 'unlocked' and unlockedAt timestamp
• Locked districts have status: 'locked' and progressPct
• All configured districts appear in the response (not just unlocked ones)
• xpRequired matches the threshold from issue District unlock progress: track XP toward unlocking each district and expose progress via API #300
• Unit test: 1 unlocked + 2 locked → all 3 in map response with correct status

🎁 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.

[ekwe7]

I would love to work on this issue. I have experience building production ready applications and collaborating through GitHub workflows. I'll carefully analyze the current implementation, propose a reliable solution, and submit a well-tested PR. My focus is on clean code, maintainability, and timely delivery

[Stella112]

Hi, I’d like to work on #306: Agent district map API endpoint returning district unlock state as a GeoJSON-like structure.

I can inspect the existing district/unlock data model, add a focused API endpoint that returns map-friendly district unlock state, and include a small example response or test if the project has an existing test setup.

I’ll keep the PR scoped to the endpoint and avoid unrelated changes.

[grantfox-oss]

🦊 GrantFox — @ekwe7 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 #306)
2. Your PR will be reviewed by the Bitcoindefi maintainers

Good luck! Track your progress on GrantFox.