x402 SDK Tutorial:
Build a Paid API Endpoint
in 15 Minutes

mkdir my-paid-api && cd my-paid-api && npm init -y

npm i hono @proxies-sx/x402-core @proxies-sx/x402-hono @proxies-sx/x402-solana

// src/index.ts
import { Hono } from 'hono'
import { cors } from 'hono/cors'
import { logger } from 'hono/logger'
import { serve } from '@hono/node-server'

import {
  type PaymentRequirement,
  createPaymentRequirement,
  validatePaymentSignature,
} from '@proxies-sx/x402-core'

import { x402Middleware } from '@proxies-sx/x402-hono'
import { verifySolanaPayment } from '@proxies-sx/x402-solana'

// ─── Configuration ───────────────────────────────────────────────
// Your Solana wallet that receives USDC payments
const SOLANA_RECIPIENT = '6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv'

// Your Base (Ethereum L2) wallet (optional, for multi-network)
const BASE_RECIPIENT = '0xF8cD900794245fc36CBE65be9afc23CDF5103042'

// USDC token addresses
const SOLANA_USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
const BASE_USDC = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'

// Proxies.sx credentials (from client.proxies.sx dashboard)
const PROXY_HOST = process.env.PROXY_HOST || 'us.proxies.sx'
const PROXY_PORT = parseInt(process.env.PROXY_PORT || '5057')
const PROXY_USER = process.env.PROXY_USER || 'your_username'
const PROXY_PASS = process.env.PROXY_PASS || 'your_password'

// ─── Hono App ────────────────────────────────────────────────────
const app = new Hono()

// Global middleware
app.use('*', cors())
app.use('*', logger())

// ─── Health Check (free, no payment required) ────────────────────
app.get('/', (c) => {
  return c.json({
    service: 'my-paid-api',
    version: '1.0.0',
    protocol: 'x402',
    endpoints: {
      '/api/scrape': {
        method: 'POST',
        price: '$0.05 per request',
        payment: 'USDC on Solana or Base',
        description: 'Scrape any URL through a real 4G/5G mobile proxy',
      },
      '/api/bulk-scrape': {
        method: 'POST',
        price: '$0.20 per request (up to 10 URLs)',
        payment: 'USDC on Solana or Base',
        description: 'Batch scrape multiple URLs',
      },
    },
    docs: 'https://agents.proxies.sx/marketplace/',
  })
})

// ─── x402 Middleware for /api/* routes ────────────────────────────
//
// x402Middleware() configuration:
//
//   price: number
//     Amount in micro-units. 1 micro-unit = $0.000001.
//     50000 = $0.05, 200000 = $0.20, 5000000 = $5.00
//
//   recipient: string
//     Your wallet address that receives payment.
//
//   networks: string[]
//     Which blockchains to accept. Options: 'solana', 'base'.
//     The agent picks which one to use based on its funding.
//
//   description: string
//     Human-readable description shown in the 402 response body.
//
//   verify: (paymentHeader: string, requirement: PaymentRequirement) => Promise<boolean>
//     Your custom verification function. Called when the client
//     retries with an X-PAYMENT header. Must return true if the
//     on-chain payment is valid.
//
//   resource: string (optional)
//     Identifies the resource being purchased. Included in the
//     PaymentRequirement for the agent's reference.

// ─── Single Scrape Endpoint ($0.05/request) ──────────────────────
app.use(
  '/api/scrape',
  x402Middleware({
    price: 50000, // $0.05 in micro-units (50000 * $0.000001)
    recipient: SOLANA_RECIPIENT,
    networks: ['solana', 'base'],
    description: 'Scrape a URL through a real 4G/5G mobile proxy',
    resource: '/api/scrape',
    verify: async (paymentHeader: string, requirement: PaymentRequirement) => {
      // Step 1: Validate the cryptographic signature on the header
      const signatureValid = validatePaymentSignature(paymentHeader)
      if (!signatureValid) return false

      // Step 2: Verify the on-chain payment
      // Parse the payment header to get the transaction signature
      const payment = JSON.parse(
        Buffer.from(paymentHeader, 'base64').toString()
      )

      if (payment.network === 'solana') {
        const result = await verifySolanaPayment({
          txSignature: payment.txSignature,
          expectedRecipient: SOLANA_RECIPIENT,
          expectedAmount: requirement.price,
          usdcMint: SOLANA_USDC,
        })
        return result.verified
      }

      // For Base verification, use @proxies-sx/x402-base
      // (similar pattern, checks ERC20 Transfer event)
      return false
    },
  })
)

