# Real Money Pvp

> Builds real-money 1v1 PvP games with matchmaking, PostgreSQL double-entry ledger, match escrow, rake settlement, refunds, and Nuvei deposit/withdraw. Use when creating or extending a paid matchmaking game, implementing escrow or ledger money flows, integrating Nuvei pay-in/payout webhooks, or when the user provides a game mechanics document for a real-money PvP app.

- Skill: `oguzakkuss/real-money-pvp` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add oguzakkuss/real-money-pvp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oguzakkuss/real-money-pvp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: oguzakkuss (https://skillmd.com/u/oguzakkuss)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/oguzakkuss/real-money-pvp

---


# Real-Money PvP

Gerçek paralı 1v1 PvP uygulamaları için sabit finansal/backend iskeleti.
Oyun mekanikleri her projede değişir; para, escrow, settlement ve Nuvei akışları değişmez.

## Ne zaman kullan

- Yeni gerçek paralı PvP / matchmaking uygulaması kurulurken
- Escrow, ledger, rake, refund, deposit, withdraw işleri yapılırken
- Kullanıcı bir oyun dokümantasyonu verip “bu sistemle kur” dediğinde

## Girdi kontrolü (zorunlu)

1. Projede oyun mekanik dokümanını bul (`docs/game.md`, `GAME.md`, veya kullanıcının verdiği path).
2. Yoksa [templates/game-documentation.md](templates/game-documentation.md) şablonunu iste; doldurulmadan oyun loop’u uydurma.
3. Örnek format için [examples/clue-rush.md](examples/clue-rush.md) ve [examples/last-move.md](examples/last-move.md) oku.
4. Ekonomi/iskelet için oyun dokümanındaki “3€/5€/1€” gibi örnek rakamları **yeniden icat etme** — sabit iskeleti uygula; tutarlar proje config’inden gelir.

**Kural:** Sabit iskeleti oyuna uydurma. Oyunu iskelete oturt.

## Sabit iskelet (değiştirme)

Detay: [references/escrow-ledger.md](references/escrow-ledger.md), [references/payments-nuvei.md](references/payments-nuvei.md), [references/architecture.md](references/architecture.md).

### Ledger

- Append-only, double-entry (UPDATE/DELETE yok; düzeltme = ters kayıt).
- Tutarlar: integer cent veya `decimal`; **float yok**.
- Hesaplar:
  - `user_available:{userId}:{currency}`
  - `match_escrow:{matchId}:{currency}`
  - `house_revenue:{currency}`
  - `user_withdraw_hold:{userId}:{currency}`

### Match lifecycle

```
CREATED → FUNDED → IN_PROGRESS → SETTLED
                              ↘ CANCELED (tam refund, rake yok)
```

### Para akışı

| Aşama | Davranış |
|-------|----------|
| Fund | Her oyuncudan `entry_fee` → `match_escrow` (tek DB transaction, her iki oyuncu atomik) |
| Settle | Escrow → kazanan + `house_revenue` (rake); status `SETTLED`; idempotent |
| Cancel | Escrow → her iki `user_available`; status `CANCELED`; rake yok; idempotent |

Varsayılan ekonomi örneği (config ile değişir): entry 3€ + 3€ = 6€ → kazanan 5€, rake 1€.

### PostgreSQL

- Tüm para hareketleri ACID transaction içinde.
- Bakiye yarışı: `SELECT ... FOR UPDATE`.
- Settlement/refund: `status` kontrolü + unique `event_id` / `txn_group_id`.

### Nuvei

- **Nuvei:** gerçek pay-in / pay-out.
- **Ledger:** iç muhasebe, escrow, liability.
- Deposit: intent `PENDING` → webhook SoT → sadece `SUCCEEDED` ile `user_available` CREDIT.
- Withdraw: `available` → `withdraw_hold` → payout → webhook ile `PAID` veya hold geri alma.
- Webhook: signature doğrula, `event_id` ile idempotent, hızlı ACK + queue/worker.

### Realtime

- Server-authoritative; client timestamp’leri otorite değil.
- Disconnect: oyun dokümanındaki grace/cancel politikası; tamamlanamazsa **CANCELED + full refund**.

### Matchmaking (iskelet tamamlaması)

1. Paid queue’ya girmeden `user_available >= entry_fee` kontrol et.
2. Eşleşince tek transaction’da her iki oyuncuyu fund et (`FUNDED`).
3. Fund başarısızsa eşleşmeyi geri al; kısmi düşüm bırakma.
4. Sonra realtime odayı aç (`IN_PROGRESS`).

## Oyundan alınanlar (dokümandan)

Bunları oyun dokümanından çıkar; uydurma:

- Süre, skor, hamle kuralları, beraberlik
- Disconnect / reconnect / forfeit
- Anti-cheat
- Client↔server event’ler ve authoritative state
- Edge case’ler

## Uygulama sırası

1. Accounts + ledger + balance okuma
2. Deposit / withdraw (Nuvei webhook)
3. Match fund / settle / cancel
4. Matchmaking queue → fund → oda
5. Game loop (server-authoritative, dokümana göre)
6. Reconciliation job + withdraw risk/limit politikası

## Çıktı beklentisi

Uygulama veya tasarım üretirken:

- Ledger hareketlerini account + direction + amount ile yaz
- Match status geçişlerini açık tut
- Settlement ve refund’u idempotent yap
- Oyun kurallarını dokümana bağla; çelişki varsa dokümana sor

## Progressive disclosure

- Escrow/settlement adımları → [references/escrow-ledger.md](references/escrow-ledger.md)
- Nuvei deposit/withdraw → [references/payments-nuvei.md](references/payments-nuvei.md)
- Şema, güvenlik, checklist → [references/architecture.md](references/architecture.md)
- Yeni oyun şablonu → [templates/game-documentation.md](templates/game-documentation.md)