Гейминг ГудсГейминг Гудс
API

Gaming Goods — API Documentation

Integrate the Gaming Goods catalog into your applications. REST API with JSON responses, JWT authentication and a predictable error structure.

Base URL

Production
https://gaming-goods.ru/api/v1

All endpoints share this base URL. Responses are returned as JSON.

Authentication

Several access schemes — pick the one that matches your scenario:

SchemeWherePurpose
JWT BearerAuthorizationUser flow (issued after SMS). Orders on behalf of a user.
gg_live_… BearerAuthorizationPublic API (B2B): catalog + orders by key. Rotating a key invalidates the old one.
MCP OAuth 2.1BearerFor AI agents via the MCP channel (see “MCP channel”).
Partner API keyAuthorizationLegacy Partner API. Partner catalog is public; cart/orders/seller require a key.
HTTP Header (JWT or gg_live_)
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Authorization: Bearer gg_live_xxxxxxxxxxxxxxxxxxxx

Public endpoints (catalog, search, categories, brands) work without a token. To request a gg_live_ key, email ceo@vvv.cash.

Product catalog

GET/products

Returns a paginated list of products with optional filters.

ParameterTypeDescription
categorystringFilter by category (e.g. Steam, Xbox)
brandstringFilter by brand
localestringResponse locale: ru or en
sortstringSort order: price_asc, price_desc, name, newest
pageintegerPage number (default 1)
page_sizeintegerItems per page (default 20, max 100)
Response
{
  "data": {
    "products": [
      {
        "id": "a1b2c3d4-...",
        "name": "Cyberpunk 2077",
        "slug": "cyberpunk-2077-steam-key",
        "category": "Steam",
        "brand": "CD Projekt",
        "price": 19.99,
        "currency": "EUR",
        "stock_quantity": 12,
        "image_url": "https://gaming-goods.ru/...",
        "is_active": true
      }
    ],
    "total": 1542,
    "page": 1,
    "page_size": 20
  }
}

Product detail

GET/products/:slug

Returns full details of a single product by slug.

Response
{
  "data": {
    "id": "a1b2c3d4-...",
    "name": "Cyberpunk 2077",
    "slug": "cyberpunk-2077-steam-key",
    "category": "Steam",
    "brand": "CD Projekt",
    "description": "Open-world action-adventure...",
    "price": 19.99,
    "currency": "EUR",
    "stock_quantity": 12,
    "image_url": "https://gaming-goods.ru/...",
    "is_active": true,
    "meta": { "activation_details": "..." }
  }
}

Search

GET/products/search

Full-text search across the product catalog.

ParameterTypeDescription
qstringSearch query (minimum 2 characters)
localestringResponse locale: ru or en
pageintegerPage number
page_sizeintegerItems per page
Response
{
  "data": {
    "products": [
      {
        "id": "a1b2c3d4-...",
        "name": "Cyberpunk 2077",
        "slug": "cyberpunk-2077-steam-key",
        "price": 19.99,
        "stock_quantity": 12,
        "is_active": true
      }
    ],
    "total": 3,
    "page": 1,
    "page_size": 20
  }
}

Categories

GET/categories

Returns all categories with the number of products in each.

Response
{
  "data": [
    { "name": "Steam", "product_count": 842 },
    { "name": "Xbox", "product_count": 215 },
    { "name": "PlayStation", "product_count": 187 },
    { "name": "Nintendo", "product_count": 94 }
  ]
}

Brands

GET/brands

Returns all brands with the number of products.

Response
{
  "data": [
    { "name": "Microsoft", "product_count": 312 },
    { "name": "Electronic Arts", "product_count": 198 },
    { "name": "Ubisoft", "product_count": 156 }
  ]
}

Create order

POST/orders

Creates a new order. Authentication required. The Idempotency-Key header is REQUIRED (since GG-278) — without it you get 400 MISSING_IDEMPOTENCY_KEY.

ParameterTypeDescription
Idempotency-KeyheaderREQUIRED. UUID to prevent duplicate orders on retries
Request Body
{
  "items": [
    {
      "product_id": "a1b2c3d4-...",
      "quantity": 1
    }
  ],
  "payment_method": "balance",
  "promo_code": "SALE10"
}
Response
{
  "data": {
    "id": "e5f6a7b8-...",
    "status": "pending_payment",
    "items": [
      {
        "product_id": "a1b2c3d4-...",
        "product_name": "Cyberpunk 2077",
        "price": 1999,
        "quantity": 1
      }
    ],
    "total": 1799,
    "currency": "EUR",
    "payment_url": "https://...",
    "created_at": "2026-07-13T12:00:00Z"
  }
}

