ArcPay

Instant stablecoin payment rails for agentic commerce on Arc.

ArcPay is a production-hardened operational dashboard and developer API for managing native USDC payments on the Arc Network — the Circle-backed chain with sub-second deterministic finality. It is purpose-built for AI agents, backend microservices, and operational teams that need transparent, conditional, and auditable on-chain transactions.

Why Arc? — USDC is the native gas token. A single asset covers both transaction fees and payment amounts, eliminating volatile gas cost surprises and making micro-payments viable for autonomous agents.

Problem & Solution

Autonomous AI agents and automated workflows frequently need to perform on-chain payments — paying for APIs, purchasing data, or settling recurring costs. Doing this by embedding private keys directly into bots is insecure and lacks auditability.

ArcPay solves this by acting as an orchestration and auditing hub:

Step	What happens
1. Intent	The agent creates a payment intent via the REST API
2. Signing	An operator or agent connects an EVM wallet and signs the queued payment on Arc
3. Settlement	ArcPay settles the transaction and records the `tx_hash` on-chain
4. Webhook	A cryptographically signed webhook is pushed to external services in real-time
5. Audit	Every action is logged to an immutable audit trail

Key Features

Feature	Description
🔐 Passwordless Dashboard	Instant operator access — no email/password required
📝 Payment Intents	Compose intents with custom amounts, recipients, and JSON condition rules
💼 Wallet Integration	Connect MetaMask, Rabby, or Coinbase Wallet; switch networks dynamically
🤖 Agent Management	Register, activate, and throttle agent wallets
🔑 Scoped API Keys	Peppered SHA-256 hashed keys with granular permission scopes
🔔 Webhook Worker	Reliable delivery queue with HMAC-SHA256 signatures and exponential backoff retries
📜 Audit Trail	Immutable ledger recording every operational action
⛓️ Contract Deployer	Foundry integration for deploying `PaymentEscrow`, `ProgrammablePayment`, and `SubscriptionManager`
🛡️ Production Hardened	Rate limiting, SSRF-filtered webhooks, security headers, and Supabase RLS policies

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     ArcPay Platform                         │
├──────────────────┬──────────────────────────────────────────┤
│   Dashboard UI   │  Next.js 15 · React 19 · Tailwind CSS   │
│   (Frontend)     │  Metrics, Intents, Agents, Webhooks,     │
│                  │  API Keys, Contracts                     │
├──────────────────┼──────────────────────────────────────────┤
│   Serverless API │  Next.js API Routes (App Router)         │
│   (Backend)      │  RESTful endpoints with auth middleware  │
├──────────────────┼──────────────────────────────────────────┤
│   Data Layer     │  Supabase (PostgreSQL + RLS)             │
│                  │  Migrations · Audit logs · Rate limits   │
├──────────────────┼──────────────────────────────────────────┤
│   Blockchain     │  Arc Testnet / Mainnet                   │
│                  │  Solidity ^0.8.20 · Foundry · EVM wallet │
├──────────────────┼──────────────────────────────────────────┤
│   Integrations   │  Agent SDKs (TS/Python) · MCP Server     │
│                  │  HMAC Webhooks · llms.txt                │
└──────────────────┴──────────────────────────────────────────┘

Tech Stack

Layer	Technology	Purpose
Frontend	Next.js 15, React 19, Tailwind CSS	App Router with server components
Backend	Next.js API Routes	Serverless REST API with auth middleware
Database	Supabase (PostgreSQL)	Row Level Security, audit logging, rate limits
Blockchain	Solidity ^0.8.20, Foundry	Smart contract development and deployment
Web3	EVM browser providers	Wallet connection and transaction signing
Agent SDKs	TypeScript, Python	First-party integration packages

Getting Started

Prerequisites

Requirement	Minimum Version
Node.js	v18.x or newer
npm	v9.x or newer
Supabase	Dedicated project instance
Foundry	Latest (for smart contract deployment)
EVM Wallet	MetaMask, Rabby, or Coinbase Wallet

Quick Start

# 1. Clone the repository
git clone https://github.com/your-org/arcpay.git
cd arcpay

# 2. Install dependencies
npm install

# 3. Configure environment
cp .env.example .env.local
# Edit .env.local with your credentials (see below)

# 4. Apply database migrations (in Supabase SQL Editor)
# Run migration files in order (see Database Setup)

# 5. Start development server
npm run dev

The dashboard opens at http://localhost:3000 — no login required (passwordless operator session).

Environment Variables

Create a .env.local file in the project root:

