​
Overview

This quickstart guide will get you up and running with Meridian’s x402 payment system and receiver wallet features.

​
Prerequisites

  • Node.js 20+
  • PNPM 9+
  • Ethereum wallet (MetaMask recommended)
  • Base Sepolia testnet ETH and USDC

​
Installation

1

Clone the repository

git clone https://github.com/meridian-protocol/meridian-protocol
cd meridian-protocol
2

Install dependencies

bash pnpm install
3

Set up environment variables

Create .env.local files in the apps you want to run:Frontend (.env.local):
NEXT_PUBLIC_REOWN_PROJECT_ID=your_reown_project_id
NEXT_PUBLIC_X402_FACILITATOR_URL=http://localhost:4021
Facilitator (.env.local):
DATABASE_URL=your_database_url
JWT_SECRET=your_jwt_secret
4

Start development servers

# Start all applications
pnpm dev

# Or start specific apps
pnpm dev --filter=@meridian/frontend
pnpm dev --filter=@meridian/facilitator

​
Make your first payment

1

Connect your wallet

Navigate to the demo app at http://localhost:3000 and connect your Ethereum wallet.
2

Sign in with Ethereum

Use SIWE (Sign-In with Ethereum) to authenticate your session.
3

Make a payment

Use the payment interface to make your first x402 payment:
import { useX402Payment } from '@/hooks/use-x402-payment'

const { signAndVerifyPayment } = useX402Payment()

const payment = await signAndVerifyPayment({
  amount: "1.00",
  recipient: "0x...",
  network: "base-sepolia",
  description: "Test payment"
})

​
Key Concepts

​
x402 Protocol

  • Authorization-based payments: No token approvals needed
  • Fee structure: 1% fee to treasury, remainder to recipient
  • Multi-network support: Base, Arbitrum, Optimism, and testnets

​
Enhanced Security

  • Organization management: Users belong to organizations with shared infrastructure
  • API key authentication: Secure, organization-scoped access control
  • Multi-user teams: Collaborative payment management without wallet sharing

​
Authentication

  • SIWE integration: Sign-In with Ethereum for secure sessions
  • Session management: Persistent sessions across page reloads
  • API key support: For server-to-server integrations

​
Next Steps

Explore Demo Apps

See working examples of Meridian integration

Learn x402

Deep dive into the Meridian x402 smart contracts

API Reference

Complete API documentation