esimker Catalog API

openapi: 3.2.0
info:
  title: esimker Catalog 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: Catalog
paths:
  /api/catalog:
    get:
      tags:
      - Catalog
      summary: Catalog Index
      description: 'Destinations on sale with the lowest price and the plan count; `slug` is

        the key for `GET /api/catalog/{slug}`.'
      operationId: catalog_index_api_catalog_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  additionalProperties: true
                  type: object
                type: array
                title: Response Catalog Index Api Catalog Get
  /api/catalog/{slug}:
    get:
      tags:
      - Catalog
      summary: Catalog Destination
      description: 'The destination''s plans (`plans[].id` is the `plan_id` for an order) and its

        published reviews.'
      operationId: catalog_destination_api_catalog__slug__get
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Catalog Destination Api Catalog  Slug  Get
        '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