# VRIL/eSIM Complete Documentation Export (llms-full.txt) > Sovereign Global 5G Connectivity, Dual-Carrier Redundancy, and White-Label Telecom Infrastructure. > Full markdown export for AI and LLM agents. > Source: https://vsim.dev # VRIL/eSIM Documentation Platform Overview URL: https://vsim.dev/docs > Technical documentation hub covering REST API reference, TypeScript Node SDK, and White-Label Reseller Engine. Welcome to the VRIL/eSIM Developer and Partner Documentation Hub. VRIL provides sovereign global 5G cellular connectivity, automated dual-carrier failover, and white-label telecom infrastructure across 190+ countries. ## Documentation Tracks 1. [REST API Reference](/docs/api): Direct HTTP endpoints for package discovery, asynchronous eSIM profile provisioning, real-time consumption telemetry, and Whop webhooks. 2. [TypeScript & Node SDK Guide](/docs/sdk): Type-safe client library (`@vril-labs/esimaccess-api`) with automatic token rotation, cellular telemetry streams, and structured error handling. 3. [White-Label Reseller Engine](/docs/reseller): Partner wholesale volume tiers, custom CNAME domain routing (`cname.vsim.dev`), dynamic margin controls, and bulk fleet provisioning. ## LLM & AI Agent Access - Plain text documentation index: `https://vsim.dev/llms.txt` - Complete markdown documentation export: `https://vsim.dev/llms-full.txt` # eSIM Provisioning REST API Reference URL: https://vsim.dev/docs/api > Programmatic eSIM profile issuance, real-time carrier telemetry, and multi-carrier failover integration with REST API. The VRIL v1 REST API enables programmatic eSIM profile issuance, real-time carrier telemetry, and multi-carrier failover across 190+ countries. ## Base URL & Authentication - Production Base URL: `https://api.vsim.dev/v1` - Sandbox Base URL: `https://sandbox.api.vsim.dev/v1` - Header: `Authorization: Bearer vril_live_` - HMAC Signature (Optional for webhooks): `X-Vril-Signature: t=,v1=` ## Core Endpoints ### 1. GET /api/esim/packages Retrieve cached eSIM packages with country, carrier, price, and data balance metadata. Cached in Neon and refreshed every 6 hours. - Method: `GET` - Path: `/api/esim/packages?country=JP&type=local` - Response: 200 OK ```json { "success": true, "data": [ { "packageCode": "JP_10GB_30D", "country": "Japan", "countryCode": "JP", "dataMb": 10240, "durationDays": 30, "retailPriceUsd": 12.00, "carrier": "KDDI + SoftBank" } ] } ``` ### 2. POST /api/esim/orders Provision a new eSIM profile asynchronously. Fulfillment is triggered via webhook or instant order API, returning LPA activation string and QR image URL. - Method: `POST` - Path: `/api/esim/orders` - Headers: `Authorization: Bearer `, `Content-Type: application/json` - Body: ```json { "packageCode": "JP_10GB_30D", "customerEmail": "traveler@vsim.dev", "clientReferenceId": "REF-99201" } ``` - Response: 200 OK ```json { "orderNo": "ORD-2026-84920", "status": "processing", "iccid": "89814400000072184931", "qrCodeUrl": "https://cdn.vsim.dev/qr/89814400000072184931.png", "activationCode": "LPA:1$smdp.io$89814400000072184931" } ``` ### 3. GET /api/esim/sims/{iccid} Query real-time data consumption, active session status, remaining bytes, and expiration timestamp for a SIM profile. - Method: `GET` - Path: `/api/esim/sims/89814400000072184931` - Response: 200 OK ```json { "iccid": "89814400000072184931", "status": "ACTIVE", "totalDataBytes": 10737418240, "usedDataBytes": 3435973836, "remainingDataBytes": 7301444404, "expiresAt": "2026-09-26T18:30:00.000Z" } ``` ### 4. POST /api/webhooks/whop Webhook receiver for Whop membership, checkout, and cancellation events. Validated via HMAC signature. - Event: `membership.went_valid` triggers instant profile provisioning. # Node SDK & Developer Tooling Guide URL: https://vsim.dev/docs/sdk > Official TypeScript/Node.js client guide for @vril-labs/esimaccess-api and @vril-labs/sdk with end-to-end provisioning examples. The official TypeScript/Node.js client for VRIL and eSIM Access (`@vril-labs/esimaccess-api`, `@vril-labs/sdk`). Provides type-safe wrappers with automatic OAuth token rotation, exponential backoff, and cellular telemetry streams. ## Installation ```bash # Install via bun (recommended) bun add @vril-labs/esimaccess-api # Install via npm npm install @vril-labs/esimaccess-api ``` ## Quickstart ```typescript import { EsimAccessService } from '@/lib/esimaccess'; // Client automatically consumes ESIMACCESS_ACCESS_CODE & ESIMACCESS_SECRET_KEY const esim = EsimAccessService; // 1. Discover available packages in destination country const packages = await esim.getPackages({ locationCode: 'JP', type: 'local', }); console.log('Available packages:', packages.data.packageList.length); // 2. Provision asynchronous eSIM order const order = await esim.createOrder({ packageCode: 'JP_10GB_30D', price: 12.00, transactionId: 'TX-2026-001', }); console.log('Order status:', order.orderNo, order.status); // 3. Inspect active profile & telemetry const usage = await esim.getSimUsage('89814400000072184931'); console.log('Remaining MB:', usage.remainingDataMb); ``` ## High-Throughput Cellular Telemetry Query real-time network latency, multi-carrier failover events, and automated failover health: ```typescript import { VrilTelemetryClient } from '@vril-labs/client'; const telemetry = new VrilTelemetryClient({ apiKey: process.env.VRIL_API_KEY }); const health = await telemetry.network.checkStatus(); console.log('Active Tier-1 Carrier:', health.currentCarrier); console.log('Failover Status:', health.failoverReady ? 'ARMED' : 'STANDBY'); ``` ## Error Handling & Retry Policy The SDK implements automated 3-tier exponential backoff with jitter on 429 Rate Limited and 503 Carrier Gateway timeouts. All errors inherit from `VrilApiError` with structured codes: - `ERR_CARRIER_TIMEOUT`: Upstream carrier provisioning delayed; poll `order.status`. - `ERR_QUOTA_EXHAUSTED`: Account wholesale balance low. - `ERR_INVALID_ICCID`: Profile identifier checksum mismatch. # White-Label Reseller Engine & Partner Portal URL: https://vsim.dev/docs/reseller > Partner wholesale tiers, custom margin controls, CNAME white-labeling, and bulk provisioning for travel platforms. Empower your travel platform, airline booking flow, or nomad SaaS to resell global eSIM connectivity under your brand with custom margins, white-label CNAME routing, and automated delivery. ## Partner Wholesale Tiers & Margin Structure | Tier | Monthly Volume | Wholesale Discount | Dedicated Pool | Priority SLA | | :--- | :--- | :--- | :--- | :--- | | **Starter** | < $5,000 | 15% off retail | Shared | 4 hour | | **Growth** | $5,000 - $25,000 | 25% off retail | Regional Tier-1 | 1 hour | | **Enterprise** | > $25,000 | 35% off retail | Private APN + Multi-IMSI | 15 min | ## CNAME White-Labeling (Custom Domain Setup) You can serve the entire eSIM plan browser and checkout portal under your custom subdomain (e.g. `esim.yourbrand.com`). ### 1. DNS Configuration Add a CNAME record at your DNS provider: - **Type**: `CNAME` - **Name**: `esim` (or desired subdomain) - **Target**: `cname.vsim.dev` - **TTL**: Auto / 300 seconds ### 2. Automated SSL & Edge Routing Once DNS propagates, our Cloudflare edge automatically provisions a wildcard TLS certificate with zero maintenance. ## Custom Branding & Delivery Pipeline Configure custom branding in the Reseller Portal under `/dashboard/reseller`: - **Sender Identity**: Deliver transactional emails from `data@yourbrand.com`. - **Branded QR PDF**: White-label activation vouchers generated with your logo, brand primary color, and custom support links. - **Dynamic Markup Engine**: Configure percentage markups (e.g. +35%) or fixed dollar margins per destination country. ## Bulk Provisioning API & CSV Workflows Provision up to 500 eSIM profiles in a single batch for tour groups, corporate fleets, or conferences: 1. Upload CSV to `/reseller/customers` or dispatch to `POST /api/v1/orders/bulk`. 2. Asynchronous Inngest worker validates and issues profiles in parallel. 3. Webhook notification dispatched when all QR assets are compiled.