Getting Started

Welcome to 402x: the platform that makes micropayments as simple as sending a message.

What You'll Learn

This guide will help you:

Understand what 402x is and how it works
Choose the right product for your use case
Get your first payment integration running in minutes
Explore advanced features and capabilities

What is 402x?

402x enables instant, trustless micropayments across the internet. Built on the x402 Protocol, it allows creators, developers, researchers, and communities to monetize their work without subscriptions, accounts, or complex payment infrastructure.

Key Benefits

✅ Instant Settlement: Get paid in seconds, not days
✅ No Accounts Required: Users pay without signing up
✅ Micropayment Optimized: Accept payments as low as $0.01
✅ Low Fees: 1-2% protocol fee, no monthly costs
✅ Global by Default: No geographic restrictions
✅ Developer Friendly: Simple APIs and SDKs

Quick Start by Use Case

Choose your path based on what you want to build:

💰 I want to monetize content

Use: 402x Paywalls

Perfect for: Blogs, articles, videos, premium content

html

<!-- Add to your HTML -->
<script src="https://402x.io/paywall.js" 
        data-price="0.10"
        data-content-id="article-123"></script>

Time to first payment: 5 minutes
Coding required: Minimal (copy/paste)

🔌 I want to monetize my API

Use: 402x APIs

Perfect for: SaaS APIs, AI models, data services, web services

javascript

// Express.js example
import { x402Middleware } from '@402x/express';

app.use('/api', x402Middleware({
  pricing: {
    '/search': 0.01,      // $0.01 per search
    '/ai/generate': 0.10   // $0.10 per generation
  }
}));

Time to first payment: 15 minutes
Coding required: Moderate (SDK integration)

🤖 I want to create a task marketplace

Use: 402x Tasks

Perfect for: AI agents, freelance tasks, bounties, microtasks

javascript

// Post a task
const task = await x402.tasks.create({
  title: 'Summarize this article',
  description: 'Create a 100-word summary',
  payment: 2.00,
  deadline: Date.now() + (24 * 60 * 60 * 1000) // 24 hours
});

Time to first payment: 20 minutes
Coding required: Moderate (API calls)

👥 I want to monetize my community

Use: 402x Communities

Perfect for: Discord servers, Telegram groups, Slack communities

bash

# Discord bot command
!402x setup --entry-fee 5.00 --channels premium,alpha

Time to first payment: 10 minutes
Coding required: None (bot commands)

📚 I want to publish research papers

Use: 402x Research

Perfect for: Academic papers, research reports, white papers

Visit research.402x.io
Upload your PDF
Set price ($1-10 recommended)
Publish instantly

Time to first payment: 5 minutes
Coding required: None (web interface)

🎨 I want a simple payment button

Use: 402x Widgets

Perfect for: Digital downloads, tips, one-time purchases

html

<!-- Donation button -->
<script src="https://402x.io/widget.js"
        data-type="button"
        data-price="5.00"
        data-label="Support My Work"></script>

Time to first payment: 2 minutes
Coding required: None (copy/paste)

5-Minute Quickstart

Let's get your first payment integration running:

Step 1: Create an Account

Visit dashboard.402x.io and sign up with your email.

You'll instantly receive:

API key for development
Sandbox environment with test funds
Access to dashboard and analytics

Step 2: Choose Your Integration Method

Pick the simplest option for your needs:

No-Code Options:

Widget Builder (payment buttons, donation forms)
Community Bots (Discord, Telegram, Slack)
Research Platform (paper publishing)

Low-Code Options:

Paywall Scripts (content monetization)
WordPress Plugin
Pre-built integrations

Developer Options:

REST API
JavaScript/TypeScript SDK
Python SDK
Custom integration

Step 3: Test in Sandbox

Use the sandbox environment to test without real money:

javascript

import X402 from '@402x/sdk';

const x402 = new X402({
  apiKey: process.env.X402_SANDBOX_KEY,
  environment: 'sandbox' // Use test funds
});

// Create a test payment
const payment = await x402.payments.create({
  amount: 1.00,
  description: 'Test payment',
  returnUrl: 'https://myapp.com/success'
});

console.log('Payment URL:', payment.url);

Sandbox features:

Test USDC tokens (unlimited)
Test wallets pre-configured
Full API access
Webhook testing with ngrok

Step 4: Go Live

When ready for production:

Get Production API Key
- Dashboard → API Keys → Create Production Key

Update Your Code

javascript

const x402 = new X402({
  apiKey: process.env.X402_PRODUCTION_KEY,
  environment: 'production'
});

Configure Webhooks
- Set your production webhook URL
- Verify signature validation
- Handle payment events
Launch! 🚀

Understanding the Basics

How Payments Work

User requests paid content/service
402x generates payment request (HTTP 402)
User approves payment (via wallet or card)
Payment settles on Base L2 (~2 seconds)
Content/service unlocks (via webhook)
You receive funds (instantly in wallet)

Payment Flow Diagram

User Request → 402x Gateway → Payment Required (402)
                    ↓
             User Pays (USDC)
                    ↓
          Base L2 Confirmation (~2s)
                    ↓
        Webhook → Your Server → Unlock Content
                    ↓
              Funds in Wallet

Key Concepts

What is the x402 Protocol?

The x402 Protocol is the underlying infrastructure that powers all 402x products. It's an implementation of HTTP 402 (Payment Required) that enables instant, trustless micropayments. Think of it as the protocol layer, while 402x products are the application layer.

Learn more: Protocol Overview

What is Base L2?

