# EsimTao Full Platform & Travel eSIM Architecture Documentation (llms-full.txt)

> Version: 2026.8 | Canonical Base URL: https://www.esimtao.com
> Contact / Support: admin@esimtao.com | AI Agent Registration: https://www.esimtao.com/auth.md
> Formats: OpenAPI 3.1, MCP (Model Context Protocol), RFC 9727 API Catalog, Agent Skills

---

## 1. System Overview & Core Philosophy

EsimTao is an autonomous, open global travel eSIM search, comparison, and connectivity platform. It aggregates and normalizes over 560+ prepaid travel eSIM data plans across 100+ destinations worldwide, connecting travelers, digital nomads, and autonomous AI agents with verified telecommunications providers including Airalo, Nomad, Ubigi, Holafly, Maya Mobile, and Jetpac.

### Key Capabilities
- **Real-Time Price & Feature Comparison**: Continuous indexing of data allowances (1GB to Unlimited), validity periods (1 to 90 days), carrier roaming tiers (5G NR / 4G LTE), hotspot / tethering policies, and eKYC (Real-Name Identity Verification) mandates.
- **Hardware Compatibility Engine**: Multi-brand, cross-variant validation for Apple iOS, iPadOS, Google Android (Samsung One UI, Google Pixel, Xiaomi HyperOS) including regional hardware differences (e.g., dual physical nano-SIM models sold in Mainland China, Hong Kong, and Macao).
- **Travel Data Usage Estimator**: Quantitative modeling of daily gigabyte requirements across travel scenarios (navigation, photo uploads, video calls, streaming, remote work hotspot).
- **AI Agent Protocols (A2A & MCP)**: Full compatibility with autonomous tool-calling agents via OpenAPI 3.1, A2A MCP Server Card, and Auth.md specification for high-throughput execution.
- **Multi-Currency Normalization**: Real-time FX conversion across USD, CNY, EUR, GBP, JPY, CAD, and HKD.

---

## 2. Machine API Reference & Data Schemas

### 2.1 Public Search API: `GET /api/plans`
Retrieves the real-time catalog of travel eSIM plans with optional query filtering.

#### Endpoint
`GET https://www.esimtao.com/api/plans`

#### Query Parameters
- `destination` (string, optional): Target country or region (e.g., `Japan`, `United States`, `Europe`, `Thailand`, `United Kingdom`).
- `data_min` (number, optional): Minimum data allowance in GB.
- `data_max` (number, optional): Maximum data allowance in GB.
- `days` (integer, optional): Desired plan validity duration in days (e.g. `7`, `15`, `30`).
- `unlimited` (boolean, optional): Set to `true` to filter for unlimited data plans.
- `hotspot` (boolean, optional): Set to `true` to require mobile hotspot/tethering support.
- `kyc` (string, optional): Filter by identity verification requirement (`none`, `required`).
- `network` (string, optional): Cellular network generation (`5G`, `4G`).
- `sort` (string, optional): Sort order (`price_asc`, `price_desc`, `data_desc`, `rating_desc`).
- `currency` (string, optional): Currency code (`USD`, `CNY`, `EUR`, `GBP`, `JPY`, `CAD`, `HKD`). Default: `USD`.

#### JSON Response Schema
```json
{
  "status": "success",
  "total": 560,
  "data": [
    {
      "id": "jp-airalo-10gb-30d",
      "provider": "Airalo",
      "planName": "Moshi Moshi 10GB",
      "destination": "Japan",
      "dataAmountGb": 10,
      "unlimited": false,
      "durationDays": 30,
      "priceUsd": 18.00,
      "priceLocalized": 18.00,
      "currency": "USD",
      "network": "5G / 4G",
      "operator": "SoftBank / KDDI AU",
      "hotspotSupported": true,
      "kycRequired": false,
      "apn": "globaldata",
      "rating": 4.8,
      "reviewCount": 1420,
      "affiliateUrl": "https://www.airalo.com/japan-esim?coupon=ESIMTAO10",
      "features": ["Instant QR delivery", "Hotspot supported", "Zero KYC required"]
    }
  ]
}
```

