API REST /api/v1

Salud

• GET /api/v1/health — Estado del servicio y conexión a base de datos. Público.

Jugadores (público)

• GET /api/v1/players/facets — Listas de positions y academy_tags distintas para jugadores con el estado público configurado (PLAYERS_PUBLIC_STATUS en servidor, por defecto active).
• GET /api/v1/players — Listado paginado. Query: page, per_page (máx. 100), q (búsqueda, mín. 2 caracteres), position y academy (coincidencia exacta insensible a mayúsculas). La respuesta incluye meta con totales y filtros aplicados.
• GET /api/v1/players/{slug} — Ficha con milestones y colecciones públicas. Solo status = active en ficha pública.

Ranking y cifras

• GET /api/v1/leaderboard?limit= — Ranking (1–50). Incluye meta.methodology.
• GET /api/v1/stats — Agregados públicos (jugadores, colecciones, NFT, waitlist).

Colecciones y metadata NFT

• GET /api/v1/collections — Colecciones en estado live o planned.
• GET /api/v1/collections/{id} — Detalle de una colección pública.
• GET /api/v1/nft/metadata/{collectionId}/{tokenIndex} — JSON de metadata ERC-721 (requiere fila en nft_tokens).

Lista de interés

• POST /api/v1/waitlist — Cuerpo JSON: email, opcional collection_id (solo si la colección existe y está en estado live o planned), note. Rate limit por IP (BD + hash de IP). Errores 400 / 409 / 429.

Cuenta (sesión por cookie)

Incluir credentials: "include" en fetch desde el mismo origen. Content-Type application/json en POST.

• POST /api/v1/auth/register — email, password.
• POST /api/v1/auth/login — email, password.
• POST /api/v1/auth/logout — Cierra sesión.
• GET /api/v1/me — Usuario actual o 401.
• GET|POST|DELETE /api/v1/wallet y POST /api/v1/wallet/remove — Wallet por chain_id (query o cuerpo). Solo se acepta 137 (Polygon) u 80002 (Amoy); otros valores devuelven 400.
• GET /api/v1/my/nfts — NFT del ledger asignados al usuario.

Mint con voucher (sesión)

Flujo descrito en mint.html: el usuario firma la transacción en MetaMask y paga gas (y mintPrice si aplica). El servidor solo firma un mensaje EIP-191 si existe MINT_SIGNER_PRIVATE_KEY en el entorno y el contrato tiene mintSigner configurado.

• GET /api/v1/mint/status — Público. Indica si la firma de vouchers está configurada.
• GET /api/v1/mint/eligible?chain_id=137 — Ítems reserved del usuario con mint público y contrato en esa red.
• POST /api/v1/mint/voucher — Cuerpo JSON: ledger_id (id de fila en nft_tokens), wallet (0x…, debe coincidir con la wallet vinculada en la cuenta para el chain_id de la colección). Respuesta: contrato, token_id, deadline, signature, mint_price_wei.

Qué queda fuera de esta API

Marketplace y pagos fiat (Stripe/PayPal) no están integrados; el mint en cadena usa el activo nativo de la red (MATIC/POL o ETH de prueba en testnet) según mintPrice. El panel /admin/* es HTML con sesión admin, no parte de la API JSON pública.