docs: Add CEX Singleton Wallet integration guide

guides/cex-singleton-wallet.md

@@ -0,0 +1,131 @@
+# CEX Singleton Wallet Integration Guide
+
+This guide is for exchanges that want to offer Polymarket trading with **minimal integration complexity** — the CEX operates a single wallet on Polymarket and manages all user accounting internally. Users never interact with Polymarket directly.
+
+If your exchange deploys a separate wallet per user, see the [direct CEX](direct-cex-integration.md) guide instead. For the self-custodial model, see [`cex-dex-integration.md`](cex-dex-integration.md). For a more general omnibus approach, see [`omnibus-account-model.md`](omnibus-account-model.md).
+
+## Overview
+
+In this model, the CEX operates **one Polymarket wallet** (the "Singleton Wallet") that executes all trades on behalf of all users. Users see prediction markets as another product on the exchange — alongside spot, futures, etc. — but behind the scenes, a single wallet holds all positions on Polymarket. The CEX tracks per-user balances and positions entirely through its own internal ledger.
+
+This is the simplest integration architecture. There's no per-user wallet deployment, no per-user key management, and no blockchain interaction from the user's perspective.
+
+## Architecture
+
+### Three Layers
+
+**User** — Interacts only with the CEX. Submits buy/sell intents for Polymarket positions. Sees a representation of their position in the CEX interface. Never touches a wallet, gas, or Polymarket APIs.
+
+**CEX Backend Service** — The exchange's own infrastructure. Handles:
+- Internal accounting (lock/deduct user USD or positions)
+- Translating user intents into trade instructions for the Singleton Wallet
+- Delivering position representations and USD back to users
+- Fee collection (the CEX can charge any spread or fee since users never see Polymarket prices directly)
+
+**CEX Singleton Wallet** — A single EOA + Safe that the CEX operates on Polymarket. This wallet:
+- Holds all Polymarket positions (CTF tokens) for all users
+- Submits taker orders to the Polymarket Order Book
+- Receives positions (on buys) and USDC (on sells)
+- Reports execution results back to the CEX Backend
+
+**Polymarket Order Book** — The CLOB that matches orders. From Polymarket's perspective, all activity comes from one wallet — no different from any other trader.
+
+## Buy Flow
+
+![CEX Singleton Wallet — Buy Flow](../assets/cex-singleton-buy.png)
+
+1. **User** submits "Buy Polymarket Position" to the CEX
+2. **CEX Backend** locks the user's USD (internal ledger)
+3. **CEX Backend** instructs the Singleton Wallet to buy the position on Polymarket
+4. **Singleton Wallet** submits a taker BUY order to the Polymarket Order Book
+5. **Polymarket** fills the order — Singleton Wallet receives the position (CTF tokens)
+6. **Singleton Wallet** confirms "Position Received" to the CEX Backend
+7. **CEX Backend** deducts the user's USD and delivers a **representation** of the Polymarket position
+
+## Sell Flow
+
+![CEX Singleton Wallet — Sell Flow](../assets/cex-singleton-sell.png)
+
+1. **User** submits "Sell Polymarket Position" to the CEX
+2. **CEX Backend** locks the user's position (internal ledger)
+3. **CEX Backend** instructs the Singleton Wallet to sell the position on Polymarket
+4. **Singleton Wallet** submits a taker SELL order to the Polymarket Order Book
+5. **Polymarket** fills the order — Singleton Wallet receives USDC
+6. **Singleton Wallet** confirms "USD Received" to the CEX Backend
+7. **CEX Backend** deducts the user's position and delivers USD
+
+## Redemption Flow
+
+When a market resolves, the Singleton Wallet redeems winning positions in bulk. The CEX Backend credits individual users based on its internal ledger — the same way it handles any other settlement.
+
+## Operational Considerations
+
+### Funding the Singleton Wallet
+
+The only operational requirement is keeping the Singleton Wallet funded with USDC to execute buys. For a CEX, this is straightforward — the internal accounting always balances (user USD locked = USDC spent on Polymarket), and the CEX can top up the wallet from its own reserves.
+
+| Path | How It Works |
+|------|-------------|
+| **Direct Polygon transfer** | Send USDC.e on Polygon from a CEX hot wallet to the Singleton Wallet's Safe address |
+| **Bridge API** | Call `POST /deposit` with the Safe address to get deposit addresses on other chains, then fund from there |
+
+### Gas
+
+Gas costs for on-chain settlement are generally sponsored by Polymarket, so this is not a concern for the CEX.
+
+### Fees
+
+Since users never interact with Polymarket directly, the CEX has full control over pricing. The CEX can charge any spread, commission, or fee structure it chooses — users only see the CEX's quoted prices.
+
+### How This Differs from Other Models
+
+| | Singleton Wallet | Direct CEX | CEX / Self-Custodial | Omnibus |
+|---|---|---|---|---|
+| **Wallets** | One for all users | One Safe per user | One self-custodial wallet per user | One or a few for all users |
+| **Key management** | One EOA | One EOA per user | User or CEX manages per-user keys | One or a few EOAs |
+| **User experience** | Native CEX product | Native CEX product | User switches between CEX and wallet | Varies |
+| **Safe deployments** | One | Per user | Per user | One or a few |
+| **Complexity** | Lowest | Medium | Medium-High | Low |
+
+## Mapping to the Integration Guide
+
+The [main guide](../README.md) documents 9 phases. The Singleton Wallet model simplifies several of them.
+
+### Phase 1: Wallet Infrastructure
+
+The simplest setup — one wallet for the entire integration:
+
+- **One EOA** managed by the CEX
+- **One Safe** derived and deployed via Relay
+- **One set of token approvals**
+- **One set of CLOB API credentials**
+
+The standard lifecycle (Relay init, derive Safe, deploy, approvals, derive API creds) runs **once**, not per user. See [Phase 1](../README.md#phase-1-wallet-infrastructure) in the main guide.
+
+### Phase 2: Market Discovery
+
+Same as all architectures — Gamma API for events, markets, and metadata. Feed this data into the CEX's product catalog to display to users.
+
+### Phase 3: Trading
+
+The CEX Backend translates user buy/sell intents into CLOB orders signed by the Singleton Wallet. All orders appear as the Singleton Wallet on the CLOB. The CEX's internal ledger attributes each trade to the originating user.
+
+### Phase 4: Position Management
+
+The CEX's internal ledger is the source of truth for per-user positions. The Data API shows positions for the Singleton Wallet as a whole — useful for reconciliation, not for per-user queries.
+
+### Phase 5 & 6: Resolution and Redemption
+
+The Singleton Wallet redeems winning positions in bulk. The CEX credits individual users via its internal ledger.
+
+### Phase 7: Geoblocking
+
+Still applies — the CEX must enforce geographic restrictions on its users.
+
+### Phase 8: Real-Time Data
+
+WebSocket feeds (order book updates, fills, events) feed into the CEX Backend to keep user-facing data current.
+
+### Phase 9: Deposits & Withdrawals
+
+See [Funding the Singleton Wallet](#funding-the-singleton-wallet) above. Users deposit/withdraw through the CEX's normal flows — fiat or crypto. The CEX manages the Singleton Wallet's USDC balance separately.