### 2.2 Currency Rates API: `GET /api/exchange-rates`
Returns real-time foreign currency exchange base rates against USD.

#### Endpoint
`GET https://www.esimtao.com/api/exchange-rates`

#### JSON Response
```json
{
  "base": "USD",
  "timestamp": 1771890000,
  "rates": {
    "USD": 1.0,
    "CNY": 7.25,
    "EUR": 0.92,
    "GBP": 0.78,
    "JPY": 154.5,
    "CAD": 1.38,
    "HKD": 7.82
  }
}
```

### 2.3 Agent MCP Server Card: `GET /.well-known/mcp/server-card.json`
Provides Model Context Protocol server capabilities for agent tool execution.

---

## 3. Device Compatibility Matrix & Regional Nuances

eSIM (embedded SIM) requires a dedicated eUICC hardware chip built onto the smartphone motherboard.

### 3.1 Apple iPhone Compatibility
- **Supported Models**:
  - iPhone 16, 16 Plus, 16 Pro, 16 Pro Max
  - iPhone 15, 15 Plus, 15 Pro, 15 Pro Max
  - iPhone 14, 14 Plus, 14 Pro, 14 Pro Max
  - iPhone 13, 13 mini, 13 Pro, 13 Pro Max
  - iPhone 12, 12 mini, 12 Pro, 12 Pro Max
  - iPhone 11, 11 Pro, 11 Pro Max
  - iPhone XS, XS Max, XR
  - iPhone SE (2nd gen 2020, 3rd gen 2022)
- **CRITICAL HARDWARE EXCEPTIONS**:
  - **Mainland China iPhones**: All iPhones manufactured for Mainland China feature dual physical SIM slots and **DO NOT** contain an eSIM chip (except cellular iPad models).
  - **Hong Kong & Macao iPhones**: iPhone XS, 11, 12, 13, 14, 15, 16 standard/Pro models from HK/Macao feature dual physical nano-SIM trays and do not support eSIM. Only iPhone 13 mini, 12 mini, SE (2nd/3rd gen), and iPhone XS support eSIM in HK/Macao editions.
  - **US Carrier Locks**: US iPhones purchased on installment contracts (AT&T, Verizon, T-Mobile) must be network-unlocked before installing international travel eSIMs.

### 3.2 Samsung Galaxy Compatibility
- **Supported Models**:
  - Galaxy S24, S24+, S24 Ultra
  - Galaxy S23, S23+, S23 Ultra, S23 FE
  - Galaxy S22, S22+, S22 Ultra
  - Galaxy S21, S21+, S21 Ultra 5G
  - Galaxy S20, S20+ 5G, S20 Ultra 5G (US Carrier variants may differ)
  - Galaxy Z Fold 6, Z Flip 6, Z Fold 5, Z Flip 5, Fold 4, Flip 4, Fold 3, Flip 3
  - Galaxy Note 20, Note 20 Ultra 5G
- **Exceptions**: Samsung devices manufactured for the Mainland China, Hong Kong, and Taiwan markets generally disable eSIM functionality in favor of dual physical SIM slots.

### 3.3 Google Pixel Compatibility
- **Supported Models**:
  - Pixel 9, 9 Pro, 9 Pro XL, 9 Pro Fold
  - Pixel 8, 8 Pro, 8a
  - Pixel 7, 7 Pro, 7a
  - Pixel 6, 6 Pro, 6a
  - Pixel 5, 5a 5G
  - Pixel 4, 4 XL, 4a, 4a 5G
  - Pixel 3, 3 XL, 3a, 3a XL (Global editions)

---

## 4. Destination Guides & Carrier Matrix