Order status

GET/orders/:id

Returns order details including activation keys (after payment). Authentication required.

Response
{
  "data": {
    "id": "e5f6a7b8-...",
    "status": "completed",
    "items": [
      {
        "product_id": "a1b2c3d4-...",
        "product_name": "Cyberpunk 2077",
        "price": 1999,
        "quantity": 1,
        "keys": ["XXXXX-XXXXX-XXXXX-XXXXX"]
      }
    ],
    "total": 1999,
    "currency": "EUR",
    "created_at": "2026-07-13T12:00:00Z",
    "completed_at": "2026-07-13T12:00:05Z"
  }
}

Public API (Pub) — B2B

Paid B2B channel with an Authorization: Bearer gg_live_… key. Returns the “full-but-masked” catalog (supplier hidden) and lets you create orders. Base URL: https://gaming-goods.ru/api/v1/pub.

curl examples (substitute your gg_live_ key)
KEY="gg_live_xxxxxxxxxxxxxxxxxxxx"

# 1) Catalog list
curl -sS -H "Authorization: Bearer $KEY" \
  "https://gaming-goods.ru/api/v1/pub/products?q=cyberpunk&page_size=1"

# 2) Product detail
curl -sS -H "Authorization: Bearer $KEY" \
  "https://gaming-goods.ru/api/v1/pub/products/cyberpunk-2077-steam-key"

# 3) Create order (recipient_data for recipient products)
curl -sS -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"items":[{"gg_product_id":"a1b2c3d4-...","quantity":1}],"idempotency_key":"550e8400-e29b-41d4-a716-446655440000"}' \
  "https://gaming-goods.ru/api/v1/pub/orders"

# 4) Order detail
curl -sS -H "Authorization: Bearer $KEY" \
  "https://gaming-goods.ru/api/v1/pub/orders/e5f6a7b8-..."

Pub: Catalog

GET/pub/products

Product list with filters and pagination. Requires Bearer gg_live_. provider_type is masked as "marketplace".

ParameterTypeDescription
brandstringFilter by brand
categorystringFilter by category
qstringSearch by title
min_price / max_pricenumberPrice range
page / page_sizeintegerPagination (page_size ≤ 500)
Response
{
  "products": [
    {
      "gg_product_id": "a1b2c3d4-...",
      "slug": "cyberpunk-2077-steam-key",
      "name": "Cyberpunk 2077",
      "provider_type": "marketplace",
      "price": 19.99,
      "currency": "EUR",
      "stock_quantity": 12,
      "delivery_type": "playwallet",
      "moderation_status": "approved",
      "is_active": true,
      "steam_app_id": 1091500,
      "steam_url": "https://store.steampowered.com/app/1091500/"
    }
  ],
  "total": 1542,
  "page": 1,
  "page_size": 100
}

Pub: Product detail

GET/pub/products/{slug}

Full product card by slug. Requires Bearer gg_live_.

Response
{ "product": { "gg_product_id": "...", "slug": "...", "steam_app_id": 1091500, "steam_url": "https://store.steampowered.com/app/1091500/" } }

Pub: Create order

POST/pub/orders

Creates an order from the catalog. recipient_data is required for recipient products (see section). idempotency_key is a body field (auto-generated if omitted; pass your own to dedupe retries).

Request Body
{
  "items": [{ "gg_product_id": "a1b2c3d4-...", "quantity": 1 }],
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "recipient_data": { "steam_login": "user123" }
}
Response
{ "data": { "id": "e5f6a7b8-...", "status": "pending_payment", "total": 1999, "currency": "EUR" } }

Pub: Order detail

GET/pub/orders/{id}

Order status and contents, including keys once fulfilled. Requires Bearer gg_live_.

Response
{ "data": { "id": "e5f6a7b8-...", "status": "completed", "delivery": { "codes": ["XXXXX-XXXXX"] } } }

Pub: Balance (in review)

GET/pub/balance

Current partner balance. Endpoint is in review (GG-393) — confirm availability before use.

Response
{ "data": { "balance": 125000, "currency": "EUR" } }

recipient_data contract

Products delivered to a recipient require a recipient_data object when creating an order (POST /pub/orders and POST /buyer/checkout/virtual). Which field is needed is determined by the product’s delivery_type (the REST catalog does not expose a separate recipient_requirement — rely on delivery_type).

