# Rommy game integration: agent quickstart

Canonical starting page: https://rommygames.com/developers/docs/getting-started
This text is the implementation companion to that page, not a separate onboarding flow. For automated retrieval, use https://rommygames.netlify.app with the same paths when the public brand domain presents a browser challenge. The machine-facing links below already use that origin.
Agent task: Read this guide and the OpenAPI, inspect the existing game, then connect a quiz checkpoint with authenticated learner progress. Keep credentials in protected configuration and verify the complete answer/retry loop.

## Start with the example

Public preview: https://rommygames.netlify.app/examples/checkpoint-game/index.html?preview=1
Runnable starter: https://rommygames.netlify.app/examples/checkpoint-game.zip

The public preview runs local sample questions. It needs no account, makes no live Rommy API calls and does not save learner progress. Follow the downloaded README for run commands and configuration. Live mode requires your own entitled project and API key; preview success does not verify a live integration. The local example is for a developer's test learner; replace its demo identity with your application's authenticated player mapping before deployment. Adapt the checkpoint to your game loop: pause play, display a question, acknowledge the answer, then resume play.

## References and origins

Developer documentation: https://rommygames.netlify.app/developers/docs
Effective REST origin: https://rommygames.netlify.app
REST base path: /api/public/v1
Public OpenAPI: https://rommygames.netlify.app/api/public/v1/openapi.json
Widget guide: https://rommygames.netlify.app/developers/docs/embed-widget
Runtime API guide: https://rommygames.netlify.app/developers/docs/public-api
Project setup: https://rommygames.netlify.app/api-portal/onboarding
Pricing and entitlement: https://rommygames.netlify.app/developers/pricing

Use the explicit REST origin for new server integrations. Keep an existing pending journal bound to its original API origin and project until reconciled. The canonical human documentation remains on rommygames.com; these machine-facing documentation and download links use the same paths on the REST origin to avoid browser challenges.

## Wallet access without manual API-key setup (developer preview)

Guide: https://rommygames.netlify.app/developers/docs/agent-payments
Node helper and simulated tests: https://github.com/kylewalsh525/EduRoms/tree/master/integrations/x402
Live availability: https://mcp.rommygames.com/api/public/v1/x402/config

Live purchases remain disabled until the merchant configures a receiving wallet, price, credits and production facilitator. Require enabled:true from the configuration endpoint. This path uses native USDC on Base (eip155:8453) and externally owned wallets. It creates a private prepaid project through wallet sign-in and automatically renews scoped 15-minute rma1_ credentials. No developer-console API key is created. Wallet/provider secrets and automatic project credentials stay on the backend; the learner receives only a session token. Ordinary MCP clients do not automatically become payment-aware.

Use an independently approved recipient and spending cap. Sign-in spends nothing; purchasing must be an explicit application decision. The helper persists the purchase ID and exact signed authorization before sending. Reuse them after uncertainty; settlement_unknown requires merchant reconciliation, never another charge. One confirmed answer debits one credit atomically with progress; exact replay is free. Zero balance preserves progress reads, renewal and committed retries. Offline imports and administrative progress edits are unavailable on prepaid projects. Use the normal session/widget loop below with automatic credentials in the protected X-Rommy-Api-Key header. Existing subscription integrations continue unchanged.

## Connect a subscription project

1. Set up a tenant/project and API key in the API Portal. The project must be active with an active or trialing subscription. A key alone does not grant entitlement; 402 subscription_required is a setup/billing outcome.
2. Store ROMMY_API_KEY only in your backend's protected environment/secret configuration. Configure ROMMY_API_BASE_URL=https://rommygames.netlify.app. Never put the key in prompts, source control, frontend environment variables, browser/mobile bundles, ROMs, query strings or logs. Ask the owner to configure a missing secret through their hosting/client settings.
3. For the widget, record the game's intended production HTTPS origin in the project's allowedOrigins. This stored setting is not currently an enforced frame allowlist; control access through your authenticated backend and token ownership checks. Local loopback setup is described in the starter README. Use sessions:create for session operations and progress:read for progress reads. Grant other scopes only when needed.
4. Authenticate your game's user on your backend. Map that trusted identity to a stable, opaque externalLearnerId in your project. Bind each created session to that identity. Authorize every refresh and progress request; a caller-supplied learner or session ID is not proof of ownership. These IDs do not automatically pair with existing Rommy Games student accounts. Use your application's CSRF protections on cookie-authenticated writes.

## Implement the session and question loop

All paths below are relative to the REST origin. Use Content-Type: application/json for JSON bodies.

