# KodShop

> Digital goods store: gift cards (Steam, Apple, PlayStation, Google Play, Xbox and ~1000 more), service top-ups, travel eSIMs for 80+ countries, and rentable phone numbers for SMS. Codes are delivered by email within seconds of payment. Prices in RUB.

No account is required to buy — the delivery email address is the only identity. Full auth notes: https://kodshop.cloud/auth.md

## API

- [OpenAPI 3.1 description](https://kodshop.cloud/openapi.json): every public endpoint, request and response shape
- [API catalog](https://kodshop.cloud/.well-known/api-catalog): RFC 9727 linkset
- [Authentication](https://kodshop.cloud/auth.md): public API needs no credentials; orders carry a per-order access token
- [MCP server](https://kodshop.cloud/mcp): Streamable HTTP, card at https://kodshop.cloud/.well-known/mcp/server-card.json
- [A2A agent](https://kodshop.cloud/a2a): JSON-RPC `message/send`, card at https://kodshop.cloud/.well-known/agent-card.json
- [Agent skills](https://kodshop.cloud/.well-known/agent-skills/index.json): step-by-step buying recipe
- [ACP discovery](https://kodshop.cloud/.well-known/acp.json): Agentic Commerce Protocol metadata
- [Payment methods](https://kodshop.cloud/api/public/payment-methods): rails, minimums, payable coin/network pairs
- [UCP profile](https://kodshop.cloud/.well-known/ucp): Universal Commerce Protocol service registry

### Buying flow

1. `GET https://kodshop.cloud/api/public/products?q=steam&type=voucher` — search the catalog. Only rows with `available_for_sale` and `in_stock` true are orderable. Prices are `price` / `min_price` in `currency` (`*_rub` keys are legacy aliases of the same numbers — the suffix is a storage-era name, not the unit).
2. `GET https://kodshop.cloud/api/public/products/{id}` — read `items[]` (denominations), `fields[]` (extra inputs) and per-item `restricted_countries`.
3. `POST https://kodshop.cloud/api/public/create-order` with an `Idempotency-Key` header — returns `order_id` + `access_token`. Only `email`, `product_type`, `product_id` and `item_id` are needed for a gift card: `quantity` defaults to 1 even where `fields[]` marks it required, so send it only to buy several copies.
4. `POST https://kodshop.cloud/api/public/create-heleket-payment` with `{"order_id":…,"to_currency":"USDT","network":"bsc"}` — returns an on-chain `address` + exact `pay_amount` your wallet can settle with no browser. Drop `to_currency` and you get only the hosted checkout `url` for a human. Card rails exist for humans on the site; crypto is the agent rail.
5. `GET https://kodshop.cloud/api/public/order/{id}?token=…` — poll until `completed`, then read `delivery.code` / `esim` / `phone`.

Payment is on-chain stablecoin transfer, detected automatically.

### Payment rails

`GET https://kodshop.cloud/api/public/payment-methods` lists both rails with their minimums and the coin/network pairs the crypto invoice accepts. Read it before picking a product — the two constraints below decide which items you can actually pay for.

- **Crypto invoice** (`create-heleket-payment`): minimum **10.00 RUB per order**. Cheaper orders are rejected with `amount_too_low` after the order already exists. Its `to_currency`/`network` pairs are the payment gateway's, and USDT on `bsc` or `tron` are the reliable ones. Network codes are case-insensitive.
- **x402** (`/api/v1/buy`): **USDC on `eip155:8453` (Base)**, no minimum — the rail for anything under the crypto floor. Needs a signed `PAYMENT-SIGNATURE` header, so a wallet that can only send a plain transfer must use the crypto invoice and a large enough order.

Holding USDC on Base (`eip155:8453`, spelled `base` by x402 v1) means x402, not the crypto invoice: that pair is native to `/api/v1/buy` and is not one the invoice gateway offers. Asking the invoice endpoint for it answers `unsupported_coin_network`, which says nothing about the store's support for the asset.

### x402 (one-shot buying)

`POST https://kodshop.cloud/api/v1/buy` sells the goods themselves over x402 — USDC on Base (`eip155:8453`), priced per product, no browser and no separate payment call.

1. `POST https://kodshop.cloud/api/v1/buy` with the create-order body (`{"email":…,"product_type":"giftcard","product_id":…,"item_id":…}`) — answers `402` with the x402 v2 `PaymentRequired` document in the `PAYMENT-REQUIRED` header and in the body (`accepts[]` holds the exact USDC amount in atomic units for that item), plus an `order` block.
2. Repeat the identical request with a `PAYMENT-SIGNATURE` header. The payment is verified and settled through the CDP facilitator, then the order is fulfilled.
3. `200` carries `delivery.code` / `esim` / `phone`. `202` means fulfilment is still running — poll the `order.status_url`. The settlement receipt is in the `PAYMENT-RESPONSE` header.

Protocol version: v2 by default (CAIP-2 network `eip155:8453`, atomic amounts, discovery under `extensions.bazaar`). x402 v1 is still served for clients that speak nothing else — send the payment in `X-PAYMENT`, or ask for a v1 quote with `X-PAYMENT-VERSION: 1` (or `?x402_version=1`); the v1 network name is `base` and its receipt header is `X-PAYMENT-RESPONSE`.

Send an `Idempotency-Key` header to make retries safe; without one it is derived from the request body, so an identical repeat resolves to the same order. `GET https://kodshop.cloud/api/v1` describes the rail for free; `GET https://kodshop.cloud/api/v1/buy?product_id=…&item_id=…&email=…` quotes over query params. Calling `/api/v1/buy` with nothing named answers `402` with the rail's floor and no order — a description of the paywall, not a buyable quote.

## Pages

- [Catalog](https://kodshop.cloud/ru/catalog/): all products, filterable by category, country and type
- [eSIM](https://kodshop.cloud/ru/esim/): data plans by country
- [Phone numbers](https://kodshop.cloud/ru/phone-rental/): rentable numbers for SMS, 1 or 3 months
- [Top-ups](https://kodshop.cloud/ru/popolnit/): mobile and service balance top-ups
- [For AI agents](https://kodshop.cloud/ru/agents/): human-readable version of this document, with per-product guides
- [Blog](https://kodshop.cloud/ru/blog/): guides on redeeming codes, eSIM activation, regional restrictions
- [Sitemap](https://kodshop.cloud/sitemap.xml)

## Notes

- The homepage answers `Accept: text/markdown` with a markdown version of itself. Other pages are HTML only — use the API for structured data.
- Catalog data refreshes on a 25-minute cycle; cache it rather than re-listing ~1200 products per query.
- Refunds and order recovery are manual: support@support.kodshop.cloud