| Destination | Primary Local Carriers | Best Roaming Tier | KYC Mandate | Average Daily Cost | Top Recommended Provider |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **Japan** | SoftBank, NTT Docomo, KDDI | 5G NR / 4G LTE | No | $1.20 - $2.50 | Airalo / Ubigi |
| **United States** | T-Mobile, AT&T, Verizon | 5G Ultra Capacity | No | $1.50 - $3.50 | Nomad / T-Mobile |
| **Europe (33+ Co.)** | Vodafone, Orange, O2, TIM | 5G / 4G LTE | No | $1.10 - $2.80 | Airalo / Maya Mobile |
| **United Kingdom** | EE, Vodafone, Three UK, O2 | 5G NR | No | $1.00 - $2.50 | giffgaff / Nomad |
| **Thailand** | AIS, TrueMove H, DTAC | 5G Max Speed | No (Pre-registered) | $0.90 - $1.80 | Airalo / DTAC |
| **South Korea** | SK Telecom, KT, LG U+ | 5G mmWave / Sub-6 | No (Data only) | $1.50 - $3.00 | LG U+ / Nomad |
| **Hong Kong** | CSL, SmarTone, 3 HK | 5G NR | Yes (Real-name law) | $1.00 - $2.20 | Airalo / Birdie |
| **Taiwan** | Chunghwa, Taiwan Mobile, FET | 5G High Speed | No | $1.20 - $2.40 | Chunghwa / Nomad |
| **Singapore** | Singtel, StarHub, M1 | 5G Standalone | Yes (Some carriers) | $1.10 - $2.00 | Singtel / Airalo |

---

## 5. Travel Data Usage Calculation Guidelines

Recommended daily allowances based on real-world consumption:
1. **Light User (0.5GB - 1.0GB / Day)**:
   - Google Maps / Apple Maps navigation (2-3 hours)
   - Messaging (WhatsApp, WeChat, iMessage, LINE)
   - Web search, translation tools (Google Translate / DeepL)
   - Light email checks
2. **Moderate User (1.5GB - 2.5GB / Day)**:
   - All light usage tasks
   - Social media feed browsing with videos (Instagram Reels, TikTok, RedNote, YouTube 1080p)
   - Photo cloud synchronization (Google Photos / Apple iCloud)
   - Ride-hailing apps (Uber, Grab, GO)
3. **Heavy / Digital Nomad User (3.0GB - 5.0GB+ / Day or Unlimited)**:
   - Video conferencing (Zoom, Google Meet, Microsoft Teams)
   - Laptop tethering via mobile hotspot
   - 4K video streaming and raw camera photo/video cloud uploads
   - Large file attachments and VPN tunneling

---

## 6. eSIM Installation & Activation Workflow

### 6.1 Installation via QR Code (Recommended)
1. Ensure the smartphone is connected to a stable Wi-Fi network (hotel, airport, or home).
2. Open device settings:
   - **iOS**: `Settings` > `Cellular` (or `Mobile Service`) > `Add eSIM`.
   - **Samsung**: `Settings` > `Connections` > `SIM manager` > `Add mobile plan` (or `Add eSIM`).
   - **Pixel**: `Settings` > `Network & internet` > `SIMs` > `+` > `Download a SIM instead?`.
3. Point camera at the QR code sent via email or displayed on the EsimTao confirmation screen.
4. Confirm profile download and label the newly installed eSIM line (e.g., `Travel Japan` or `Airalo`).

### 6.2 Manual LPA Code Entry (When QR cannot be scanned on the same screen)
If the QR code cannot be scanned directly, copy and paste the manual activation string:
- **SM-DP+ Address**: (e.g. `rsp.airalo.com` or `lpa.esim.global`)
- **Activation Code**: (e.g. `CONF-XX99881234`)
- **Combined LPA Syntax**: `LPA:1$SM-DP_ADDRESS$ACTIVATION_CODE`