// ─── Bulk Scrape Endpoint ($0.20/request, up to 10 URLs) ─────────
app.use(
  '/api/bulk-scrape',
  x402Middleware({
    price: 200000, // $0.20 in micro-units
    recipient: SOLANA_RECIPIENT,
    networks: ['solana'],
    description: 'Batch scrape up to 10 URLs through mobile proxies',
    resource: '/api/bulk-scrape',
    verify: async (paymentHeader: string, requirement: PaymentRequirement) => {
      const signatureValid = validatePaymentSignature(paymentHeader)
      if (!signatureValid) return false

      const payment = JSON.parse(
        Buffer.from(paymentHeader, 'base64').toString()
      )

      const result = await verifySolanaPayment({
        txSignature: payment.txSignature,
        expectedRecipient: SOLANA_RECIPIENT,
        expectedAmount: requirement.price,
        usdcMint: SOLANA_USDC,
      })
      return result.verified
    },
  })
)

// ─── Route Handlers ──────────────────────────────────────────────

// POST /api/scrape — single URL scrape
app.post('/api/scrape', async (c) => {
  const body = await c.req.json<{ url: string; headers?: Record<string, string> }>()

  if (!body.url) {
    return c.json({ error: 'missing_url', message: 'Provide a "url" field' }, 400)
  }

  try {
    // Build proxy URL for fetch (SOCKS5 via Proxies.sx)
    const proxyUrl = `http://${PROXY_USER}:${PROXY_PASS}@${PROXY_HOST}:${PROXY_PORT}`

    // Fetch through mobile proxy
    const response = await fetch(body.url, {
      headers: {
        'User-Agent':
          'Mozilla/5.0 (iPhone; CPU iPhone OS 17_4 like Mac OS X) AppleWebKit/605.1.15',
        ...body.headers,
      },
      // @ts-ignore — proxy support varies by runtime
      proxy: proxyUrl,
    })

    const html = await response.text()

    return c.json({
      success: true,
      url: body.url,
      status: response.status,
      content_length: html.length,
      content: html,
      proxy: {
        provider: 'proxies.sx',
        type: '4G/5G mobile',
        country: 'US',
      },
      payment: {
        protocol: 'x402',
        amount: '$0.05',
        currency: 'USDC',
      },
    })
  } catch (err) {
    return c.json(
      {
        error: 'scrape_failed',
        message: err instanceof Error ? err.message : 'Unknown error',
      },
      500
    )
  }
})

// POST /api/bulk-scrape — up to 10 URLs
app.post('/api/bulk-scrape', async (c) => {
  const body = await c.req.json<{ urls: string[] }>()

  if (!body.urls || !Array.isArray(body.urls)) {
    return c.json({ error: 'missing_urls', message: 'Provide a "urls" array' }, 400)
  }

  if (body.urls.length > 10) {
    return c.json({ error: 'too_many_urls', message: 'Maximum 10 URLs per request' }, 400)
  }

  const proxyUrl = `http://${PROXY_USER}:${PROXY_PASS}@${PROXY_HOST}:${PROXY_PORT}`

  const results = await Promise.allSettled(
    body.urls.map(async (url) => {
      const response = await fetch(url, {
        headers: {
          'User-Agent':
            'Mozilla/5.0 (iPhone; CPU iPhone OS 17_4 like Mac OS X) AppleWebKit/605.1.15',
        },
        // @ts-ignore
        proxy: proxyUrl,
      })
      const html = await response.text()
      return { url, status: response.status, content_length: html.length, content: html }
    })
  )

  return c.json({
    success: true,
    total: body.urls.length,
    results: results.map((r, i) =>
      r.status === 'fulfilled'
        ? r.value
        : { url: body.urls[i], error: (r.reason as Error).message }
    ),
    payment: { protocol: 'x402', amount: '$0.20', currency: 'USDC' },
  })
})

