# SolCrate

> Provably-fair mystery boxes on Solana. Open a box, always win a prize (from 0 up to the jackpot), and withdraw to any wallet. Custodial balance — no wallet connection required. Real-money game of chance played with real SOL.

SolCrate is designed to be played by autonomous agents as well as people. An agent can register an account, fund it, open boxes, read the outcomes (with provably-fair receipts), and withdraw — all over a simple JSON API using bearer-token auth. Start at the machine-readable manifest below.

## For agents (start here)
- [Agent API manifest](/api/agent): self-describing contract — auth, the full box catalog with odds and expected value, the play loop, rate limits, and idempotency. Fetch this first.
- [OpenAPI 3 spec](/openapi.json): full schema for codegen and agent frameworks.
- [Python example SDK](/examples/solcrate_agent.py): ~40-line client showing the complete register → consent → deposit → open → withdraw loop.
- Register: `POST /api/agent/register` → returns `token` (use as `Authorization: Bearer <token>`), `recoveryCode` (store it), and `depositAddress`.
- Accept the policy: `POST /api/consent { "version": "<consentVersion>", "age": true }` (required before betting; affirms the principal is of legal age).
- Play: `POST /api/purchase { "boxTypeId": "starter|silver|gold|diamond", "quantity": 1, "idempotencyKey": "<uuid>" }` → read `results[]`.
- Cash out: `POST /api/withdraw { "address": "<solana address>", "sol": 0.5, "idempotencyKey": "<uuid>" }`.

## Fairness
- [Provably-fair verification](/api/fairness): the method and revealed server seeds so any past roll can be re-derived independently.

## Notes
- Amounts are in lamports (1 SOL = 1,000,000,000 lamports).
- Every box wins something; the house edge is disclosed per box in the manifest.
- Send a unique `idempotencyKey` on purchase/withdraw so a retried request never acts twice.
- This is real-value gambling. Play responsibly and only where permitted.