### 6.3 Activation upon Destination Arrival
1. Turn off Data Roaming on your domestic primary SIM to prevent exorbitant carrier roaming fees.
2. Turn ON the Travel eSIM line.
3. Enable **Data Roaming** on the Travel eSIM line.
4. Set **Cellular Data** to the Travel eSIM line while keeping your primary line active for SMS 2FA verification if desired.
5. If internet does not connect within 2 minutes, check the carrier's specified APN setting (e.g., set APN to `globaldata` or `internet`).

---

## 7. Comprehensive Troubleshooting & Error Resolution

| Error / Symptom | Primary Cause | Immediate Fix |
| :--- | :--- | :--- |
| **"PDP Authentication Failure"** | APN field is empty or incorrect | Go to `Cellular Data Network` settings and enter the exact APN provided by the carrier (e.g., `globaldata`, `dtag`, `emov`). Restart phone. |
| **"Could Not Activate eSIM"** | No Wi-Fi during download or server timeout | Verify internet connection on Wi-Fi. Do not delete the eSIM profile. Toggle Airplane Mode on and off. |
| **"No Service" / "Searching..."** | eSIM line turned on before arriving in target country, or Data Roaming is disabled | Verify you have landed in the destination country. Ensure `Data Roaming` is toggled ON under the eSIM settings. |
| **"Hotspot / Tethering Not Working"** | APN for Personal Hotspot is blank | Navigate to `Cellular` > `Cellular Data Network` > scroll down to `Personal Hotspot` and enter the identical APN name used in Cellular Data. |
| **"Cannot Add eSIM: SIM Locked"** | Phone is carrier-locked to an original telecom network | Contact your home carrier (AT&T, Verizon, NTT Docomo, etc.) to request a SIM network unlock. |

---

## 8. Provider Feature Comparison

- **Airalo**: World's leading travel eSIM store. Strongest coverage across 200+ countries, local and regional eSIMs, intuitive native iOS/Android apps, Airmoney loyalty reward program, 24/7 customer support.
- **Nomad**: High-speed premium data plans with direct partnerships with tier-1 regional carriers (e.g., SoftBank Japan, Singtel, AIS). Flexible add-on data top-ups without re-installing new eSIM profiles.
- **Ubigi**: Specialized in direct cellular routing with ultra-low latency and trans-global 5G connectivity. Excellent for Japan (NTT Docomo partnership) and connected vehicles.
- **Holafly**: Famous for true unlimited data packages with customizable day validity (1 to 90 days). Great for travelers who do not want to monitor gigabyte quotas.
- **Maya Mobile**: Flexible 30-day plans with automatic renewal option, comprehensive Europe-wide 5G access, and full mobile hotspot tethering.
- **Jetpac**: Affordable packages backed by Circles.Life with complimentary airport lounge access passes (SmartDelay) during flight delays.

---

## 9. Frequently Asked Questions (FAQs)

**Q1: Can I keep my WhatsApp, iMessage, and WeChat number when using an eSIM?**
Yes. WhatsApp, iMessage, Telegram, and WeChat bind to your account and phone number independently of the cellular data connection. You will keep all chat histories and contacts intact.

**Q2: Can I receive bank SMS 2FA codes while traveling?**
Yes. Keep your primary physical SIM line turned ON for Calls & SMS, but turn Data Roaming OFF for that primary line. Assign Cellular Data exclusively to your Travel eSIM. Incoming SMS messages are typically free on most global operators.

**Q3: Can I delete and reinstall an eSIM profile on another phone?**
Generally NO. Most travel eSIM activation QR codes are one-time use tokens. Once activated on a specific device's eUICC chip, the profile cannot be transferred to another phone unless explicitly supported by the provider's app.

**Q4: When does my eSIM validity period start counting?**
For 95% of travel eSIMs, the validity countdown starts only when the eSIM connects to a supported local cellular network in the destination country, not when you scan the QR code at home.

---

*Document compiled and served by EsimTao Global Travel eSIM Engine.*
*Open standards: https://www.esimtao.com/llms.txt | https://www.esimtao.com/api/openapi.json*