Base is an Ethereum Layer 2 blockchain optimized for low-cost, fast transactions. 402x uses Base for payment settlement, which means:

~2 second confirmation times
~$0.001 transaction fees
Full Ethereum security
USDC stablecoin support

You don't need to understand blockchain to use 402x - it's all handled automatically.

What currencies are supported?

Primary: USDC (USD Coin stablecoin)

Coming Soon:

ETH (Ethereum)
Fiat on-ramps (credit card → USDC conversion)
Multi-chain support (Optimism, Arbitrum)

Q: Do my users need crypto wallets?

Most users won't notice - they can pay with cards and 402x handles the crypto conversion.

How do I get paid?

Payments arrive instantly in your configured wallet address. You can:

Withdraw to your bank account
Keep funds in crypto
Reinvest in other 402x services
No minimum payout amount
No withdrawal delays

Installation & Setup

JavaScript/TypeScript

bash

npm install @402x/sdk

javascript

import X402 from '@402x/sdk';

const x402 = new X402({
  apiKey: process.env.X402_API_KEY
});

// Create a payment
const payment = await x402.payments.create({
  amount: 1.00,
  description: 'Premium article access'
});

Python

bash

pip install x402

python

from x402 import X402Client

client = X402Client(api_key=os.environ['X402_API_KEY'])

# Create a payment
payment = client.payments.create(
    amount=1.00,
    description='Premium article access'
)

REST API

bash

curl -X POST https://api.402x.io/v1/payments \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1.00,
    "description": "Premium article access"
  }'

Common Integration Patterns

Pattern 1: Content Paywall

javascript

// 1. Check if user has paid
const hasPaid = await x402.payments.verify({
  contentId: 'article-123',
  userId: req.session.userId
});

if (!hasPaid) {
  // 2. Create payment request
  const payment = await x402.payments.create({
    amount: 0.50,
    metadata: { contentId: 'article-123' }
  });
  
  // 3. Return payment URL
  return res.json({ paymentUrl: payment.url });
}

// 4. Serve content
return res.json({ content: article.fullContent });

Pattern 2: API Metering

javascript

// Middleware for pay-per-use API
app.use('/api', async (req, res, next) => {
  const price = getPriceForEndpoint(req.path);
  
  try {
    // Charge for API call
    await x402.payments.charge({
      amount: price,
      userId: req.headers['x-user-id'],
      description: `API call: ${req.path}`
    });
    
    next(); // Continue to API handler
  } catch (error) {
    res.status(402).json({
      error: 'Payment required',
      price: price,
      paymentUrl: error.paymentUrl
    });
  }
});

Pattern 3: Webhook Handler

javascript

app.post('/webhooks/402x', async (req, res) => {
  // 1. Verify webhook signature
  const isValid = x402.webhooks.verify(
    req.body,
    req.headers['x-402-signature'],
    webhookSecret
  );
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // 2. Handle event
  const event = req.body;
  
  if (event.type === 'payment.confirmed') {
    // Unlock content
    await unlockContent(event.data.metadata.contentId);
  }
  
  // 3. Acknowledge receipt
  res.sendStatus(200);
});

Next Steps

Learn More

📖 Protocol Architecture: Deep dive into how it works
🔒 Security Model: Understanding payment security
🛠️ Testing Guide: Comprehensive testing strategies

Explore Use Cases

Paywalls: Content monetization
APIs: API monetization
Tasks: Task marketplace
Communities: Community economics
Research: Academic publishing
Widgets: No-code payments

Get Help

💬 Discord Community: Ask questions, share ideas
📧 Email Support: Technical support
📚 FAQ: Common questions answered
🐛 Troubleshooting: Fix common issues

Ready to Build?

Start with the simplest integration for your use case. You can always add complexity later.

Recommended First Steps:

Sign up at dashboard.402x.io
Get your sandbox API key
Try a 5-minute integration
Join Discord to connect with other builders

Getting Started ​

What is 402x? ​

Key Benefits ​

Quick Start by Use Case ​

💰 I want to monetize content ​

🔌 I want to monetize my API ​

🤖 I want to create a task marketplace ​

👥 I want to monetize my community ​

📚 I want to publish research papers ​

🎨 I want a simple payment button ​

5-Minute Quickstart ​

Step 1: Create an Account ​

Step 2: Choose Your Integration Method ​

Step 3: Test in Sandbox ​

Step 4: Go Live ​

Understanding the Basics ​

How Payments Work ​

Payment Flow Diagram ​

Key Concepts ​

Installation & Setup ​

JavaScript/TypeScript ​

Python ​

REST API ​

Common Integration Patterns ​

Pattern 1: Content Paywall ​

Pattern 2: API Metering ​

Pattern 3: Webhook Handler ​

Next Steps ​

Learn More ​

Explore Use Cases ​

Get Help ​

Getting Started

What is 402x?

Key Benefits

Quick Start by Use Case

💰 I want to monetize content

🔌 I want to monetize my API

🤖 I want to create a task marketplace

👥 I want to monetize my community

📚 I want to publish research papers

🎨 I want a simple payment button

5-Minute Quickstart

Step 1: Create an Account

Step 2: Choose Your Integration Method

Step 3: Test in Sandbox

Step 4: Go Live

Understanding the Basics

How Payments Work

Payment Flow Diagram

Key Concepts

Installation & Setup

JavaScript/TypeScript

Python

REST API

Common Integration Patterns

Pattern 1: Content Paywall

Pattern 2: API Metering

Pattern 3: Webhook Handler

Next Steps

Learn More

Explore Use Cases

Get Help