# ggbucks public developer documentation

Public OpenAPI3.1 integration context. Sandbox TEST ggbucks only, no cash value or production-wallet credit. Contract hash: 9ae5180d5f8f1de2cd25fc025b00af0ee00e1ae569dd787254956d0ebf116216. Source: live.

## Resources

- [OpenAPI](https://docs.ggbucks.com/openapi.json)
- [Getting started](https://docs.ggbucks.com/guides/getting-started): Set up invited access, a project, a game and bounded TEST reward rules.
- [Unity public configuration](https://docs.ggbucks.com/guides/unity-public-config): Read game configuration with a public key, without embedding a secret.
- [Server events and outbox](https://docs.ggbucks.com/guides/server-events): Verify actions on your server and deliver one durable event decision.
- [Player linking and consent](https://docs.ggbucks.com/guides/player-linking): Connect a game account through native player approval and server status polling.
- [Agent skills](https://docs.ggbucks.com/skills)
- [Skill manifest](https://docs.ggbucks.com/skills/manifest.json)

# Current public integration contract

Contract hash: `9ae5180d5f8f1de2cd25fc025b00af0ee00e1ae569dd787254956d0ebf116216`. Document hash: `8d7060c0cb1ed48d2fce6d06f2ca41463dbbee0d1db0331a55634dc6cdf404e8`.
This resource and its examples are generated together from the validated public contract. Confirm the current contract before remote work. Read [openapi.json](openapi.json) for exact request/response schemas and console action variants.

## Reward and credential boundaries

All reward accounting is sandbox **TEST ggbucks**, with no cash value and no production-wallet credit. 1000 integer units represent one test dollar for display. Project and game allocations, lifetime payout ceilings and daily player caps are enforced by the server. Unlimited organization test funding never removes project or game caps.

A public key identifies a game and reads configuration; it is extractable from a client and is not gameplay proof. The secret belongs only in the trusted game server's secret manager. Secret authentication reduces spoofed submissions; the game server must still verify gameplay. Do not put secret keys in Unity, remote config, client analytics, logs, crash reports, or support tickets. The portal requires an active admin invitation plus verified primary email; organization membership alone is insufficient. Reading this skill does not authorize key issuance/revocation, account enforcement, live value movement, deployment, messages, or other external mutations.

## Event delivery

Record the UUID and UTC timestamp once when the trusted server records a verified action. Atomically persist that event body and the action in your durable outbox before delivery. Reuse the same game-scoped event ID, player, type, timestamp and metadata after an unknown delivery result; changed-payload replay returns 409. Object key ordering is canonicalized; values and timestamps must remain unchanged. Clock skew allowance is 300 seconds and fresh-event capacity is 120 per game per minute. Metadata allows 4096 UTF-8 bytes, depth 6, 100 array values and 100 object entries. Caller-provided reward amounts or native user IDs are not event fields.

Use a bounded retry budget for transport failures, 429 and 5xx, with backoff and server Retry-After when present. Keep exhausted items for operator review. Do not retry other 4xx automatically. A 2xx event response can be rejected; persist status, reason and replayed rather than inventing an earned payout. Never grant another local benefit when replayed is true. The server's immutable original decision survives subsequent rule changes.

## Native consent boundary

A compatible ggbucks mobile build that implements v2 consent is required. The previously released mobile app is not assumed compatible; confirm readiness before promising end-to-end linking. The game backend creates an intent for its authenticated external player identity, then the game opens `ggbucks://developer-game-link?linkToken=...`. Tokens expire after 600 seconds. The human reviews the game/account and explicitly approves inside ggbucks. Native inspect/approve are **ggbucks-app-owned** boundaries with canonical profile and session-bound device admission. The game backend must never collect a player's Clerk session or call native approve using its secret or developer token. Poll the game-scoped player status from the server at a bounded interval, stop when linked or expired, and expose only that requesting game account's status. Never log/persist link tokens on devices, add arbitrary callbacks, or put them in analytics.

## Supported operations

| Method | Path | Credential | Operation |
| --- | --- | --- | --- |
| GET | `/api/developer/v1/access` | developer-session | Check developer dashboard admission |
| GET | `/api/developer/v1/console` | developer-session | Read the developer console |
| POST | `/api/developer/v1/console` | developer-session | Manage organizations, projects and games |
| GET | `/api/developer/v1/records` | developer-session | Page through linked players or reward decisions |
| GET | `/api/game-sdk/v2/config` | game-public-key | Read game configuration with a public identifier |
| POST | `/api/game-sdk/v2/events` | game-secret | Record a server-verified rewarded-play event |
| POST | `/api/game-sdk/v2/links` | game-secret | Create a native account linking intent |
| GET | `/api/game-sdk/v2/players/{playerId}` | game-secret | Poll whether a game player is linked |
| POST | `/api/v0/game-sdk/v2/links/approve` | native-session | Approve linking after native user consent |
| POST | `/api/v0/game-sdk/v2/links/inspect` | native-session | Inspect a linking request in the native consent flow |

## Developer console action variants

`addMember`, `allocateGame`, `allocateProject`, `createGame`, `createOrganization`, `createProject`, `createRule`, `fundOrganization`, `issueKey`, `removeMember`, `revokeKey`, `updateGame`, `updateMember`, `updateProject`, `updateRule`.
These variants use the invited portal session and organization permissions. Their presence in the contract is not authorization to execute them; use the portal UI for the user's approved sandbox setup.

This is v2-only public documentation. It does not promise legacy v1 endpoints, a published Unity package, or an npm registry SDK. The bundled Unity example is self-contained source to review and copy into your own project. Keep ordinary gameplay available when configuration/networking/linking fails; never fabricate a reward success.