KodShop catalog

Search the store catalog of gift cards, service top-ups and eSIM data plans. Returns matching products with their price, availability and product page URL.

{
  "type": "object",
  "properties": {
    "country": {
      "description": "ISO-3166-1 alpha-2 country code the product is issued for, e.g. US, TR.",
      "type": "string"
    },
    "limit": {
      "description": "Max products to return (default 10, max 50).",
      "type": "integer"
    },
    "query": {
      "description": "Free text matched against product name and brand, e.g. \"steam\" or \"playstation\".",
      "type": "string"
    },
    "type": {
      "description": "voucher = gift card, recharge_fixed / recharge = top-up, e_sim = eSIM data plan.",
      "enum": [
        "voucher",
        "recharge_fixed",
        "recharge",
        "e_sim"
      ],
      "type": "string"
    }
  }
}

Get one catalog product by id: available denominations with prices, required order inputs, and any countries where the code cannot be redeemed.

{
  "type": "object",
  "properties": {
    "id": {
      "description": "Product id from search_catalog.",
      "type": "integer"
    }
  },
  "required": [
    "id"
  ]
}

Buy a gift card, service top-up or travel eSIM and receive the delivery. Paid in USDC on Base (x402), no account and no browser. Call it twice: first with the order arguments to get payment requirements and an order_id (nothing is charged), then with that order_id plus the signed x402 payment payload to settle and receive the code.

{
  "type": "object",
  "properties": {
    "account_number": {
      "description": "Only for products where get_product reported requires_account: the recipient account the top-up credits.",
      "type": "string"
    },
    "amount": {
      "description": "Only for products where get_product reported requires_amount; send instead of item_id.",
      "type": "number"
    },
    "email": {
      "description": "Delivery address. The code, eSIM profile or number is emailed here, and it is the only identity the order has. Required on the first call.",
      "type": "string"
    },
    "item_id": {
      "description": "Denomination id from get_product items[].",
      "type": "integer"
    },
    "order_id": {
      "description": "Second call only: the order_id returned by the first call.",
      "type": "string"
    },
    "payment_payload": {
      "description": "Second call only: the signed x402 PaymentPayload built from the requirements the first call returned.",
      "type": "object"
    },
    "product_id": {
      "description": "Product id from search_catalog.",
      "type": "integer"
    },
    "product_type": {
      "description": "giftcard = voucher, topup = service recharge. eSIM data plans from search_catalog are bought as giftcard too — the value names the order shape, not the goods.",
      "enum": [
        "giftcard",
        "topup"
      ],
      "type": "string"
    },
    "quantity": {
      "description": "Copies to buy. Defaults to 1 — send it only to buy several.",
      "type": "integer"
    }
  }
}