Integration Guide

Everything you need to set up Sender MultiSend for production use on Arc Testnet.

1. Environment Setup

Copy .env.example to .env.local and fill in the following:

Variable	Description	Required
CIRCLE_API_KEY	Circle developer API key — from console.circle.com
CIRCLE_WALLET_SET_ID	Circle wallet set UUID for developer-controlled wallets
CIRCLE_ENTITY_SECRET	32-byte hex entity secret for signing (never expose to browser)
NEXT_PUBLIC_CIRCLE_APP_ID	Public Circle App ID for browser SDK integration
NEXT_PUBLIC_ARC_TESTNET_RPC_URL	Arc Testnet JSON-RPC endpoint URL
NEXT_PUBLIC_ARC_TESTNET_CHAIN_ID	Arc Testnet EVM chain ID (verify from docs.arc.network)
NEXT_PUBLIC_USDC_CONTRACT_ADDRESS	USDC ERC-20 contract on Arc Testnet
NEXT_PUBLIC_EURC_CONTRACT_ADDRESS	EURC ERC-20 contract on Arc Testnet
NEXT_PUBLIC_MULTISEND_CONTRACT_ADDRESS	Deployed MultiSend.sol contract address (fallback to sequential if unset)	Optional
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID	WalletConnect Cloud project ID — cloud.walletconnect.com

2. Arc Testnet Configuration

Arc Testnet is an EVM-compatible blockchain. Confirm the correct Chain ID and RPC URL from docs.arc.network then update NEXT_PUBLIC_ARC_TESTNET_CHAIN_ID and NEXT_PUBLIC_ARC_TESTNET_RPC_URL.

The chain ID 12321 is a placeholder. Verify the actual Arc Testnet chain ID before deploying.

3. Circle SDK Setup

1Sign up at console.circle.com and create an API key.
2Create a Developer-Controlled Wallet Set for your app and note the Wallet Set ID.
3Generate a 32-byte entity secret: openssl rand -hex 32 — store it securely.
4Upload your entity secret's public key ciphertext to Circle Console (see Circle docs for the RSA encryption step).
5Get your App ID from Circle Console → App Settings and set it as NEXT_PUBLIC_CIRCLE_APP_ID.
6Fetch Circle token IDs for Arc Testnet via GET /v1/w3s/token/catalog and set them in circle-adapter.ts.

The Circle adapter at src/lib/blockchain/circle-adapter.ts is fully typed and isolated. Replace the fetch calls with the official @circle-fin/developer-controlled-wallets SDK when available.

4. MultiSend Contract Deployment

The contract at contracts/MultiSend.sol provides gas-optimized batch transfers. Deploy it to Arc Testnet using Hardhat or Foundry:

# Hardhat
npx hardhat run scripts/deploy.ts --network arc-testnet

# Foundry
forge create contracts/MultiSend.sol:MultiSend \
  --rpc-url $NEXT_PUBLIC_ARC_TESTNET_RPC_URL \
  --private-key $DEPLOYER_PRIVATE_KEY

Set the deployed address in NEXT_PUBLIC_MULTISEND_CONTRACT_ADDRESS. If this variable is not set (equals 0x000...000), the app falls back to sequential ERC-20 transfers automatically.

5. Token Contract Addresses

USDC and EURC must be deployed or located on Arc Testnet. Once you have the addresses, set:

NEXT_PUBLIC_USDC_CONTRACT_ADDRESS=0x...
NEXT_PUBLIC_EURC_CONTRACT_ADDRESS=0x...

Contact Circle via their developer portal to get testnet USDC/EURC faucet access for Arc Testnet.

6. Vercel Deployment

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod

# Set env vars via Vercel dashboard or CLI:
vercel env add CIRCLE_API_KEY production
vercel env add CIRCLE_WALLET_SET_ID production
vercel env add CIRCLE_ENTITY_SECRET production

Never expose CIRCLE_API_KEY, CIRCLE_ENTITY_SECRET, or CIRCLE_WALLET_SET_ID to the browser. These are server-side only.

7. Architecture Overview


src/
├── app/                         # Next.js App Router
│   ├── layout.tsx               # Root layout + Providers
│   ├── page.tsx                 # Landing page
│   └── app/
│       ├── layout.tsx           # Dashboard shell + AppHeader
│       ├── page.tsx             # Dashboard (main UI)
│       ├── history/page.tsx     # Transaction history
│       └── docs/page.tsx        # This page
│
├── components/
│   ├── ui/                      # Primitive UI components
│   ├── layout/                  # Header, WalletConnectButton, Providers
│   └── dashboard/               # Feature components (table, summary, CSV modal)
│
├── lib/
│   ├── blockchain/
│   │   ├── provider.ts          # Arc Testnet viem client + chain config
│   │   ├── tokens.ts            # Token registry + ERC-20 ABI + formatters
│   │   ├── multisend.ts         # Batch execution logic + MultiSend ABI
│   │   └── circle-adapter.ts   # Circle API adapter (plug-in, replaceable)
│   ├── hooks/
│   │   ├── use-token-balances.ts  # TanStack Query: on-chain balances
│   │   └── use-batch-execution.ts # useMutation: validate + execute batch
│   ├── store/
│   │   └── batch-store.ts       # Zustand: recipients, history, address book
│   ├── utils/
│   │   ├── csv.ts               # CSV/XLSX parse + export
│   │   └── validation.ts        # Address + amount validators
│   └── wagmi-config.ts          # wagmi v2 config (MetaMask + WalletConnect)
│
└── types/index.ts               # All domain TypeScript types