# ── Supabase ──────────────────────────────────────────────
NEXT_PUBLIC_SUPABASE_URL=        # Your Supabase project URL
NEXT_PUBLIC_SUPABASE_ANON_KEY=   # Supabase anonymous key
SUPABASE_SERVICE_ROLE_KEY=       # Supabase service role key (server-side only)

# ── Security ──────────────────────────────────────────────
WEBHOOK_WORKER_SECRET=           # Secret for authenticating webhook worker
API_KEY_PEPPER=                  # Pepper for API key hashing (SHA-256)

# ── Arc Network ───────────────────────────────────────────
ARC_TESTNET_RPC_URL=https://rpc.testnet.arc.network
ARC_MAINNET_RPC_URL=             # Mainnet RPC endpoint
PRIVATE_KEY=                     # Deployer private key (contract deployment only)

⚠️ Security: Never commit .env.local or expose PRIVATE_KEY, SUPABASE_SERVICE_ROLE_KEY, or API_KEY_PEPPER in client-side code, logs, or screenshots.

Database Setup

Apply the SQL migration scripts in order via the Supabase SQL Editor:

Order	Migration File	Purpose
1	`supabase/migrations/0001_initial.sql`	Core tables: agents, payment_intents, webhooks
2	`supabase/migrations/0002_production_hardening.sql`	RLS policies, audit logs, security constraints
3	`supabase/migrations/0003_rate_limit_function.sql`	Rate limiting database function

Smart Contracts

ArcPay includes three Solidity contracts deployable to Arc via Foundry:

Contract	Purpose
`PaymentEscrow.sol`	Conditional fund holding with payer/payee release logic
`ProgrammablePayment.sol`	Core agent-triggered payment primitives
`SubscriptionManager.sol`	Recurring subscription payment management

Deploy to Testnet

$env:PRIVATE_KEY="0x..."
npm run contracts:deploy:testnet

Deploy to Mainnet

$env:PRIVATE_KEY="0x..."
npm run contracts:deploy:mainnet

API Reference

All API endpoints require authentication via Bearer token:

Authorization: Bearer <API_KEY>

Core Endpoints

Method	Endpoint	Description
`POST`	`/api/payment-intents`	Create a new payment intent
`GET`	`/api/payment-intents`	List all payment intents
`PATCH`	`/api/payment-intents`	Update intent status / settle
`POST`	`/api/agents`	Register a new agent wallet
`GET`	`/api/agents`	List registered agents
`POST`	`/api/webhooks`	Create a webhook endpoint
`GET`	`/api/webhooks`	List webhook configurations
`POST`	`/api/keys`	Generate a scoped API key
`GET`	`/api/keys`	List API keys
`GET`	`/api/health`	System and database health check

Example: Create a Payment Intent

curl -X POST http://localhost:3000/api/payment-intents \
  -H "Authorization: Bearer ak_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 0.10,
    "token": "USDC",
    "recipient": "0x4C8A5d7F93d2a9e6f770D5F8f532D6a5E792a9",
    "condition": {
      "description": "Pay after delivery confirmation"
    }
  }'

Example: Register a Webhook

curl -X POST http://localhost:3000/api/webhooks \
  -H "Authorization: Bearer ak_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/arcpay-webhook",
    "event_type": "payment_intent.settled"
  }'

📖 Full API documentation: docs/ or the live GitBook

Agent SDKs

First-party SDKs are available for integrating ArcPay into your agent or backend service:

Language	Path	Status
TypeScript	`agent-sdk/typescript/`	Available
Python	`agent-sdk/python/`	Available

TypeScript Quick Start

import { ArcPayClient } from '@arcpay/sdk';

const client = new ArcPayClient({
  baseUrl: 'https://your-arcpay-domain.com',
  apiKey: 'ak_live_xxx',
});

// Create a payment intent
const intent = await client.createPaymentIntent({
  amount: 0.50,
  token: 'USDC',
  recipient: '0x...',
  condition: { description: 'Data delivery complete' },
});

MCP Server

ArcPay ships with a local Model Context Protocol server, enabling AI agents and LLM tools to interact with ArcPay natively:

npm run mcp

Required environment variables:

ARCPAY_BASE_URL=http://localhost:3000
ARCPAY_API_KEY=ak_test_xxx

Project Structure

