{"openapi":"3.0.3","info":{"title":"SolCrate Agent API","version":"1.0.0","description":"Provably-fair mystery boxes on Solana for autonomous agents. Register an account, fund it with SOL, open boxes, read outcomes, and withdraw. REAL-money game of chance; the house edge is disclosed per box. See /api/agent for the live box catalog with odds and expected value."},"servers":[{"url":"https://solcrate.shop"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"discovery","description":"Machine-readable contract (no auth)"},{"name":"account","description":"Register and account state"},{"name":"play","description":"Open boxes and withdraw"}],"paths":{"/api/agent":{"get":{"tags":["discovery"],"security":[],"operationId":"getManifest","summary":"Self-describing manifest: auth, box catalog with odds/EV, play loop.","responses":{"200":{"description":"Manifest","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/agent/register":{"post":{"tags":["account"],"security":[],"operationId":"register","summary":"Create a fresh account. Returns the bearer token, recovery code, and deposit address.","responses":{"200":{"description":"Account created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/consent":{"post":{"tags":["account"],"operationId":"acceptConsent","summary":"Accept the policy + legal-age confirmation. Required before betting.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentRequest"}}}},"responses":{"200":{"description":"Recorded","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/api/session":{"get":{"tags":["account"],"operationId":"getSession","summary":"Current account state (balance, deposit address, box availability, points).","responses":{"200":{"description":"State","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionState"}}}},"401":{"$ref":"#/components/responses/Error"}}}},"/api/deposits":{"post":{"tags":["account"],"operationId":"checkDeposits","summary":"Scan the deposit address for new transfers and credit them 1:1.","responses":{"200":{"description":"Credited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositResult"}}}},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/purchase":{"post":{"tags":["play"],"operationId":"openBoxes","summary":"Open 1..50 boxes from one balance bucket. Returns each outcome.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseRequest"}}}},"responses":{"200":{"description":"Outcomes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseResponse"}}}},"402":{"$ref":"#/components/responses/Error"},"403":{"description":"consent_required or account under review","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/withdraw":{"post":{"tags":["play"],"operationId":"withdraw","summary":"Withdraw real balance to any Solana address. New addresses age through a cooldown.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawRequest"}}}},"responses":{"200":{"description":"Queued or sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawResponse"}}}},"402":{"$ref":"#/components/responses/Error"},"403":{"description":"Address cooldown or account paused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/fairness":{"get":{"tags":["discovery"],"security":[],"operationId":"getFairness","summary":"Provably-fair method and revealed server seeds for independent verification.","responses":{"200":{"description":"Fairness data","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The `token` from /api/agent/register."}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}},"RegisterResponse":{"type":"object","properties":{"playerId":{"type":"string"},"token":{"type":"string","description":"Bearer token for Authorization header."},"recoveryCode":{"type":"string","description":"Store securely — the only way to recover the account."},"depositAddress":{"type":"string","description":"Solana address to fund with SOL."},"consentRequired":{"type":"boolean"},"consentVersion":{"type":"string"}}},"ConsentRequest":{"type":"object","required":["version","age"],"properties":{"version":{"type":"string","description":"Must equal the current consent version (\"2026-07-18\")."},"age":{"type":"boolean","enum":[true],"description":"Affirm the principal is of legal age and permitted to gamble."}}},"SessionState":{"type":"object","properties":{"id":{"type":"string"},"balanceLamports":{"type":"integer","description":"Real, withdrawable balance."},"bonusLamports":{"type":"integer","description":"Non-withdrawable promo balance (play only)."},"depositAddress":{"type":"string"},"nonce":{"type":"integer"},"points":{"type":"integer"},"consentRequired":{"type":"boolean"},"boxAvailability":{"type":"object","additionalProperties":{"type":"boolean"},"description":"Per box id: is it currently sellable."}}},"DepositResult":{"type":"object","properties":{"creditedLamports":{"type":"integer"},"balanceLamports":{"type":"integer"}}},"PurchaseRequest":{"type":"object","required":["boxTypeId"],"properties":{"boxTypeId":{"type":"string","enum":["starter","silver","gold","diamond"]},"quantity":{"type":"integer","minimum":1,"maximum":50,"default":1},"idempotencyKey":{"type":"string","description":"Unique per action (UUID). Replays return the original result."}}},"PrizeOutcome":{"type":"object","properties":{"tier":{"type":"object","properties":{"name":{"type":"string"},"tier":{"type":"integer"}}},"prizeSol":{"type":"number"},"roll":{"type":"integer","description":"0..9999, provably-fair."},"nonce":{"type":"integer"}}},"PurchaseResponse":{"type":"object","properties":{"count":{"type":"integer"},"boxTypeId":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/PrizeOutcome"}},"balanceLamports":{"type":"integer"},"bonusLamports":{"type":"integer"},"points":{"type":"integer"},"totalPriceLamports":{"type":"integer"},"totalPrizeLamports":{"type":"integer"},"serverSeedHash":{"type":"string"},"clientSeed":{"type":"string"}}},"WithdrawRequest":{"type":"object","required":["address","sol"],"properties":{"address":{"type":"string","description":"Destination Solana address."},"sol":{"type":"number","minimum":0.01},"idempotencyKey":{"type":"string","description":"Unique per action (UUID)."}}},"WithdrawResponse":{"type":"object","properties":{"withdrawalId":{"type":"string"},"status":{"type":"string","enum":["sent","pending"]},"txSignature":{"type":"string","nullable":true},"balanceLamports":{"type":"integer"},"message":{"type":"string"}}}}}}