- Your backend: POST /api/public/v1/sessions with X-Rommy-Api-Key and a persisted Idempotency-Key. Minimal body: {"externalLearnerId":"your-server-mapped-player-id","mode":"overlay","context":{"gradeLevel":"3","subject":"math"}}. The response contains sessionId, clientToken and widgetUrl. Use the current OpenAPI for optional filters and response schemas.
- Hosted widget: load https://rommygames.netlify.app/rommy-embed.js, then call window.mountRommyWidget({mode:"overlay", widgetUrl, token:clientToken, refreshToken:yourBackendRefreshCallback}). Call widget.open() at the game's checkpoint. Follow the widget guide for events, focus, themes and answerJournal; keep the game paused until the checkpoint is resolved. The widget handles question presentation and the answer loop.
- Custom UI: create with mode:"headless". GET /api/public/v1/sessions/{sessionId}/next using Authorization: Bearer <clientToken>. Read question.questionText and question.choices; handle success:false/no available question. POST /api/public/v1/sessions/{sessionId}/answers with the same bearer token, Idempotency-Key and {questionId,choiceIndex,responseTimeMs}. choiceIndex is zero-based. Read result.isCorrect from a successful answer response.
- Your backend: GET /api/public/v1/learners/{externalLearnerId}/summary or /topics using X-Rommy-Api-Key. URL-encode the learner ID. Summary fields include stats.attempts, stats.accuracy (0-1) and stats.streak. Only completed attempts count.

## Renewal and durable retries

Client tokens last 15 minutes by default. The widget's refreshToken callback calls your authenticated backend; your backend verifies session ownership, then POSTs /api/public/v1/sessions/{sessionId}/token with X-Rommy-Api-Key and returns {clientToken}. A custom client renews on 401 and retries once. Token renewal does not extend the learner session: sessions default to one hour, maximum 24 hours.

Persist an answer's original sessionId, complete body and idempotency key before sending it. Reuse exactly those values after a timeout, lost response, 408, 429 or transient 5xx; honor retry hints and use bounded backoff. Session creation also needs a stable key and unchanged body across an uncertain response. A successful answer confirms the learning update, usage and webhook delivery record were committed; replay does not count it again. Never treat a local answer or a timed-out request as confirmed server progress.

The hosted widget retains pending answers across reloads in the same tab when session storage is available. For restart durability, provide an answerJournal whose save resolves only after durable storage commits and whose clear removes only the acknowledged key. Scope journals by authenticated learner and project, preserve pending work on logout, and do not send one user's pending work as another user.

409 idempotency_conflict means the same key was reused with changed input. Legacy reconciliation errors mean an older outcome needs review. Preserve the pending operation; do not bypass either by generating a new key. On session_expired or session_inactive, create a replacement only after resolving any pending answer in its original session. Never move an uncertain answer to a new session. Show a recoverable state when progress cannot be confirmed. Keep requestId for support while excluding secrets.

Verify with a dedicated test learner: one completed answer increments attempts once, replay leaves that count unchanged, a dropped response recovers with the same key, renewal preserves session ownership, and a second user cannot access the first user's session or progress. The hosted widget requires connectivity; a public preview is not an offline progress SDK.

## Optional MCP for a building or operating agent

Guide: https://rommygames.netlify.app/developers/docs/mcp
Streamable HTTP endpoint: https://mcp.rommygames.com/mcp
Authentication: Authorization: Bearer <Rommy project API key>, stored in the MCP client's protected header configuration.

Remote MCP exposes runtime tools only. Discover the current schemas through tools/list; do not pass apiKey or clientToken tool arguments. Preserve required idempotencyKey values and exact inputs for write retries. It supports clients with manual headers, with no interactive OAuth/account linking, console provisioning, billing tools or MCP Apps. The broader public mcp-tools.json manifest describes local stdio, not remote capabilities. MCP is optional for the shipped game; ordinary HTTPS API calls are sufficient.

## Platform paths

Browser or browser-capable game: start with the hosted widget and the runnable checkpoint example.
Custom game UI: https://rommygames.netlify.app/developers/docs/public-api
RetroArch/RetroPie Linux/X11 bridge and Chromatic homebrew preview: https://rommygames.netlify.app/developers/docs/retro-integrations

Read each adapter's supported-platform limits. Native hardware does not run the browser widget or MCP. Chromatic homebrew uses an immutable text assignment and a save-file import; repeat imports must retain the assignment and sequence identity. Arbitrary stock cartridges are not supported. Project keys remain on a trusted computer/backend. Physical hardware validation remains required.