# Mahjic

> The free, open rating system for American Mahjong. Play at any club, track your skill, and own your rating forever. Open source algorithm, player-owned ratings, verified identity. Available at mahjic.org.

Mahjic is an ELO-based rating system designed for 4-player American Mahjong. Clubs and leagues ("Verified Sources") submit game results, and Mahjic calculates player ratings using pairwise win-rate comparison adapted for mahjong's 4-player format. The algorithm is open source with no black boxes.

Players get two ratings: a Mahjic Rating (all games) and a Verified Rating (only games against ID-verified opponents, used for official leaderboards). Verified player status costs $30/year and includes Stripe Identity verification to prevent fake accounts.

Any club, league, or platform can apply to become a Verified Source for free. Submission options include web form, spreadsheet upload, or REST API.

## Key Pages

- [Homepage](https://mahjic.org/): Overview of the open rating system, how it works, and pricing
- [Leaderboard](https://mahjic.org/leaderboard): Public rankings of verified American Mahjong players
- [Become a Verified Source](https://mahjic.org/become-a-source): Apply for your club or league to submit games (free)
- [Privacy Policy](https://mahjic.org/privacy): How player data is handled

## How It Works

1. A club joins as a Verified Source (free application)
2. After each session, the club submits game results via web form, spreadsheet, or API
3. Mahjic calculates updated ratings using ELO with pairwise comparison
4. Players view their profile, rating history, and leaderboard position

## Verified Sources

The rating system launched with Bam Good Time (bamgoodtime.com) as its founding Verified Source. Bam Good Time is the multi-tenant club management platform behind 30+ American Mahjong clubs across the United States; every session scored on its platform can flow into Mahjic ratings via the API above. The public leaderboard is live, and verified player rankings grow as sources submit sessions. Becoming a Verified Source is free for any club, league, or platform (apply at /become-a-source). The current count of active Verified Sources is available at GET /api/v1/sources, and the live leaderboard at GET /api/v1/leaderboard.

## Bam Good Time Integration

Bam Good Time clubs submit results to Mahjic automatically, and a club admin can link a player's Bam Good Time account to their Mahjic profile by UUID, so a player's rating follows them across every club they play at.

## Rating Algorithm

- Pairwise comparison: each player at the table is compared against each other player
- Win rate = mahjongs / games_played
- K-factor: 32 (new players) → 24 (mid) → 16 (experienced)
- League/tournament play adds a small points bonus (±5 max)
- Validation: sum(mahjongs) + wall_games = games_played

## API

REST API available for Verified Sources:

- POST /api/v1/sessions — Submit game results (requires API key)
- GET /api/v1/players/[id] — Player profile and rating
- GET /api/v1/leaderboard — Verified player rankings
- GET /api/v1/sources — List of Verified Sources

Authentication is a Bearer API key issued to each Verified Source: `Authorization: Bearer <api_key>`.

Example POST /api/v1/sessions request body:

```json
{
  "session_date": "2026-05-19",
  "game_type": "league",
  "rounds": [
    {
      "wall_games": 1,
      "players": [
        { "bgt_user_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "email": "amy@example.com", "games_played": 4, "mahjongs": 2, "points": 30 },
        { "email": "ben@example.com", "games_played": 4, "mahjongs": 1, "points": 10 },
        { "email": "cara@example.com", "games_played": 4, "mahjongs": 0, "points": -10 },
        { "email": "dee@example.com", "games_played": 4, "mahjongs": 0, "points": -30 }
      ]
    }
  ]
}
```

`game_type` is one of `social`, `league`, or `tournament`. `points` is required for `league` and `tournament` submissions. Each round must satisfy `sum(mahjongs) + wall_games = games_played`. Players are matched by `bgt_user_id` (UUID) first, then `email` fallback, then created as a new provisional player.

## Related

- [Bam Good Time](https://bamgoodtime.com): The club management platform that integrates with Mahjic ratings
- [Mahjic Mahjong for Mac](https://apps.apple.com/app/mahjic-mahjong-for-mac/id6742519175): Native macOS app
- [Mahjic Mahjong for iPhone](https://apps.apple.com/app/mahjic-mahjong/id6743857974): Native iOS app
- [Mahjic Play](https://apps.apple.com/app/mahjic-play/id6745434596): Standalone American Mahjong game