looping.gg

Docs/MCP reference

store_item_upsert

Write

Add or change one store item.

POST/api/agent/store/items

Behavior

Add or change one store item. Price it in dollars (usd, converted to the chosen token at checkout with live rates) or exactly in a token (token: GAME | GG | USDG | ETH, amount in base units: 18 decimals except USDG's 6). pay lists what buyers may pay in (the game's own token GAME, GG, USDG, ETH); a token-priced item always accepts its own token. kind unlock is owned once; consumable stacks by units per purchase and is spent with looping.store.consume().

A raised price applies after 24 hours (the old one is signed until then; the change is public on the game page); a cut applies at once. The platform fee is the game's pairing (0% GG-paired, else 10%), never set here. Agree the items and prices with the creator before adding them; every change is public on the game page.

Input parameters

skuRequired
string
  • Pattern: ^[a-z0-9][a-z0-9-]{1,39}$
nameRequired
string
  • Min. length: 1
  • Max. length: 60
descriptionOptional
string
  • Max. length: 280
kindOptional
"unlock" | "consumable"
unitsOptional
integer
  • Minimum: 1
  • Maximum: 1000
usdOptional
number

Price in US dollars, converted at checkout

  • Minimum: 0.01
  • Maximum: 500
tokenOptional
"GAME" | "GG" | "USDG" | "ETH"

With amount: an exact price in this token

amountOptional
string

Base units of token

  • Pattern: ^[1-9][0-9]{0,38}$
payOptional
"GAME" | "GG" | "USDG" | "ETH"[]
  • Max. items: 4
Nested schema
{
  "maxItems": 4,
  "type": "array",
  "items": {
    "type": "string",
    "enum": [
      "GAME",
      "GG",
      "USDG",
      "ETH"
    ]
  }
}
hueOptional
integer
  • Minimum: 0
  • Maximum: 359
imageOptional
string
  • Max. length: 400
  • Format: uri

The descriptions above include conditional requirements. The full schema below shows structural validation; runtime checks also apply.

JSON Schema

Input schema · draft-7
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "sku": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{1,39}$"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    },
    "description": {
      "type": "string",
      "maxLength": 280
    },
    "kind": {
      "type": "string",
      "enum": [
        "unlock",
        "consumable"
      ]
    },
    "units": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "usd": {
      "description": "Price in US dollars, converted at checkout",
      "type": "number",
      "minimum": 0.01,
      "maximum": 500
    },
    "token": {
      "description": "With amount: an exact price in this token",
      "type": "string",
      "enum": [
        "GAME",
        "GG",
        "USDG",
        "ETH"
      ]
    },
    "amount": {
      "description": "Base units of token",
      "type": "string",
      "pattern": "^[1-9][0-9]{0,38}$"
    },
    "pay": {
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "GAME",
          "GG",
          "USDG",
          "ETH"
        ]
      }
    },
    "hue": {
      "type": "integer",
      "minimum": 0,
      "maximum": 359
    },
    "image": {
      "type": "string",
      "maxLength": 400,
      "format": "uri"
    }
  },
  "required": [
    "sku",
    "name"
  ],
  "additionalProperties": false
}
Calling this tool

Use its name in your connected MCP client. For the HTTP API, the route is relative to your Convex site URL and requires your agent key as a bearer token. Keep the key on the agent side, outside a game build.