esimker Telegram API

openapi: 3.2.0
info:
  title: esimker Telegram API
  description: 'Prepaid travel data eSIMs. No account is needed: an order is addressed by

    the secret token from its URL. Prices are USD strings, from $1.00.


    Two ways to buy:


    - **Storefront flow** (`catalog`, `orders`): pick a plan, `POST /api/orders`, send the

    buyer to `checkout_url` to pay in crypto, then poll `GET /api/orders/{token}`

    until `status` is `ready` — the eSIM (`esim.activation_code`) is in the payload.

    - **Prepaid wallet** (`wallet`): `POST /api/wallet` mints a wallet whose secret code is

    the only credential (`X-Wallet-Code`); `POST /api/wallet/deposits` opens a top-up

    invoice and, with `currency` set, returns the coin address and the exact amount for a

    payer with no browser; `POST /api/orders` with `payment_method: "wallet"` charges the

    balance and issues at once (`client_ref` makes a retry return the same order).

    - **Reseller API** (`reseller`): white-label partners on `X-API-Key`, retail minus a

    discount; keys are issued by support.


    The wallet and the catalogue are also MCP tools at `POST https://esimker.com/api/mcp`

    (Streamable HTTP; the wallet code goes in `Authorization: Bearer`).


    The guide for agents is https://esimker.com/agents (the wallet: https://esimker.com/agents#wallet).


    **Buyer accounts** (`account`) are the storefront''s own cabinet: an address and a password

    as a second way for a person to reach their orders and wallets, on a session cookie with a

    CSRF echo. An account is optional and nothing above needs one — an agent keeps the order

    token and the wallet code, and has no use for these routes.'
  version: '1'
tags:
- name: telegram
paths:
  /api/telegram/orders:
    get:
      tags:
      - telegram
      summary: Chat Orders
      description: 'The orders this Telegram user bought — in the Mini App or in the bot''s chat

        (both write `bot_order_links`), newest first. 401 without a valid initData.'
      operationId: chat_orders_api_telegram_orders_get
      parameters:
      - name: X-Telegram-Init-Data
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Telegram-Init-Data
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
                title: Response Chat Orders Api Telegram Orders Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/telegram/wallet/reveal:
    post:
      tags:
      - telegram
      summary: Reveal Chat Wallet
      description: 'The chat''s wallet code and backup phrase, for the buyer to write down —

        the Mini App''s "Show backup", as the bot''s is in the chat. 404 without a

        linked wallet. A POST, so no cache and no prefetch ever holds the answer.'
      operationId: reveal_chat_wallet_api_telegram_wallet_reveal_post
      parameters:
      - name: X-Telegram-Init-Data
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Telegram-Init-Data
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatWalletSecret'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/telegram/wallet/forget:
    post:
      tags:
      - telegram
      summary: Forget Chat Wallet
      description: 'Unlinks the chat''s wallet — in the chat and in the Mini App alike, since

        they share it. The wallet itself stays and opens again with its code.'
      operationId: forget_chat_wallet_api_telegram_wallet_forget_post
      parameters:
      - name: X-Telegram-Init-Data
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Telegram-Init-Data
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: boolean
                title: Response Forget Chat Wallet Api Telegram Wallet Forget Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ChatWalletSecret:
      properties:
        code:
          type: string
          title: Code
        phrase:
          type: string
          title: Phrase
      type: object
      required:
      - code
      - phrase
      title: ChatWalletSecret