# API Reference — The Arena RPS Royale

## Base URL

- Production : `https://api.jeu.cosmolan.fr`
- Local : `http://localhost:3001`

## REST Endpoints

### GET /api/health

Vérification de santé du serveur.

**Response:**
```json
{ "status": "ok", "timestamp": "2026-05-24T10:00:00.000Z" }
```

### GET /api/leaderboard

Classement mondial des 50 meilleurs joueurs.

**Response:**
```json
[
  {
    "rank": 1,
    "address": "0x...",
    "name": "Player1",
    "rating": 1450,
    "wins": 12,
    "losses": 3,
    "profit": "0.45"
  }
]
```

### GET /api/player/:address

Profil détaillé d'un joueur + historique des 20 derniers matchs.

### GET /api/history/:address

Historique complet des matchs d'un joueur (50 derniers).

## Socket.io Events

### Client → Server

| Event | Payload | Description |
|-------|---------|-------------|
| `lobby:join` | - | Rejoint le lobby et reçoit la liste des tables |
| `lobby:leave` | - | Quitte le lobby |
| `match:request` | `{ address: string, betAmount: string }` | Demande un matchmaking |
| `match:commit` | `{ matchId, commitHash, address }` | Envoie le hash du commit |
| `match:reveal` | `{ matchId, choice, nonce, address }` | Révèle le choix et le nonce |
| `match:spectate` | `matchId: string` | Rejoint une table en spectateur |

### Server → Client

| Event | Payload | Description |
|-------|---------|-------------|
| `lobby:tables` | `Table[]` | Liste des tables actives |
| `match:found` | `MatchState` | Match trouvé, transition vers l'arène |
| `match:commitPhase` | `matchId` | Début de la phase de commit |
| `match:commitReceived` | `{ matchId, playerAddress }` | Un joueur a commité |
| `match:suspenseStart` | `matchId` | Début de la phase de suspense (animations) |
| `match:revealPhase` | `matchId` | Début de la phase de reveal |
| `match:revealReceived` | `{ matchId, playerAddress }` | Un joueur a révélé |
| `match:result` | `{ matchId, winner, p1Choice, p2Choice, payout }` | Résultat final |
| `match:error` | `message: string` | Erreur dans le match |
| `match:timeout` | `matchId` | Timeout déclaré |

## Types partagés

Voir `packages/shared/src/types.ts` pour les interfaces TypeScript complètes.