arcpay/
├── app/                          # Next.js 15 App Router
│   ├── api/                      # RESTful API endpoints
│   │   ├── payment-intents/      # Payment intent CRUD & settlement
│   │   ├── agents/               # Agent registration & management
│   │   ├── webhooks/             # Webhook config, delivery & workers
│   │   ├── keys/                 # Scoped API key generation
│   │   ├── contracts/            # Contract deployment records
│   │   ├── health/               # System health check
│   │   └── seed/                 # Database seeding
│   ├── intents/                  # Payment intents dashboard
│   ├── agents/                   # Agent management dashboard
│   ├── webhooks/                 # Webhook configuration dashboard
│   ├── keys/                     # API keys dashboard
│   ├── contracts/                # Contract deployment dashboard
│   └── page.tsx                  # Main overview & metrics dashboard
├── components/                   # Shared React components
├── lib/                          # Core utility modules
│   ├── api-auth.ts               # API key validation & scoping
│   ├── audit.ts                  # Immutable audit trail logger
│   ├── security.ts               # Rate limiting & SSRF protection
│   ├── webhook-delivery.ts       # HMAC signature & retry handler
│   └── arc/                      # Arc network & wallet integration
├── contracts/                    # Solidity smart contracts
│   ├── PaymentEscrow.sol
│   ├── ProgrammablePayment.sol
│   └── SubscriptionManager.sol
├── script/                       # Foundry deployment scripts
├── agent-sdk/                    # TypeScript & Python SDKs
│   ├── typescript/
│   └── python/
├── mcp-server/                   # MCP server for AI agent integration
├── supabase/                     # Database migrations & schemas
├── docs/                         # Documentation source (GitBook-ready)
├── middleware.ts                  # Next.js middleware (security headers)
├── llms.txt                      # LLM integration instructions
└── foundry.toml                  # Foundry configuration

Documentation

Resource	Description
📖 Live Docs (GitBook)	Full user and developer documentation
📁 `docs/`	Source markdown files (GitBook-synced)
🧪 `guild.md`	Interactive demo & QA testing guide
🤖 `llms.txt`	Concise instructions for AI agents
📋 `project.md`	Detailed project directory overview

Security

ArcPay is designed with production-grade security throughout:

API Key Hashing — Peppered SHA-256 with scoped permissions (intents:create, webhooks:write, etc.)
Webhook Signatures — Every outbound webhook is signed with HMAC-SHA256 for verification
Rate Limiting — Database-level rate limiting to prevent API abuse
SSRF Protection — Webhook URLs are validated against SSRF attack patterns
Row Level Security — Supabase RLS policies enforce data access boundaries
Security Headers — Next.js middleware applies strict security headers on all responses
Audit Logging — Immutable records of all operational actions for compliance and forensics

Verification

Run the full verification suite before deploying:

# Lint check (zero warnings enforced)
npm run lint

# Type checking
npm run typecheck

# Production build
npm run build

Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/your-feature)
Commit your changes (git commit -m 'feat: add your feature')
Push to your branch (git push origin feature/your-feature)
Open a Pull Request

License

This project is licensed under the MIT License.

_{Built for the agentic economy on Arc Network · Powered by native USDC}

Navigation Menu

Repository files navigation

ArcPay

Table of Contents

Problem & Solution

Key Features

Architecture

Tech Stack

Getting Started

Prerequisites

Quick Start

Environment Variables

Database Setup

Smart Contracts

Deploy to Testnet

Deploy to Mainnet

API Reference

Core Endpoints

Example: Create a Payment Intent

Example: Register a Webhook

Agent SDKs

TypeScript Quick Start

MCP Server

Project Structure

Documentation

Security

Verification

Contributing

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
agent-sdk		agent-sdk
app		app
components		components
contracts		contracts
docs		docs
lib		lib
mcp-server		mcp-server
script		script
scripts		scripts
supabase/migrations		supabase/migrations
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
archpay_hermes.md		archpay_hermes.md
eslint.config.mjs		eslint.config.mjs
foundry.toml		foundry.toml
guild.md		guild.md
llms.txt		llms.txt
middleware.ts		middleware.ts
next-env.d.ts		next-env.d.ts
next.config.mjs		next.config.mjs
package.json		package.json
postcss.config.mjs		postcss.config.mjs
project.md		project.md
script.md		script.md
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

ArcPay

Table of Contents

Problem & Solution

Key Features

Architecture

Tech Stack

Getting Started

Prerequisites

Quick Start

Environment Variables

Database Setup

Smart Contracts

Deploy to Testnet

Deploy to Mainnet

API Reference

Core Endpoints

Example: Create a Payment Intent

Example: Register a Webhook

Agent SDKs

TypeScript Quick Start

MCP Server

Project Structure

Documentation

Security

Verification

Contributing

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages