> For the complete documentation index, see [llms.txt](https://sdk.metamarket.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sdk.metamarket.tech/architecture-and-trust/how-it-fits.md).

# How MetaMarket Fits Into Your Game

MetaMarket sits behind your game as a backend it talks to over HTTP. Your client and your game logic stay yours; the platform stores authoritative player state and runs the shared engine your configuration drives. Here is the shape of that relationship before you reach the integration detail.

## The split, in one line

You send player activity as actions and display the results. MetaMarket interprets each action against your config, stores the authoritative state, and runs the quest, reward, and economy engine.

```mermaid
flowchart LR
    Client["Your game client<br/>(UI, game logic)"] -->|actions / JWT| Gateway["Edge gateway<br/>(external door)"]
    Gateway --> Runtime["Your game's runtime<br/>(your config, your local economy)"]
    Runtime -->|"auth calls, proxied"| Hub["Hub<br/>(shared identity + platform currency)"]
    Runtime -->|"declared milestones"| Hub
```

* **Your game client** holds the UI and game rules, authenticates the player, and sends actions.
* **The edge gateway** is the door external games come through. It enforces the tenant boundary and attaches your app credential to event calls on your behalf.
* **Your game's runtime** interprets your configuration (your actions, resources, quests, and local economy), isolated by your app id.
* **The Hub** owns what is shared across every game: player identity, the platform currency, and the loyalty standing (points, tier, badges).

First-party modules skip the gateway and talk to the engine directly; external games always go through the gateway. [Roles](/architecture-and-trust/users-and-actors.md) explains why, and which door each trust level uses.

## What you send, what MetaMarket stores

| You send                                                       | MetaMarket does                                                                                                                          |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Player activity your game reports, as actions                  | Interprets each action against your config and writes the result                                                                         |
| A player JWT, obtained by the SDK's device-key sign-in         | Owns identity, issues and rotates sessions, and runs handoff. The device keeps its private key; the platform stores only the public half |
| Your app's configuration (actions, resources, quests, rewards) | Runs the shared engine that config drives, and picks up changes within its refresh window                                                |
| Requests to read player state, quests, inventory               | Returns authoritative state, with live echoes of what an action just changed                                                             |

## What you keep, what MetaMarket owns

Your game logic, content, UX, local economy, and client credentials stay with you. MetaMarket owns identity (so you don't build and maintain a login system), the platform currency and shared loyalty standing, the platform-owned bridge quests, and tenant isolation. See [Studio and platform responsibilities](/architecture-and-trust/responsibilities-and-boundaries.md) for the full breakdown, and the [Integration walkthrough](/evaluate-and-integrate/quickstart.md) to wire up the first call.

## One consistent response shape

Every mutating domain call returns the same four-channel envelope, which carries the domain result alongside the values the action changed, snapshots of the affected subjects, and any instruction the client should act on. The practical consequence is that a client updates its UI straight from an action's response instead of making a second read. [Sending Actions](/evaluate-and-integrate/events-and-directives.md) documents the four channels and the order to apply them in.

## How an action becomes a state update or reward

```mermaid
sequenceDiagram
    participant Client as Your game client
    participant Engine as Your game's runtime
    participant Config as Your app configuration

    Client->>Engine: action (verb, value, entity)
    Engine->>Config: is this verb declared? what does it do?
    Config-->>Engine: stat write / package grant / no-op
    Engine->>Engine: apply write, run reward package if linked
    Engine-->>Client: data + effects (touched values) + mutations (touched entities) + directives
```

An action's own config decides what it does: a `stat` action writes a declared resource, a `mechanic` action runs a linked reward package. Either way, the response already carries what changed, so the client does not need a follow-up read to update its UI.

With the shape in hand, the [Integration walkthrough](/evaluate-and-integrate/quickstart.md) wires up the first real call.