Installation
install and run each of the four apps.

01Check your tools

flutter --version      # 3.41 or newer
flutter doctor         # fix anything red for iOS or Android
python3 --version      # 3.10 or newer, for Card Studio

See Requirements if something is missing.

02NFC Crypto (apps/nfc_crypto)

1. Open the folder. cd apps/nfc_crypto
2. Create your settings file. cp .env.example .env. Every value in it is optional; the app runs with the file as it is. See Configuration.
3. Get the packages. flutter pub get
4. Connect a phone with NFC (USB, or wireless debugging). For iOS, set your Apple team first (next section).
5. Run. flutter run --dart-define-from-file=.env

cd apps/nfc_crypto
cp .env.example .env
flutter pub get
flutter run --dart-define-from-file=.env

The first screen lets you create a new wallet or import one. Then open the Card tab to pair a card. On a simulator or emulator the card screens open, but no card can be read.

03Set your Apple team (iOS)

The projects ship without an Apple team. Before you run on an iPhone, set yours in one of two ways:

• NFC Crypto and CryptoCard Wallet: in ios/Flutter/, create Signing.local.xcconfig with one line, DEVELOPMENT_TEAM = YOUR_TEAM_ID (your 10-character Team ID from developer.apple.com → Account → Membership details). Debug.xcconfig and Release.xcconfig read this file when it exists, and git ignores it. CryptoCard has a ready template: in ios/Flutter/ run cp Signing.example.xcconfig Signing.local.xcconfig, then remove the // in front of the settings.

  

• Any app, including NFC Recovery: open ios/Runner.xcworkspace in Xcode → Runner target → Signing & Capabilities → choose your team.

Your App ID needs the NFC Tag Reading capability. NFC Crypto and CryptoCard Wallet also need Associated Domains (for card taps that open the app). With automatic signing, Xcode adds them from the entitlements files.

04CryptoCard Wallet (apps/cryptocard_wallet)

cd apps/cryptocard_wallet
flutter pub get
flutter run

No settings file is needed. A new install starts on the Sepolia test network (and Solana Devnet for Solana), so nothing of value moves until the user switches network on purpose (defaultNetworkId in lib/brand/brand_config.dart). Free test coins come from any Sepolia faucet and from faucet.solana.com.

The card host can be changed per build with --dart-define=CARD_HOST=cards.example.com. See White label.

05NFC Recovery (apps/nfc_recovery)

cd apps/nfc_recovery
flutter pub get
flutter run

The app only reads cards. It needs no settings file and no internet. Set your Apple team in Xcode before running on an iPhone.

06Card Studio (apps/card_studio)

macOS:

cd apps/card_studio
./run.sh              # with an ACR122U reader plugged in
./run.sh --simulate   # without a reader

Windows: double-click run.bat. In PowerShell you can use .\run.ps1; if Windows says running scripts is disabled, run powershell -ExecutionPolicy Bypass -File .\run.ps1.

The first start takes about a minute: the launcher creates a private Python environment (.venv) next to the app and installs argon2-cffi, cryptography and pyscard. Later starts are quick. If pyscard cannot be installed, the studio still starts and the simulated reader works; delete .venv/pyscard-skipped to try the install again.

The studio opens in your default browser. The terminal prints the address, for example http://127.0.0.1:57551/#…. Keep the terminal window open while you work; Ctrl+C quits.

Optional native window: install pywebview into the studio's environment (.venv/bin/pip install pywebview, on Windows .venv\Scripts\pip install pywebview).

07Run the tests (optional)

The tests need no phone, card or reader. They use simulated cards.