Back to Home
Docs v1.2

Mikachan
Developer Docs

Everything you need to integrate private, offline-ready tap-to-pay into your Web3 application.

Introduction

Welcome to the Mikachan developer documentation. Mikachan is a decentralized protocol designed to bridge the gap between digital Web3 assets and physical point-of-sale (POS) systems.

By utilizing Zero-Knowledge Proofs (zk-SNARKs) over standard Near Field Communication (NFC), Mikachan enables secure, private, and offline-capable tap-to-pay transactions.

Quickstart Guide

Get up and running with the Mikachan SDK in minutes. First, install the package via npm or yarn:

bash
npm install @mikachan/sdk

Initialize the client with your API key and preferred network:

typescript
import { MikachanClient } from '@mikachan/sdk';

const client = new MikachanClient({
  apiKey: process.env.MIKACHAN_API_KEY,
  network: 'mainnet',
  environment: 'production'
});

// Initialize the NFC listener
await client.startNfcListener();

ZK-NFC Integration

The core of Mikachan's privacy lies in its ZK-NFC payload. When a user taps their device, the SDK automatically generates a zk-SNARK proof asserting that the user has sufficient funds and controls the necessary private keys, without revealing the actual address or balance.

Note: Proof generation happens locally on the user's device within a secure enclave (if available) or via highly optimized WebAssembly modules.

As a merchant integrator, you only need to listen for the `onPaymentReceived` event, which guarantees the proof has been cryptographically verified by the SDK.

x402 Offline Settlement

The x402 protocol allows transactions to be buffered locally when the merchant terminal is offline. The SDK handles the queuing and optimistic verification of ZK-proofs.

Once internet connectivity is restored, the SDK automatically flushes the queue, settling all buffered transactions on-chain. You can monitor the queue status using the `client.getQueueStatus()` method.

Smart Contracts

Mikachan's smart contracts are deployed on multiple EVM-compatible networks. They handle the final verification of ZK-proofs and the state transitions for the shielded pool.

For direct contract interactions, refer to our ABI documentation and deployed contract addresses in the developer portal.

REST API

While the SDK is the recommended way to integrate Mikachan, we also provide a REST API for backend services that need to query transaction status, retrieve historical data, or manage merchant accounts.

http
GET /v1/transactions/status?id=tx_12345 Authorization: Bearer YOUR_API_KEY

JavaScript SDK

The `@mikachan/sdk` provides a comprehensive set of tools for both Node.js and browser environments. It includes built-in support for NFC hardware abstraction, ZK-proof generation, and x402 queue management.

Full API reference for the SDK classes and methods is available in our typedoc generated documentation.

Error Codes

When an operation fails, the Mikachan API and SDK return standardized error codes to help you diagnose the issue.

  • ERR_INSUFFICIENT_FUNDS: The user's shielded balance is too low.
  • ERR_INVALID_PROOF: The provided ZK-proof failed cryptographic verification.
  • ERR_NFC_TIMEOUT: The NFC connection was lost before the payload was fully transmitted.
  • ERR_DOUBLE_SPEND: The nullifier has already been used.