rocket_launch Quick Start

Make your first API call in minutes

PicoPayd APIs use the x402 protocol — pay per call with USDC on Base. No subscriptions, no API keys to manage. This guide walks through a complete integration using the Email Validator API.

check_circle No sign-up required

check_circle Pay only what you use

check_circle Works with any language

Set up a wallet

PicoPayd uses the x402 protocol — each API call deducts a small amount of USDC directly from your wallet on Base (an Ethereum L2). You need a wallet funded with USDC to make calls.

account_balance_wallet

Option A — Coinbase Wallet

Download Coinbase Wallet, create a wallet, and bridge or buy USDC on Base. Easiest for beginners.

code

Option B — Programmatic wallet

Use Coinbase CDP or viem/ethers.js to create a wallet in code. Best for AI agents and automated pipelines.

wallet_setup.py

from cdp import Cdp, Wallet

# Initialize Coinbase Developer Platform SDK
Cdp.configure_from_json("cdp_api_key.json")

# Create a new wallet on Base
wallet = Wallet.create(network_id="base-mainnet")
address = wallet.default_address

print("Wallet address: {address.address_id}")

# Fund with USDC — send USDC to the address above
# Minimum recommended: $1 USDC for testing

info

Base network only. PicoPayd currently accepts USDC on Base mainnet and Base Sepolia (testnet). Make sure you're on the right network before funding.

Install the x402 client library

The x402 client handles the payment handshake automatically. When your request returns an HTTP 402, the client pays with your wallet and retries — you don't need to think about it.

# Install the x402 client for Python
pip install x402

# Also install the Coinbase CDP SDK if using programmatic wallets
pip install cdp-sdk

# Install the x402 client for Node.js
npm install x402-fetch

# Or with bun / pnpm
bun add x402-fetch
pnpm add x402-fetch

# No library needed for cURL — but you must handle the 402 handshake manually.
# See Step 4 for a cURL example using pre-signed payment headers.

# For testing on testnet, set your wallet env var:
export PICOPAYD_WALLET_KEY="0xYOUR_PRIVATE_KEY"

Make your first API call

We'll use the Email Validator API as an example. It checks syntax, performs an MX record lookup, detects disposable addresses, and returns a confidence score — all for $0.001 per call.

POST https://email.picopayd.codefission.co.uk/api/validate $0.001 / call

import x402
from cdp import Cdp, Wallet

# Load your wallet
Cdp.configure_from_json("cdp_api_key.json")
wallet = Wallet.fetch("YOUR_WALLET_ID")

# Create an x402-enabled HTTP client
client = x402.Client(wallet)

# Call the Email Validator API
response = client.post(
    "https://email.picopayd.codefission.co.uk/api/validate",
    json={"email": "hello@example.com"}
)

result = response.json()
print(f"Valid: {result['valid']}")
print(f"Confidence: {result['confidence']}")

import { createX402Fetch } from 'x402-fetch';
import { privateKeyToAccount } from 'viem/accounts';

// Load your wallet from a private key
const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY);

// Create an x402-enabled fetch
const fetchWithPayment = createX402Fetch(account);

// Call the Email Validator API
const response = await fetchWithPayment(
  'https://email.picopayd.codefission.co.uk/api/validate',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email: 'hello@example.com' }),
  }
);

const result = await response.json();
console.log('Valid:', result.valid);
console.log('Confidence:', result.confidence);

# Step 1: Make the initial request (will return 402)
curl -X POST https://email.picopayd.codefission.co.uk/api/validate \
  -H "Content-Type: application/json" \
  -d '{"email": "hello@example.com"}'

# The 402 response includes a payment payload:
# { "x402Version": 1, "accepts": [{ "scheme": "exact", "network": "base", ... }] }

# Step 2: Sign the payment and retry with X-Payment header
# (Use the x402-cli tool to sign: npm install -g x402-cli)
x402 pay --key $WALLET_KEY https://email.picopayd.codefission.co.uk/api/validate \
  --data '{"email": "hello@example.com"}'

Handle the response

A successful call returns a JSON object with a valid boolean, detailed check results, and a confidence score from 0.0 to 1.0.

Response — 200 OK 200 OK

{
  "valid": true,
  "email": "hello@example.com",
  "checks": {
    "syntaxOk": true,
    "mxExists": true,
    "isDisposable": false
  },
  "confidence": 1.0
}

Field	Type	Description
`valid`	boolean	Whether the email address is considered deliverable
`checks.syntaxOk`	boolean	Email format passes RFC 5322 syntax validation
`checks.mxExists`	boolean	Domain has valid MX records — mail can be delivered
`checks.isDisposable`	boolean	Address is from a known disposable email provider
`confidence`	number	Score from 0.0–1.0. Penalised for missing MX (−0.6) or disposable (−0.3)

Handle errors

The API uses standard HTTP status codes. The most common non-2xx response you'll encounter is 402 Payment Required — this is handled automatically by the x402 client. You only need to catch it manually if you're making raw HTTP calls.

Status	Meaning	Action
200	Success	Parse the JSON response
400	Invalid request body	Check your JSON — likely a missing or malformed field
402	Payment required	Handled automatically by the x402 client. If manual: sign and retry with `X-Payment` header
429	Rate limited	Back off and retry after the `Retry-After` header duration
500	Server error	Retry with exponential backoff. Check status page if persistent

error_handling.py

import x402

client = x402.Client(wallet)

try:
    response = client.post(
        "https://email.picopayd.codefission.co.uk/api/validate",
        json={"email": "hello@example.com"}
    )
    response.raise_for_status()
    result = response.json()

except x402.InsufficientFundsError:
    print("Wallet balance too low — top up with USDC on Base")

except x402.PaymentError as e:
    print(f"Payment failed: {e}")

except Exception as e:
    print(f"Request failed: {e}")

check

You're ready to build

That's the full integration. The same pattern works for every PicoPayd API — swap the endpoint URL and request body, and you're done.