> ## Documentation Index
> Fetch the complete documentation index at: https://docs.darkmatter.rdytobash.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Api

> Api — Dark Matter Protocol on Robinhood Chain.

# API Reference

All game APIs are serverless functions under `/api/*` on the app origin. Auth for
money-touching calls is the stateless wallet signature described in
[Crash Money Model](../casino/crash-economy.md#auth--session-model). Responses are
JSON; game state endpoints send `cache-control: no-store`.

## Crash — `/api/crash`

### `GET /api/crash?wallet=0x…&authSig=0x…`

Full state snapshot. Sweeps round commits, settlements and vault deposits before
responding (self-healing — any instance can serve any state).

```json theme={null}
{
  "roundId": 481902,
  "phase": "betting",            // betting | flight | results
  "msLeft": 12345,
  "multiplier": 1.00,
  "crashPoint": null,            // secret until settle
  "edgeBps": 400,
  "history": [{ "roundId": 481901, "crash": 1.87 }],
  "recentWins": [{ "wallet": "0x…", "token": "ETH", "amount": "…", "mult": 2.5, "payout": "…" }],
  "me": { "chips": { "ETH": "…", "USDG": "…" }, "openBet": null, "nonce": 3 },
  "config": { "bounds": { "ETH": { "min": "…", "max": "…" } }, "depositFeeBps": 100 }
}
```

### `GET /api/crash?action=verify-seeds`

Publishes `(seed_hash, seed, pepper)` for the last 12 settled bet-bearing rounds —
the raw fairness disclosure (see [Provably Fair](../casino/crash-fairness.md)).

### `POST /api/crash` actions

| Action | Body (beyond wallet+authSig) | Notes |
| - | - | - |
| `bet` | `token, amountWei` | Debits chips; one open bet per wallet per round; refunds ledger on any failure |
| `cashout` | — | Credits `amount × currentMultiplier`; only while in flight |
| `withdraw` | `token, amountWei, nonce, signature` | Relayer submits `CrashVault.withdraw`; player-signed, gasless |
| `house-topup` | — | Vault-owner-only: surfaces `houseNeedsFunding` when the relayer's gas reserve is low |

## Entropy dice — `/api/entropy`

### `GET /api/entropy`

Public config:

```json theme={null}
{
  "ok": true,
  "games": ["mines", "limbo", "plinko", "keno"],
  "bounds": { "ETH": { "min": "50000000000000", "max": "…" },
               "USDG": { "min": "10000", "max": "500000000" } },
  "plinkoTables": { "low": [...], "medium": [...], "high": [...] }
}
```

### `POST /api/entropy`

```json theme={null}
{ "action": "play", "game": "mines", "token": "ETH", "amountWei": "10000000000000",
  "params": { "mines": 3, "pick": 7 }, "wallet": "0x…", "authSig": "0x…" }
```

Response carries the settled result **with fairness data** (`seedHash`, `seed`, meta
with mine positions / draws / bucket), plus the payout. `action: "recent"` returns
the recent-results feed for the in-app strip.

Games: `mines` (params: `mines`, `pick`), `limbo` (`target`), `plinko` (`risk`,
`bucket` derived server-side), `keno` (`picks[]`).

## Lootbox — `/api/lootbox`

| Endpoint | Purpose |
| - | - |
| `GET /api/lootbox` | Public config: price, pool, prize table, recent wins |
| `POST` (pay → verify flow) | Client sends the payment tx hash; server verifies `to == pool, value == price` on-chain, rolls the tier, pays the prize (stock tiers swap + send xStock directly) |
| `POST` share-to-spin | One free DUST open per UTC day; verifies the shared post via oEmbed |

## LootBox NFT — `/api/lootbox-nft`

| Call | Body | Effect |
| - | - | - |
| `GET ?wallet=…` | — | Your boxes (closed/revealed), tiers, prices, stats |
| `POST action:buy` | `kind` | Server-side buy coordination → client submits payable `LootBoxNFT.buy()` (wallet prompt 1) |
| `POST` (reveal) | `boxId` | Server rolls tier from `keccak(boxId ‖ pepper)` and signs the open commitment (free, no wallet prompt beyond submitting) |
| `POST action:claim` | `boxId` | Verifies the on-chain reveal, credits the DUST prize via `StardustWheel.claimAward` with the same nonce (wallet prompt 3) |

Flow guarantee: **three wallet prompts total, never more** — buy (payable), open
(submits the signed commitment), claim (free DUST cash).

## Wallet bridge — `/api/wallet/*` (vfair platform)

Implements the partner-wallet contract the vfair-games platform calls during
real-money play, backed by the same crash-chip ledger:

```
GET  /api/wallet/balance?playerId=&currency=   → { balance }
POST /api/wallet/transaction                   → { partnerTransactionId, balance, balanceBefore }
```

* Auth: partner **JWT (HS256, ≤30s TTL)** in the Authorization header, verified with
  node:crypto in constant time.
* `playerId` = the player's wallet address; `currency` = chip token (ETH/USDG);
  amounts in whole units (1.0 = 1 token).
* Idempotency keys are **persisted** (`vfair_wallet_txs`) so platform retries can
  never double-move funds.

## RPC proxy — `/api/rpc`

Same-origin JSON-RPC proxy for the Robinhood chain RPCs. The public RPC sends a
malformed CORS header (`Access-Control-Allow-Origin: *,*`), which browsers hard-reject;
the proxy performs upstream calls server-side and answers from our own origin with a
single valid CORS header. Upstreams are allowlisted.

## Rate limits & reliability notes

* Game state endpoints are read-heavy and cheap; they always self-sweep pending
  work before answering.
* Money endpoints verify auth signatures against the current **and previous** 24h
  window — a once-a-day signature is sufficient.
* All ledger mutations are idempotent per round/nonce; replays from clients or the
  platform are safe by construction.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.