delivery_typefieldpurpose
fragmenttelegram_usernameTelegram Stars / Premium. Format: @username (5–32, [a-zA-Z0-9_])
playwalletsteam_loginSteam wallet top-up. Login 3–32 chars
manual_giftrecipient_emailClaude / Anthropic and other email subscriptions
Example inside the order body
"recipient_data": {
  "telegram_username": "@durov"   // fragment
  // "steam_login": "user123"     // playwallet
  // "recipient_email": "u@mail.com" // manual_gift
}

Validation errors: recipient_required (field missing), recipient_invalid (bad format) — HTTP 422.

MCP channel (for AI agents)

The MCP server at https://gaming-goods.ru/mcp integrates with AI clients (Claude Desktop, ChatGPT Custom Connector, etc.) over OAuth 2.1. Transport is JSON-RPC over HTTP/SSE.

OAuth endpointmethodpurpose
/mcp/.well-known/oauth-authorization-serverGETDiscovery metadata (RFC 8414). Also /mcp/.well-known/oauth-protected-resource
/mcp/registerPOSTDynamic Client Registration (DCR)
/mcp/authorizeGETAuthorization Code + PKCE (S256)
/mcp/tokenPOSTExchange code for token; grants: authorization_code, refresh_token
/mcp/revokePOSTRevoke a token

MCP tools: search, get_product, add_to_cart, view_cart, remove_from_cart, clear_cart, create_checkout_link. Scope mcp. The search/get_product tools return requires_recipient + recipient_schema.

Partner API

The Partner API is for third-party marketplace integrations. Authentication uses the X-API-Key header. To request a key, contact ceo@vvv.cash.

Base URL
https://gaming-goods.ru/api/partner/v1

Partner: Brands

GET/catalog/brands

Returns the list of brands with the number of available products.

ParameterTypeDescription
limitintegerItems per page (default 20, max 100)
offsetintegerPagination offset
Response
{
  "items": [
    { "brand": "Steam", "product_count": 842 },
    { "brand": "Xbox", "product_count": 215 }
  ],
  "limit": 20,
  "offset": 0,
  "total": 156
}

Partner: Brand categories

GET/catalog/brands/{brand}/categories

Returns product categories for the given brand.

Response
{
  "brand": "Steam",
  "categories": [
    { "category": "Game Keys", "product_count": 650 },
    { "category": "Gift Card", "product_count": 42 }
  ]
}

Partner: Product catalog

GET/catalog/products

Returns paginated products. Prices are in euro cents. product_type=KINGUIN marks the supplier.

ParameterTypeDescription
brandstringFilter by brand
categorystringFilter by category
searchstringSearch by title
updated_sincestringRFC3339. Incremental export of changed products
platform / platformsstringPlatform (single / multi)
genres / regions / activationsstringMulti-value attribute filters
typestringProduct type
providerstringkinguin | dpgame | bamboo | c2c
min_price / max_priceintegerPrice range (euro cents)
min_discountinteger1–100. Discount vs Steam price (needs EUR→RUB rate)
sortstringprice_asc, price_desc, newest, relevance
limit / offsetintegerPagination
Response
{
  "items": [
    {
      "id": "a1b2c3d4-...",
      "title": "Cyberpunk 2077 Steam Key",
      "brand": "CD Projekt",
      "category": "Game Keys",
      "genres": ["RPG"],
      "platform": "Steam",
      "activation_type": "steam",
      "region": "GLOBAL",
      "price": 1999,
      "currency": "EUR",
      "quantity": 12,
      "is_available": true,
      "delivery_type": "EXTERNAL",
      "product_type": "KINGUIN",
      "images": ["https://gaming-goods.ru/..."],
      "short_description": "",
      "steam_app_id": 1091500,
      "steam_url": "https://store.steampowered.com/app/1091500/"
    }
  ],
  "total": 1542,
  "limit": 20,
  "offset": 0
}

Partner: Product detail

GET/catalog/products/{productId}

Full product details by UUID. steam_discount_percent, steam_app_id, steam_url, activation_instructions appear only when available (Kinguin with a verified match).

