eSIM Tabby

Find travel eSIM data plans available for a destination.

{
  "type": "object",
  "properties": {
    "country": {
      "description": "Country or region name, or ISO 3166-1 alpha-2 code",
      "type": "string"
    },
    "min_data_mb": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Only plans with at least this much data"
    },
    "max_duration_days": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Only plans lasting at most this many days"
    }
  },
  "required": [
    "country"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "result": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "x-fastmcp-wrap-result": true
}

Full details of one eSIM plan, including current price.

{
  "type": "object",
  "properties": {
    "plan_id": {
      "description": "plan_id from search_esim_plans",
      "type": "string"
    }
  },
  "required": [
    "plan_id"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

Start a purchase — the step after the user picks a plan from search_esim_plans. Call it with that plan's plan_id (get_plan_details shows the current price first). Returns an order_id and where to pay, on the rail you asked for: 'card' (the default) returns a checkout_url — a hosted Stripe page for a human to open in a browser; once they say they've paid, call get_order_status to confirm and carry on to the QR code. 'x402' returns an x402_url for a wallet to settle in USDC, with no browser step — only choose it if you actually hold a wallet. Never accepts payment details — a card is entered on the hosted page, and a wallet signs for itself. Calling it again for the same plan reuses the pending order (reused: true) instead of creating a duplicate.

{
  "type": "object",
  "properties": {
    "plan_id": {
      "description": "plan_id from search_esim_plans",
      "type": "string"
    },
    "pay_with": {
      "default": "card",
      "description": "How the buyer intends to pay. 'card' returns a hosted checkout link for a human to open in a browser. 'x402' returns an x402_url for a wallet tool to settle in USDC, with no browser step — only choose it if you have a wallet. An order keeps the rail it was first given: to pay an existing card order in USDC instead, cancel it and start a new one, so there are never two live ways to pay it.",
      "enum": [
        "card",
        "x402"
      ],
      "type": "string"
    }
  },
  "required": [
    "plan_id"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

Pay for an order in USDC over x402, without opening a browser. Only for an MCP client that signs x402 payments itself: call it once for the payment requirements, then repeat the call carrying the signed payment in _meta['x402/payment'] and it settles and starts the eSIM. If your wallet is a separate tool, make an x402 request to the order's x402_url instead — this tool cannot take a payment on a wallet tool's behalf.

{
  "type": "object",
  "properties": {
    "order_id": {
      "description": "order_id from create_checkout",
      "type": "string"
    }
  },
  "required": [
    "order_id"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "x402Version": {
      "type": "integer"
    },
    "accepts": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "x402 payment requirements to satisfy"
    },
    "error": {
      "type": "string",
      "description": "How to pay, for the 402 case"
    },
    "order_id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "transaction": {
      "type": "string",
      "description": "On-chain transaction hash"
    },
    "paid_with": {
      "type": "string"
    },
    "next_step": {
      "type": "string"
    },
    "result": {
      "type": "string"
    }
  },
  "description": "Without a payment: the x402 payment requirements (accepts, error). With one: the settled order (transaction, next_step), or the unchanged order plus `result` when it was no longer awaiting payment.",
  "additionalProperties": true
}

Check an order. Call this after the user says they've paid. Not read-only: an order still in progress is advanced first — payment is confirmed and the provider order placed or collected — so the status can change as a result of calling this.

{
  "type": "object",
  "properties": {
    "order_id": {
      "description": "order_id from create_checkout",
      "type": "string"
    }
  },
  "required": [
    "order_id"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

Get the QR code and activation details for a purchased eSIM. Not read-only: like get_order_status, an order that is not ready yet is advanced first, so this can change the order's state.

{
  "type": "object",
  "properties": {
    "order_id": {
      "description": "order_id of a fulfilled order",
      "type": "string"
    }
  },
  "required": [
    "order_id"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "order_id": {
      "description": "The order this eSIM belongs to",
      "title": "Order Id",
      "type": "string"
    },
    "iccid": {
      "description": "The eSIM's ICCID",
      "title": "Iccid",
      "type": "string"
    },
    "qr_code_url": {
      "description": "Image URL of the activation QR code",
      "title": "Qr Code Url",
      "type": "string"
    },
    "activation_code": {
      "description": "LPA activation string, for manual install",
      "title": "Activation Code",
      "type": "string"
    },
    "smdp_address": {
      "description": "SM-DP+ server address, for manual install",
      "title": "Smdp Address",
      "type": "string"
    },
    "expires_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the plan expires, in the provider's own format",
      "title": "Expires At"
    },
    "instructions": {
      "description": "How to install the eSIM",
      "title": "Instructions",
      "type": "string"
    }
  },
  "required": [
    "order_id",
    "iccid",
    "qr_code_url",
    "activation_code",
    "smdp_address",
    "expires_at",
    "instructions"
  ],
  "description": "What `get_esim_activation` returns.\n\nThe other tools annotate their return type and FastMCP derives the schema from it.\nThis one hands back a ToolResult — the QR has to reach the reply body as markdown —\nso the type goes here instead and the schema is derived from it below.",
  "title": "Activation"
}

Data top-ups that can be added to an eSIM the user already has. A top-up extends the existing eSIM — same QR code, nothing to re-install. Not every plan is reloadable; this returns an empty list when none apply.

{
  "type": "object",
  "properties": {
    "order_id": {
      "description": "order_id of a fulfilled eSIM to add data to",
      "type": "string"
    }
  },
  "required": [
    "order_id"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "result": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "x-fastmcp-wrap-result": true
}

Buy more data for an eSIM the user already has — the step after list_topup_options. Call it with the order_id of the fulfilled eSIM and a plan_id chosen from list_topup_options. The top-up lands on the existing eSIM: same QR code, nothing to re-install. Returns a new order_id and where to pay, exactly like create_checkout: 'card' returns a checkout_url for a human to open, confirmed via get_order_status; 'x402' returns an x402_url for a wallet to settle in USDC. Never accepts payment details — a card is entered on the hosted page, and a wallet signs for itself.

{
  "type": "object",
  "properties": {
    "order_id": {
      "description": "order_id of the eSIM to add data to",
      "type": "string"
    },
    "plan_id": {
      "description": "plan_id from list_topup_options",
      "type": "string"
    },
    "pay_with": {
      "default": "card",
      "description": "How the buyer intends to pay. 'card' returns a hosted checkout link for a human to open in a browser. 'x402' returns an x402_url for a wallet tool to settle in USDC, with no browser step — only choose it if you have a wallet. An order keeps the rail it was first given: to pay an existing card order in USDC instead, cancel it and start a new one, so there are never two live ways to pay it.",
      "enum": [
        "card",
        "x402"
      ],
      "type": "string"
    }
  },
  "required": [
    "order_id",
    "plan_id"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

How much data an active eSIM has used, and how much is left.

{
  "type": "object",
  "properties": {
    "order_id": {
      "description": "order_id of a fulfilled order",
      "type": "string"
    }
  },
  "required": [
    "order_id"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

Cancel an order and refund it. Only possible while the eSIM is uninstalled. Once the profile has been installed on a device the provider refuses to take it back, and this returns an error instead — send the user to support. Card payments refund automatically. A USDC payment has no on-chain refund rail, so the order becomes `refund_pending` and support returns the money by hand.

{
  "type": "object",
  "properties": {
    "order_id": {
      "description": "order_id of the order to cancel",
      "type": "string"
    }
  },
  "required": [
    "order_id"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

List this account's eSIM orders, newest first.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "result": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "x-fastmcp-wrap-result": true
}