Tutorials

Step-by-step guides for building on r1x. From basic setup to advanced integrations.

Setting Up Your First x402 Service

Learn how to create and deploy an x402-protected service using PayAI facilitator.

Steps

1
Configure your Express server with PayAI middleware
2
Define protected routes with pricing
3
Set up merchant wallet and CDP API keys
4
Test payment flow end-to-end

Integrating PayAI Services

Sync and use services from PayAI facilitator in your application.

Steps

1
Call the PayAI sync endpoint
2
Query services from database
3
Handle payment quotes and verification
4
Display services in marketplace UI

Building a Payment Flow

Implement a complete payment flow with wallet integration and verification.

Steps

1
Connect user wallet to Base network
2
Request payment quote from server
3
Approve and sign transaction
4
Verify payment via PayAI facilitator
5
Grant access to paid resource

Creating Marketplace Listings

Add your services to the r1x marketplace for discovery.

Steps

1
Ensure service is synced from PayAI
2
Verify service metadata is complete
3
Set appropriate pricing
4
Test marketplace discovery

Express Server Setup

Configure your Express server with PayAI middleware:

Express Server

import express from 'express';
import { paymentMiddleware } from 'x402-express';

const app = express();
const payTo = process.env.MERCHANT_ADDRESS!;
const facilitatorUrl = process.env.FACILITATOR_URL || 'https://facilitator.payai.network';

// Apply PayAI middleware
app.use(paymentMiddleware(
  payTo,
  {
    'POST /api/r1x-agent/chat': {
      price: '$0.25',
      network: 'base',
    },
    'POST /api/x402/pay': {
      price: '$0.01',
      network: 'base',
    },
  },
  {
    url: facilitatorUrl,
  },
));

// Your routes here
app.post('/api/r1x-agent/chat', async (req, res) => {
  // Payment already verified by middleware
  // Handle your logic here
  res.json({ message: 'Success' });
});

app.listen(3001);

PayAI Middleware

The paymentMiddleware from x402-express automatically handles HTTP 402 responses, payment verification via PayAI facilitator, and CDP API authentication for Base mainnet.

Client-Side Payment Flow

Implement payment flow in your React application:

Payment Flow

import { connectWallet, transferUSDC } from '@/lib/wallet';

async function handlePayment(amount: string, merchantAddress: string) {
  // 1. Connect wallet
  const wallet = await connectWallet();
  
  // 2. Request quote from server
  const quoteResponse = await fetch('/api/x402/pay', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ serviceId: 'my-service', amount }),
  });
  
  if (quoteResponse.status === 402) {
    const { payment } = await quoteResponse.json();
    
    // 3. Transfer USDC
    const txHash = await transferUSDC(
      wallet,
      merchantAddress,
      payment.amountRaw
    );
    
    // 4. Retry with payment proof
    const proof = {
      transactionHash: txHash,
      from: wallet.address,
      to: merchantAddress,
      amount: payment.amountRaw,
      token: payment.token,
    };
    
    const successResponse = await fetch('/api/x402/pay', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-PAYMENT': JSON.stringify(proof),
      },
      body: JSON.stringify({ serviceId: 'my-service', proof }),
    });
    
    return await successResponse.json();
  }
}

Next Steps

Ready to dive deeper? Check out the API Reference for complete endpoint documentation, or explore Utilities for available helper functions.