// ─── Start Server ────────────────────────────────────────────────
const port = parseInt(process.env.PORT || '3000')

serve({ fetch: app.fetch, port }, (info) => {
  console.log(`
  ┌─────────────────────────────────────────────┐
  │  x402 Paid API running on port ${info.port}        │
  │                                             │
  │  Free:  GET  /                              │
  │  Paid:  POST /api/scrape       ($0.05)      │
  │  Paid:  POST /api/bulk-scrape  ($0.20)      │
  │                                             │
  │  Payment: USDC on Solana or Base            │
  │  Recipient: ${SOLANA_RECIPIENT.slice(0, 8)}...   │
  └─────────────────────────────────────────────┘
  `)
})

npm run dev

curl http://localhost:3000/

# Response:
# {
#   "service": "my-paid-api",
#   "version": "1.0.0",
#   "protocol": "x402",
#   "endpoints": {
#     "/api/scrape": {
#       "method": "POST",
#       "price": "$0.05 per request",
#       "payment": "USDC on Solana or Base"
#     }
#   }
# }

curl -s -w "\nHTTP Status: %{http_code}\n" \
  -X POST http://localhost:3000/api/scrape \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# HTTP Status: 402
#
# Response body:
# {
#   "status": 402,
#   "message": "Payment Required",
#   "paymentRequirements": [
#     {
#       "price": 50000,
#       "recipient": "6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv",
#       "network": "solana",
#       "token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
#       "description": "Scrape a URL through a real 4G/5G mobile proxy",
#       "resource": "/api/scrape",
#       "expiry": "2026-02-08T12:05:00.000Z",
#       "nonce": "a1b2c3d4e5f6"
#     },
#     {
#       "price": 50000,
#       "recipient": "0xF8cD900794245fc36CBE65be9afc23CDF5103042",
#       "network": "base",
#       "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
#       "description": "Scrape a URL through a real 4G/5G mobile proxy",
#       "resource": "/api/scrape",
#       "expiry": "2026-02-08T12:05:00.000Z",
#       "nonce": "a1b2c3d4e5f6"
#     }
#   ]
# }

# After the agent pays USDC on Solana and gets tx signature:
PAYMENT_HEADER=$(echo -n '{
  "txSignature": "5KtP...real_solana_tx_signature...vN3",
  "network": "solana",
  "timestamp": "2026-02-08T12:01:30.000Z",
  "signature": "base64_ed25519_signature_here"
}' | base64)

curl -s -X POST http://localhost:3000/api/scrape \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: $PAYMENT_HEADER" \
  -d '{"url": "https://example.com"}'

# HTTP Status: 200
#
# Response:
# {
#   "success": true,
#   "url": "https://example.com",
#   "status": 200,
#   "content_length": 1256,
#   "content": "<!doctype html>...",
#   "proxy": {
#     "provider": "proxies.sx",
#     "type": "4G/5G mobile",
#     "country": "US"
#   },
#   "payment": {
#     "protocol": "x402",
#     "amount": "$0.05",
#     "currency": "USDC"
#   }
# }

# x402 Service Manifest
# Submit this to agents.proxies.sx/marketplace/

