Kiosk - DIY ATM NFC

Ki0xk is a physical crypto ATM kiosk that lets anyone convert cash coins into USDC on their preferred blockchain — no wallet setup, no KYC, no
crypto knowledge required. Designed for festivals, pop-up events, and temporary venues where traditional payment infrastructure doesn't exist.

The kiosk operator pre-funds the system with USDC. When a user inserts physical coins, the system instantly credits their balance using Yellow Network's ClearNode for off-chain transfers. Users then choose how to receive their USDC: scan a QR code with their wallet address, type an ENS name, tap an NFC card, or get a PIN code to claim later. Settlement to real USDC on-chain happens via Circle's Arc Bridge (CCTP), supporting 7 chains including Base, Ethereum, Arbitrum, Polygon, Optimism, Avalanche, and Linea.

Festival mode turns any NFC-enabled object (wristband, card, keychain) into a reloadable crypto wallet. Attendees top up their NFC wallet with cash, then tap to pay at merchant booths — all settled on-chain through Circle Gateway. Merchants receive USDC directly on their preferred chain.

The hardware stack uses an Arduino Uno with a pulse-based coin acceptor for coin detection and a PC/SC NFC reader for contactless interactions, connected to a Next.js full-stack application with a retro arcade UI.

Ki0xk is a full-stack Next.js 16 application with React 19, built entirely in TypeScript. The frontend and backend live in a single codebase —
Next.js API routes handle all server-side logic including hardware communication, crypto transfers, and session management.

Yellow Network Integration (ClearNode) The core payment engine connects to Yellow Network's ClearNode via WebSocket for instant off-chain USDC transfers. When a user finishes inserting coins, the kiosk calls sendToWallet() through ClearNode to move funds from the operator's pre-funded unified balance to the user's destination. This is critical — Yellow 0.5.x has a constraint where users with any channel containing non-zero amounts cannot perform transfers, so we exclusively use unified balance mode. Authentication uses EIP-712 signed messages, and the boot sequence (connect → getConfig → getAssets → authenticate → getLedgerBalances → ready) runs automatically on server startup.

Circle Arc Bridge (CCTP) After the off-chain Yellow transfer, we bridge real USDC to the user's preferred chain using Circle's Cross-Chain Transfer Protocol via the Arc Bridge SDK. This supports 7 destination chains (Base, Ethereum, Arbitrum, Polygon, Optimism, Avalanche, Linea). For festival mode, we use Circle Gateway instead — a burn-and-mint model where the operator deposits USDC into Gateway, and merchant payments trigger direct mints on the merchant's preferred chain.

Hardware Layer An Arduino Uno with a CH-926 pulse-based coin acceptor detects physical coins via hardware interrupts. Each coin denomination produces a different pulse count (1-2 pulses = 1 peso, 5-10 = 2 pesos, 11-16 = 5 pesos) with 60ms debounce. The Arduino emits JSON over serial at 115200 baud. On the server side, Node.js reads the serial port using the serialport package and streams coin events to the browser via Server-Sent Events (SSE). NFC uses a dual-strategy approach: USB PC/SC readers (via nfc-pcsc) for physical kiosks, and the Web NFC API for phone-based demos — both unified under a single React hook.

Notable Hacks

• SSE streams for hardware events instead of WebSockets — simpler, works through Next.js API routes without a separate server, and auto-reconnects gracefully when the browser tab refocuses.
• Idempotency keys on every hardware event (timestamp + random) deduplicated client-side via a Set, preventing double-counting from bouncy physical inputs.
• NFC cards as crypto wallets — any NFC object gets a wallet ID written via NDEF. Balances are tracked server-side with PIN protection (SHA-256 hashed). This turns a $0.10 wristband into a reloadable payment card.
• PIN wallets for users with zero crypto experience — insert coins, get a 4-digit PIN and 6-character wallet ID printed on a receipt. Claim later from any device.
• Auto-zoom CSS scaling (clamp(1, min(vw/800, vh/500), 3)) and viewport-relative font sizing (clamp(10px, 2.2vh, 16px)) make the UI work on everything from a 7" tablet to a 32" touchscreen without any responsive breakpoints.
• All persistent state (sessions, PIN wallets, NFC card balances) uses flat JSON files — intentionally simple for a hackathon, no database required.

Stack: Next.js 16, React 19, TypeScript, Tailwind CSS v4, shadcn/ui (Radix), viem, yellow-ts, @circle-fin/bridge-kit, serialport, nfc-pcsc, Zod, Arduino/PlatformIO.