eSIM operator kit

Contents

What you get
How a sale works
What you need
Quick start
Documents
Layout
Money and keys
Tests

Sell travel data eSIMs under your own name, to people on a website and to AI agents over x402. You need a wholesale account, a server and a domain. The kit is the whole shop: a storefront in five languages that takes crypto on ten networks, a seller node AI agents buy from, and the federation node that makes your offers findable on AIMarket hubs. You are the merchant, and buyers pay straight into your wallets.

Try it first: esim.modelmarket.dev runs this kit in demo mode with live wholesale prices and every page and checkout step. It takes no payment.

Read in: English · Русский · Español · Français · 中文

What you get

Part	What it does
Storefront (`store/`)	A page per country, which is what travellers search for. Plan filter, checkout, the eSIM's QR code and install link, and its data usage afterwards. In English, Russian, Spanish, French and Chinese.
Payments	USDC and USDT on Base, Ethereum, Arbitrum, OP, Polygon, BNB Chain and Avalanche. USDT on Tron, USDC on Solana, USDT and TON on TON. Cards through Stripe if you add it. Each method is on once you give it an address.
Seller node for agents (`rails/`)	`esim.quote` and `esim.status` are free and signed. `esim.order` is paid over x402 in USDC on Base.
Federation node (`node/`)	`aimarket node` publishes your capabilities to AIMarket hubs, so agents that search a hub find your offers.
HTTPS	Caddy on ports 80 and 443, with certificates from Let's Encrypt.

How a sale works

A buyer picks a plan. The price is your wholesale cost plus your margin (MARGIN_PCT, and never less than MIN_MARGIN_USD above cost). It holds for 20 minutes.
The buyer pays to your wallet. The store reads the network and confirms the payment itself. There is no payment processor in between.
The store buys the profile from your eSIM Access balance at the wholesale price. The buyer gets the QR code, the activation code and an install link. Their order page keeps working afterwards and shows the data used and the expiry date.
You keep the difference. Top up the wholesale balance as you sell.

An agent does the same over HTTP: POST /agents/quote, then POST /agents/order with an x402 payment, and the activation code comes in the answer. The payment settles only after the profile exists.

What you need

A wholesale account at eSIM Access with money on it. The first top-up is at least $50 (card, PayPal or Alipay). The balance pays for the eSIMs you sell, at the wholesale price.
A server with Docker and a public IPv4 address, with ports 80 and 443 open. 1 vCPU and 1 GB of memory are enough.
A domain or subdomain whose A record points at that server.
Wallet addresses for the networks you want to take. One EVM address serves all seven EVM networks. The kit asks for addresses only: never a private key, never a seed phrase.
Optional: a Coinbase Developer Platform API key. It enables gasless USDC on Base for people and the x402 payments agents make. Also optional: a Stripe account for cards.

Quick start

git clone https://github.com/alexar76/esim-operator-kit.git && cd esim-operator-kit
cp .env.example .env            # your domain, store name, margin, wallet addresses
# put the two eSIM Access keys in secrets/ (secrets/README.md lists the files)
mkdir -p data/store data/rails data/node data/caddy
sudo chown 1000:1000 secrets/* && sudo chown -R 1000:1000 data/store data/rails data/node
docker compose up -d --build

Open https://<your domain>/. The store runs in demo mode until you set DEMO_MODE=0. The operator guide walks through every step, the test order and going live.

Documents

Operator guide: from an empty server to the first sale, then daily operation, refunds, taxes and troubleshooting.
Agent guide: for developers of AI agents. Find an eSIM, buy it over x402, check its usage.
secrets/README.md: which key goes in which file.

Layout

docker-compose.yml   the four services
Caddyfile            HTTPS and routing: /agents/* to rails, /.well-known/ai-market.json and /ai-market/* to node, the rest to store
.env.example         every setting, with comments
secrets/             your keys, one per file (git-ignored, mounted read-only)
data/                orders, token keys, the node's identity, certificates (git-ignored; back it up)
store/               the storefront (Node.js, Express)
rails/               the seller node, and the wholesale client the store uses too
node/                the federation node image (aimarket-hub from PyPI)
docs/                these guides in five languages

Money and keys

Buyers pay straight to your addresses, and the store only reads the networks. There is no hot wallet and no key that could spend.
The activation code goes to the buyer and is never stored. The store fetches it from the wholesaler whenever the buyer's order page asks. The buyer's link carries a token, and the store keeps only its hash.
One payment buys one eSIM. The wholesale order id is derived from the payment, so a retry cannot buy twice.
Before the store asks for a payment, it checks that your wholesale balance covers the order.

Tests

cd rails && npm ci && npm test
cd ../store && npm ci && npm test

The tests need no network and no keys.