esimker Topups API

openapi: 3.2.0
info:
  title: esimker Topups 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: topups
paths:
  /api/topups/{iccid}:
    get:
      tags:
      - topups
      summary: List Topups
      description: 'Available top-ups for an ICCID: EA provides compatibility, prices come from our plans.


        Only for eSIMs issued by us, like get_usage — a top-up applies to one of

        our eSIMs anyway, so a stranger''s ICCID is turned away here instead of

        being probed into the supplier''s API and coming back as a 502.'
      operationId: list_topups_api_topups__iccid__get
      parameters:
      - name: iccid
        in: path
        required: true
        schema:
          type: string
          pattern: ^89\d{16,20}$
          title: Iccid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
                title: Response List Topups Api Topups  Iccid  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/usage/{iccid}:
    get:
      tags:
      - topups
      summary: Get Usage
      description: Remaining data. Only for eSIMs issued by us.
      operationId: get_usage_api_usage__iccid__get
      parameters:
      - name: iccid
        in: path
        required: true
        schema:
          type: string
          pattern: ^89\d{16,20}$
          title: Iccid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Usage Api Usage  Iccid  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