Response
{
  "id": "a1b2c3d4-...",
  "title": "Cyberpunk 2077 Steam Key",
  "brand": "CD Projekt",
  "category": "Game Keys",
  "genres": ["RPG"],
  "platform": "Steam",
  "activation_type": "steam",
  "region": "GLOBAL",
  "price": 1999,
  "currency": "EUR",
  "quantity": 12,
  "is_available": true,
  "delivery_type": "EXTERNAL",
  "product_type": "KINGUIN",
  "images": ["https://gaming-goods.ru/..."],
  "description": "Open-world action-adventure...",
  "short_description": "",
  "specifications": [ { "key": "platform", "value": "Steam" } ],
  "steam_discount_percent": 42,
  "steam_app_id": 1091500,
  "steam_url": "https://store.steampowered.com/app/1091500/",
  "activation_instructions": "..."
}

Partner: Checkout

POST/buyer/checkout/virtual

Creates an order. Source: "cart" (from the cart) or "lines" (products in the request body). Requires X-API-Key.

Request Body
// From cart:
{ "source": "cart" }

// Or with explicit line items:
{
  "source": "lines",
  "lines": [
    { "product_id": "a1b2c3d4-...", "quantity": 1 }
  ]
}
Response
{
  "orders": [
    {
      "id": "e5f6a7b8-...",
      "status": "created",
      "total": 1999,
      "currency": "EUR"
    }
  ]
}

Partner: Order list

GET/buyer/orders

Returns the partner's paginated order list. Requires X-API-Key.

ParameterTypeDescription
limitintegerItems per page (default 20)
offsetintegerOffset
statusstringFilter by status (created, paid, completed, cancelled_before_payment, cancelled_after_payment)
Response
{
  "items": [
    {
      "id": "e5f6a7b8-...",
      "status": "completed",
      "total": 1999,
      "currency": "EUR",
      "created_at": "2026-07-13T12:00:00Z"
    }
  ],
  "limit": 20,
  "offset": 0,
  "total": 47
}

Partner: Order detail

GET/buyer/orders/{orderId}

Order details. Activation keys are available in delivery.codes once fulfilled. Requires X-API-Key.

Response
{
  "id": "e5f6a7b8-...",
  "buyer_id": "c3d4e5f6-...",
  "status": "completed",
  "items": [
    {
      "product_id": "a1b2c3d4-...",
      "title": "Cyberpunk 2077 Steam Key",
      "unit_price": 1999,
      "quantity": 1
    }
  ],
  "amounts": {
    "buyer_total": 1999,
    "platform_fee": 0
  },
  "payment": {
    "method": "balance",
    "state": "paid"
  },
  "delivery": {
    "type": "EXTERNAL",
    "codes": ["XXXXX-XXXXX-XXXXX"]
  },
  "created_at": "2026-07-13T12:00:00Z",
  "updated_at": "2026-07-13T12:00:05Z"
}

Rate Limiting

Limits depend on the access type. On exceeding, the server returns 429 Too Many Requests with a Retry-After header. Use exponential backoff.

AccessPer minutePer day
Public catalog (no token)601000 — counted per IP
Public API (gg_live_…)600100,000 — counted per key (your key’s values may differ)
Partner API—No limit applied; use reasonable load and pagination

Response headers for rate-limited endpoints (names are case-insensitive; lowercased over HTTP/2). X-RateLimit-Reset is the Unix time of the window reset.

Response Headers
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1784617860
X-Request-ID: 500c767f-6e64-4d35-b2bd-1c7698befae7

Error format

All errors share the envelope { "error": { "code", "message" } }. On REST surfaces (public API, Public API, Partner API, Seller API) codes are UPPER_SNAKE (e.g. VALIDATION_ERROR). The one exception is the MCP OAuth 2.1 layer, where codes are lowercase per the OAuth spec (invalid_request, invalid_grant, invalid_token).

Error Response (REST)
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Parameter 'page' must be a positive integer"
  }
}
400VALIDATION_ERROR / MISSING_IDEMPOTENCY_KEY — invalid parameters or a required header is missing
401UNAUTHORIZED — missing or invalid token/key
403FORBIDDEN — insufficient permissions
404NOT_FOUND — resource does not exist
422recipient_required / recipient_invalid — recipient_data missing or malformed
429RATE_LIMIT — rate limit exceeded (see Retry-After)
500INTERNAL_ERROR — server-side failure

Changelog

07-13Aligned with production: real rate limits (60/600), Public API (Pub), MCP channel (OAuth 2.1), recipient_data contract, steam_app_id/steam_url in the catalog, Idempotency-Key required on /orders. (GG-408)

Last updated: 13 July 2026.

Get API access

Email us to request an API token and discuss your integration.

ceo@vvv.cashMCP integration