Arc Commerce

This project demonstrates how to integrate USDC as a payment method for purchasing credits on Arc.

Table of Contents

• Prerequisites
• Clone and Run Locally
• Environment Variables
• User Accounts

Prerequisites

• Node.js v22+ — Install via nvm (nvm use will read the .nvmrc file)
• Supabase CLI — Install via npm install -g supabase or see Supabase CLI docs
• Docker Desktop (only if using the local Supabase path) — Install Docker Desktop

Clone and Run Locally

1. Clone and install dependencies:

   git clone git@github.com:circlefin/arc-commerce.git
   cd arc-commerce
   npm install

2. Set up the database — Choose one of the two paths below:

   Path 1: Local Supabase (Docker)

   Requires Docker Desktop installed and running.

   npx supabase start
   npx supabase migration up

   The output of npx supabase start will display the Supabase URL and API keys needed in the next step.

   Path 2: Remote Supabase (Cloud)

   Requires a Supabase account and project.

   npx supabase link --project-ref <your-project-ref>
   npx supabase db push

   Retrieve your project URL and API keys from the Supabase dashboard under Settings → API.

3. Set up environment variables:

   cp .env.example .env.local

   Then edit .env.local and fill in all required values. Use the Supabase URL and keys from the previous step's output (see Environment Variables section below).

4. Start the development server:

   npm run dev

   The app will be available at http://localhost:3000. The admin wallet will be automatically created on first startup.

5. Set up Circle Webhooks:

   In a separate terminal, start ngrok to expose your local server:

   ngrok http 3000

   Copy the HTTPS URL from ngrok (e.g., https://your-ngrok-url.ngrok.io) and add it to your Circle Console webhooks section:

   • Navigate to Circle Console → Webhooks
   • Add a new webhook endpoint: https://your-ngrok-url.ngrok.io/api/circle/webhook
   • Keep ngrok running while developing to receive webhook events

Environment Variables

Copy .env.example to .env.local and fill in the required values:

# Supabase
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_OR_ANON_KEY=
SUPABASE_SECRET_KEY=

# Circle
CIRCLE_API_KEY=
CIRCLE_ENTITY_SECRET=
CIRCLE_BLOCKCHAIN=ARC-TESTNET
CIRCLE_USDC_TOKEN_ID=

# Misc
ADMIN_EMAIL=admin@admin.com

Variable	Scope	Purpose
NEXT_PUBLIC_SUPABASE_URL	Public	Supabase project URL.
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_OR_ANON_KEY	Public	Supabase anonymous/public key.
SUPABASE_SECRET_KEY	Server-side	Secret key for privileged writes (e.g., transaction inserts).
CIRCLE_API_KEY	Server-side	Used to fetch Circle webhook public keys for signature verification.
CIRCLE_ENTITY_SECRET	Server-side	Circle entity secret for wallet operations.
CIRCLE_BLOCKCHAIN	Server-side	Blockchain network identifier (e.g., "ARC-TESTNET").
CIRCLE_USDC_TOKEN_ID	Server-side	USDC token ID for the specified blockchain. Pre-filled for ARC-TESTNET.
ADMIN_EMAIL	Server-side	Admin user email address.

User Accounts

Admin Account

On first startup, an admin user is automatically created with the following credentials:

• Email: admin@admin.com
• Password: 123456

The admin account has access to the Admin Dashboard, which provides an overview of all users, wallets, and transactions in the system.

Regular users who sign up will see the User Dashboard, which allows them to purchase credits with USDC and view their own transaction history.

Signup Rate Limits

Supabase limits email signups to 2 per hour by default (unless custom SMTP is configured). If you hit an "email rate limit exceeded" error during testing:

• Local Supabase (Docker): Email verification is handled by the built-in Inbucket mail server — check it to confirm signups. The rate limit can be adjusted in supabase/config.toml under [auth.rate_limit].
• Remote Supabase (Cloud): Use real email addresses (disposable emails may fail verification). If you hit the limit, you can manually add users via the Supabase dashboard under Authentication → Users.