# Challenge

> Challenge is a payment and matchmaking layer for web games. Add real-money 1v1 wagers with one script tag. Challenge handles accounts, payments, KYC, matchmaking, escrow, and payouts. Developers earn 4.5% of every match.

## Quick Facts

- Entry fees: $2 or $5 per player (configured per game at registration)
- Winner receives 85% of prize pool, 10.5% platform fee, 4.5% developer revenue share
- Available in 41 US states (excludes AZ, AR, CT, DE, FL, LA, MT, SC, SD, TN)
- Widget script: one `<script>` tag, no npm package needed
- API key prefixes: `sk_test_` (sandbox), `sk_live_` (production)

## Integration Paths (pick one)

| Path | Winner | Matchmaking | Server code? | Config |
|---|---|---|---|---|
| A (simplest) | Score (highest wins) | Challenge finds opponents | No | `mode: "score"`, `matchmaking: "skill"` |
| B | Your game logic | Challenge finds opponents | No | `mode: "versus"`, `matchmaking: "skill"` |
| C | Score (highest wins) | You find opponents | Yes | `mode: "score"` + SDK |
| D | Your game logic | You find opponents | Yes | SDK `createPairedMatch()` + `reportWinner()` |

**If you want zero server code, use Challenge's matchmaking (Paths A or B).** Custom matchmaking always requires the server SDK.
**If your game has a numeric score, prefer Path A over Path B** — it's more secure because Challenge's server picks the winner.

## Callback Sequence

1. Player clicks Challenge button → widget opens
2. Player authenticates → `onReady({ userId, token, balance, entryFee })`
3. Player clicks "Play Now" inside widget → enters matchmaking queue
4. Opponent found → widget shows countdown → `onMatchStart({ matchId, opponent })`
5. **Start your game immediately. No intermediate screens, lobbies, or countdowns.**
6. During gameplay → call `Challenge.updateScore(score)`, receive `onOpponentScore({ score })`
7. Game ends → call `Challenge.gameEnded({ matchId, score })` (score mode) or `Challenge.showWin()`/`Challenge.showLose()` (versus mode)
8. Challenge shows result screen and handles rematch flow

## Minimal Example (Path A — score mode, no server)

```html
<script src="https://api.withchallenge.com/widget/dist/challenge-widget.js"></script>
```

```javascript
Challenge.init({
  gameId: "your-game-id",       // From Developer Portal — real UUID, never made up
  apiKey: "sk_test_...",        // From Developer Portal → Sandbox page
  mode: "score",
  matchmaking: "skill",
  entryFee: 2,
  showButton: false,

  onReady: (data) => {
    // Player authenticated and funded. Nothing to do — widget shows "Play Now".
  },

  onMatchStart: (match) => {
    // Start gameplay immediately. No loading screens.
    // match.matchId — use for gameEnded()
    // match.opponent — { userId, email, skillRating }
    startYourGame(match.matchId, match.opponent);
  },

  onOpponentScore: (data) => {
    // data.score — opponent's live score (number)
    updateOpponentScoreDisplay(data.score);
  },
});

// Place button inline next to your existing play buttons
Challenge.renderButton("#challenge-button", { size: "lg", fullWidth: true });
```

```javascript
// When game ends — both clients must call this independently
Challenge.gameEnded({
  matchId: currentMatchId,
  score: playerFinalScore,
});
// Challenge compares both scores, settles automatically, shows result screen
```

## Critical Rules

- **Use the official Challenge button only.** Do not create custom buttons, wrappers, or intermediate screens. Use `Challenge.renderButton()` or the floating button. The button must be on the game's main page.
- **Start gameplay immediately when `onMatchStart` fires.** No "Connecting...", no custom lobby, no countdown. The widget already handled pre-game UI.
- **Both clients must call `gameEnded()`.** Challenge waits for both scores before settling.
- **Challenge is a payment layer, not a multiplayer replacement.** If your game has live visual multiplayer (shared boards, spectating), keep your own real-time infrastructure. Challenge only streams a score number via `updateScore`/`onOpponentScore`, not game state.
- **Credentials must come from the Developer Portal.** Never make up game IDs or API keys.

## Sandbox Testing

1. Register at Developer Portal, register a game
2. Get your game ID (UUID) and test API key (`sk_test_...`) from Sandbox page
3. Get Bot 1 and Bot 2 credentials (email + password) from Sandbox page
4. Open two browser tabs with your game
5. Tab 1: click Challenge button, log in as Bot 1
6. Tab 2: click Challenge button, log in as Bot 2
7. Both click "Play Now" → they match → game starts
8. Widget shows orange "TEST MODE" banner

## Documentation

- Full docs: https://www.withchallenge.com/docs
- Detailed reference: https://www.withchallenge.com/llms-full.txt
- Developer Portal: https://app.withchallenge.com