service:
  name: "Mobile Proxy Scraper API"
  version: "1.0.0"
  description: >
    Scrape any URL through real 4G/5G mobile proxies.
    Returns full HTML content with US mobile IP.
    Powered by Proxies.sx infrastructure.

  url: "https://my-paid-api.your-subdomain.workers.dev"

  protocol: "x402"
  payment:
    currency: "USDC"
    networks:
      - name: "solana"
        recipient: "6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv"
        token: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
      - name: "base"
        recipient: "0xF8cD900794245fc36CBE65be9afc23CDF5103042"
        token: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"

  endpoints:
    - path: "/api/scrape"
      method: "POST"
      price: 50000        # $0.05 in micro-units
      description: "Scrape a single URL through mobile proxy"
      input:
        content_type: "application/json"
        schema:
          url: "string (required)"
          headers: "object (optional)"
      output:
        content_type: "application/json"

    - path: "/api/bulk-scrape"
      method: "POST"
      price: 200000       # $0.20 in micro-units
      description: "Batch scrape up to 10 URLs"
      input:
        content_type: "application/json"
        schema:
          urls: "string[] (required, max 10)"
      output:
        content_type: "application/json"

  category: "web-scraping"
  tags:
    - scraping
    - mobile-proxy
    - 4g-5g
    - data-extraction

  contact:
    email: "you@example.com"
    website: "https://your-website.com"

  sla:
    uptime: "99.5%"
    avg_response_time: "2s"
    rate_limit: "100 requests/minute"

import {
  createPaymentRequirement,
  type PaymentRequirement,
} from '@proxies-sx/x402-core'

// Dynamic pricing: charge per URL in bulk requests
app.post('/api/dynamic-scrape', async (c) => {
  const body = await c.req.json<{ urls: string[] }>()
  const urlCount = body.urls?.length || 1

  // Check for payment header first
  const paymentHeader = c.req.header('X-PAYMENT')

  if (!paymentHeader) {
    // Calculate dynamic price: $0.03 per URL
    const pricePerUrl = 30000  // $0.03 in micro-units
    const totalPrice = pricePerUrl * urlCount

    // Build custom PaymentRequirement
    const requirement = createPaymentRequirement({
      price: totalPrice,
      recipient: '6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv',
      network: 'solana',
      description: `Scrape ${urlCount} URLs at $0.03 each = $${(totalPrice / 1000000).toFixed(2)}`,
      resource: '/api/dynamic-scrape',
      expiryMinutes: 10,  // 10 min expiry for bulk jobs
    })

    return c.json(
      {
        status: 402,
        message: 'Payment Required',
        paymentRequirements: [requirement],
        pricing: {
          per_url: '$0.03',
          url_count: urlCount,
          total: `$${(totalPrice / 1000000).toFixed(2)}`,
        },
      },
      402
    )
  }

  // Verify payment and proceed...
  // (same verify logic as before)
})

// Example: Tiered access with different prices
import { createPaymentRequirement } from '@proxies-sx/x402-core'

// Premium tier: residential proxy + JS rendering
// Standard tier: mobile proxy, HTML only
app.post('/api/premium-scrape', async (c) => {
  const paymentHeader = c.req.header('X-PAYMENT')

  if (!paymentHeader) {
    // Offer two payment tiers
    const standard = createPaymentRequirement({
      price: 50000,       // $0.05
      recipient: '6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv',
      network: 'solana',
      description: 'Standard: mobile proxy, HTML only',
      resource: '/api/premium-scrape?tier=standard',
    })

    const premium = createPaymentRequirement({
      price: 250000,      // $0.25
      recipient: '6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv',
      network: 'solana',
      description: 'Premium: residential proxy + JavaScript rendering',
      resource: '/api/premium-scrape?tier=premium',
    })

    return c.json({
      status: 402,
      message: 'Payment Required',
      paymentRequirements: [standard, premium],
    }, 402)
  }

  // Verify and determine which tier was paid for...
})

my-paid-api/
├── src/
│   ├── index.ts          # Main Hono app (Node/Deno/Bun)
│   └── worker.ts         # Cloudflare Workers entry point
├── package.json
├── tsconfig.json
├── wrangler.toml         # Cloudflare Workers config
├── service-manifest.yaml # Marketplace submission
└── .env                  # Local env vars (not committed)

# .env contents:
PROXY_HOST=us.proxies.sx
PROXY_PORT=5057
PROXY_USER=your_username
PROXY_PASS=your_password
PORT=3000