Base Sepolia Testnet Mode•Add Network•USDC Faucet•ETH Faucet

EscrowUSDCBase Network

How It Works

Secure eSIM purchases with USDC escrow protection on Base.

Overview

Our smart contract escrow system protects both buyers and sellers. When you purchase an eSIM, your USDC is held in escrow until you activate the eSIM on your device. If you don't activate within 7 days, your payment is automatically refunded.

USDC

Stablecoin on Base

7 Days

Escrow Protection

No Email

Privacy First

Auto

Refund if Not Activated

✓

Your funds are never at risk. The escrow contract is non-custodial and only releases funds when the eSIM is successfully activated on your device.

Escrow Flow

The escrow smart contract manages the complete payment lifecycle:

Payment Lifecycle

User                      Escrow Contract                 Merchant
  |                              |                              |
  |--- Approve USDC ----------->|                              |
  |                              |                              |
  |--- Select Plan ------------>|                              |
  |                              |                              |
  |      [holdPayment]          |                              |
  |--- USDC Locked ------------>|                              |
  |                              |                              |
  |<-- eSIM QR Code ------------|                              |
  |                              |                              |
  |--- Install & Activate ----->|                              |
  |                              |                              |
  |      [settlePayment]        |                              |
  |                              |--- USDC Released ---------->|
  |                              |                              |

  --- OR if not activated within 7 days ---

  |      [refund]               |                              |
  |<-- USDC Returned -----------|                              |

Approve USDC

Grant the escrow contract permission to transfer your USDC

Hold Payment

USDC is locked in the smart contract with a 7-day expiry

Receive eSIM

Get your activation QR code instantly after payment

Activate

Install the eSIM on your device to trigger settlement

Settle or Refund

Funds release to merchant on activation, or refund after 7 days

Smart Contract

The ESIMPayment contract manages escrows with the following key functions:

Function	Description
`holdPayment`	Lock USDC in escrow for an eSIM order
`settlePayment`	Release funds to merchant (eSIM activated)
`refund`	Return funds to user (after expiry)
`getEscrow`	View escrow details (amount, state, expiry)

Escrow States

State	Description
`None (0)`	No escrow exists for this eSIM ID
`Pending (1)`	USDC locked, awaiting activation
`Settled (2)`	eSIM activated, funds released to merchant
`Refunded (3)`	Funds returned to user

The contract is deployed on Base and uses OpenZeppelin's SafeERC20 for secure token transfers and ReentrancyGuard for protection against reentrancy attacks.

User Journey

1. Connect Wallet

Click "Connect Wallet" to link your wallet via WalletConnect. Supports MetaMask, Coinbase Wallet, Rainbow, and other popular wallets.

Supported: Any WalletConnect-compatible wallet on Base

2. Approve USDC

Approve the escrow contract to spend your USDC. This is a one-time approval per amount. You can set a specific amount or unlimited approval.

Transaction: ERC20 approve()

3. Complete Purchase

Confirm the purchase. The escrow contract transfers your USDC and locks it with a 7-day expiry. Your eSIM QR code appears immediately. No email required.

Transaction: holdPayment()

4. Save Your eSIM URL

Important: Bookmark or save your eSIM page URL. This is your only way to access your eSIM details, QR code, and data usage. We don't collect emails, so we can't send you a link.

Example: esimqr.link/web3/esim?id=your_esim_id

5. Install eSIM

Scan the QR code with your phone camera or go to Settings → Cellular → Add eSIM. The eSIM will be ready to use once you reach your destination.

Works on iPhone XS+ and most Android phones with eSIM support

No email = no recovery. Your wallet address is your identity. Save your eSIM page URL in a bookmark, note, or password manager. If you lose it, we cannot help you recover access.

Third-Party Integration

External websites and apps can initiate eSIM purchases by using our Quote API to get pricing and contract details, then redirecting users to complete the transaction.

Integration Flow

Fetch Quote

Call the Quote API with a package code to get the USDC price and contract addresses.

Display Price

Show the usdcAmount to your user with plan details.

Redirect to Purchase

Send users to esimqr.link/web3?package=US_1_7 to complete payment.

User Completes Purchase

User connects wallet, approves USDC, and receives their eSIM QR code.

Query Parameters

Parameter	Type	Description
`packageCode`*	string	Package slug (e.g., US_1_7) or API code
`periodNum`	integer	Number of days for daily plans (optional)

✓

Use the contractAddress and usdcAddress from the response if you want to build your own wallet integration instead of redirecting users.

Refund Policy

The escrow contract enforces automatic refunds for unactivated eSIMs:

Automatic Refund

If you don't install your eSIM within 7 days, anyone can call the refund() function to return your USDC. We run an automated job to process expired escrows.

Manual Cancellation

Need to cancel before 7 days? Contact support and we can process an early refund via the forceRefund() function (owner-only).

Once you activate the eSIM on your device, the payment is settled and cannot be refunded. Make sure the plan matches your travel needs before activating.

Security

Non-Custodial

Funds are held in a smart contract, not a centralized wallet. Only the contract logic controls fund movement.

Reentrancy Protected

OpenZeppelin's ReentrancyGuard prevents reentrancy attacks on all state-changing functions.

SafeERC20

Token transfers use OpenZeppelin's SafeERC20 to handle non-standard token implementations safely.

Time-Locked Refunds

Refunds are only possible after the 7-day expiry, preventing premature fund extraction.

Network Configuration

Network	Base Sepolia (testnet)
Chain ID	84532
USDC Token	0x036CbD53842c5426634e7929541eC2318f3dCF7e
Escrow Contract	0xf4cBAAF678F3Bb8e1Af20681121EE908E7B63235
Escrow Duration	7 days
USDC Decimals	6

This is currently configured for Base Sepolia testnet. Use testnet USDC for development. Production will use Base mainnet.

← Back to eSIM Store Agent API Docs →