BlockPay is an experimental, open-source payment infrastructure built on top of the x402 open standard and blockchain technology. Please read this carefully before use.
This is NOT traditional finance:
BlockPay is not a bank, payment processor, or licensed financial institution
BlockPay is not affiliated with, endorsed by, or a replacement for Visa, Mastercard, SWIFT, or any regulated payment network
BlockPay does not provide fiat currency services, currency exchange, or regulated money transmission
BlockPay is not designed, intended, or approved to replace or compete with any licensed payment infrastructure
Regulatory responsibility:
Users are solely responsible for ensuring their use of BlockPay complies with applicable laws and regulations in their jurisdiction
Cryptocurrency payments, stablecoin transactions, and AI agent commerce may be restricted or subject to licensing requirements in some regions
BlockPay does not perform KYC/AML checks by default — operators deploying BlockPay infrastructure must implement compliance measures appropriate to their jurisdiction
Technology risk:
Smart contracts and blockchain transactions are irreversible — funds sent cannot be recovered from technical errors
x402 is an emerging open standard — the protocol and its implementations are subject to change
AI agents operating autonomously may initiate payments without direct human approval — users are responsible for configuring spending limits and guardrails
BlockPay carries the inherent risks of experimental software: bugs, downtime, and economic losses
Use at your own risk. By using BlockPay, you acknowledge that you understand and accept these risks.
1. Introduction & Vision
What is BlockPay?
BlockPay is an autonomous payment infrastructure built on the x402 open standard. It enables AI agents, machines (IoT, software bots), and human users to transact over plain HTTP — without accounts, API keys, subscriptions, or traditional payment processors.
The core thesis is simple: HTTP can already carry data. BlockPay makes it carry value.
Since the early 1990s, HTTP has reserved status code 402 Payment Required for "future use." That future is now. The x402 protocol reactivates this dormant code so that any HTTP endpoint can demand and receive cryptographic payment in a single request cycle — settling on-chain in under one second.
Who is BlockPay for?
Why BlockPay exists
The legacy payment stack was built for humans. It fails for machines:
Problem
Legacy Rails
BlockPay / x402
Minimum viable payment
~$0.30 (credit card floor fee)
$0.0001 (limited only by gas)
Account / signup required
Yes
No
Machine-to-machine support
No
Yes — first-class
Settlement time
1–3 business days
< 1 second
Chargeback risk
Yes
No (blockchain finality)
Global access
Restricted by country
Permissionless
API key management
Required
Not needed — payment IS authorization
2. Core Concepts & Terminology
2.1 Glossary
Term
Definition
x402
An open payment protocol that reactivates HTTP status code 402 Payment Required. Servers reply with payment terms; clients pay with a signed blockchain transaction and retry.
HTTP 402
HTTP status code reserved in 1991 for "Payment Required." x402 finally implements it.
Facilitator
A service that verifies signed x402 payment payloads and settles transactions on-chain. It never holds funds. BlockPay ships its own built-in facilitator (@blockpay/facilitator).
Merchant (Resource Server)
Any HTTP server that has added x402 payment middleware to one or more endpoints.
Client (Buyer)
The agent, machine, or human making the HTTP request and paying for the resource.
ERC-8004
An on-chain agent identity standard (ERC-721 NFT) providing verifiable identity, reputation, and capability metadata for AI agents.
BlockPay Facilitator
BlockPay's own facilitator service — handles x402 payment verification, nonce tracking, and USDC settlement on Sui and other supported networks.
USDC
USD Coin — the primary settlement asset. A regulated, audited stablecoin issued by Circle.
Sui Object
The fundamental unit of state on Sui blockchain. Every asset, credential, and agent identity is an independent owned object — enabling parallel transaction execution.
PTB
Programmable Transaction Block — Sui's atomic multi-step transaction primitive. Multiple operations in a single on-chain transaction.
EIP-712
Ethereum Improvement Proposal for typed structured data signing. Used by x402 payment payloads to create cryptographically verifiable payment intents.
EIP-3009 / TransferWithAuthorization
Token transfer method enabling gasless USDC transfers via an off-chain cryptographic signature. The foundation of x402's exact payment scheme.
CAIP-2
Chain Agnostic Improvement Proposal for standard chain identifiers (e.g., sui:mainnet, eip155:8453 for Base).
Scheme
In x402, the payment method type. exact = fixed amount per request. upto = consume up to a maximum. session = pre-pay for a time window.
MCP
Model Context Protocol — an open standard for connecting LLMs to external tools. BlockPay services can be exposed as MCP tools.
A2A
Agent-to-Agent — direct, autonomous transactions between two AI agents with no human in the loop.
2.2 Protocol Stack
3. System Architecture
3.1 High-Level Architecture
3.2 Component Roles
Component
Role
Technology
BlockPay Middleware
Intercepts HTTP requests; returns 402 if no payment; verifies payment response
HTTP status code 402 Payment Required was reserved in RFC 1945 (1996). For 30 years it sat unused — a placeholder for a payment layer that never arrived because digital money infrastructure didn't exist.
In May 2025, Coinbase revived it through the x402 protocol, backed by Cloudflare, Anthropic, Google, and AWS. By August 2025, x402 had processed over 100 million transactions. BlockPay is built on this open standard.
4.2 The Full Payment Handshake
1
STEP 1 — Client makes a normal HTTP request
────────────────────────────────────────────
GET /api/data HTTP/1.1 Host: merchant.example.com
2
STEP 2 — Server responds with HTTP 402 + payment terms
POST https://facilitator.blockpay.xyz/verify { "paymentPayload": , "paymentRequirements": <from step 2> }
BlockPay Facilitator checks: ✓ Signature is valid ✓ Amount matches requirement ✓ Nonce has not been used before ✓ Authorization window is still valid (validAfter / validBefore) ✓ Recipient address matches payTo
6
STEP 6 — Facilitator settles on-chain
────────────────────────────────────────
BlockPay Facilitator broadcasts the USDC TransferWithAuthorization transaction to the Sui network.
Facilitator does not support the requested payment scheme
invalid_x402_version
Protocol version mismatch
unexpected_verify_error
Internal facilitator error during verification
4.6 Replay Attack Protection
x402 implements multiple defense layers:
5. ERC-8004 Agent Identity Standard
5.1 Overview
ERC-8004 is an open standard for trustless AI agent identity on blockchain. Published by the Ethereum Foundation and Consensys in October 2025, it provides three on-chain registries that together give AI agents a verifiable, portable, censorship-resistant identity — the equivalent of a passport and credit history for software.
BlockPay uses ERC-8004 as the identity layer for all AI agents transacting on the platform.
5.2 Three-Registry Architecture
5.3 Agent Identity Object (Sui Move)
On BlockPay's Sui deployment, ERC-8004 identity maps to a native Sui owned object:
5.4 Off-Chain Agent Descriptor (agent.json)
Each agent hosts a /.well-known/agent.json file linked from the on-chain identity:
5.5 Reputation Flow
6. BlockPay Facilitator — The Settlement Layer
6.1 What a Facilitator Does
In the x402 protocol, a facilitator is the trust infrastructure that sits between merchant and blockchain. It is a stateless verification and settlement service — not a custody provider:
Receives the signed payment payload forwarded by the merchant's server
Verifies all cryptographic signatures and constraints
Confirms the nonce has not been used before (replay protection)
Broadcasts the TransferWithAuthorization call to the target chain
Returns a settlement receipt containing the on-chain transaction hash
Critically: the facilitator never holds, custodies, or controls funds. It only validates the client's pre-authorized intent and triggers the corresponding on-chain transfer.
6.2 BlockPay Facilitator Architecture
6.3 Facilitator API
The BlockPay Facilitator exposes two endpoints that the x402 middleware calls automatically:
POST /verify — Validate a payment payload without settling
POST /settle — Verify and broadcast the on-chain transaction
6.4 Supported Networks
Network
Chain ID
Status
Notes
Sui
sui:mainnet
✅ Primary
BlockPay's default network
Sui Testnet
sui:testnet
✅ Testnet
Development / testing
Solana
solana:mainnet
✅ Live
SVM USDC
Solana Devnet
solana:devnet
✅ Testnet
Development / testing
Base
eip155:8453
✅ Live
EVM USDC
Base Sepolia
eip155:84532
✅ Testnet
Development / testing
Polygon
eip155:137
✅ Live
Avalanche
eip155:43114
✅ Live
6.5 BlockPay Echo Merchant — Test Without Deploying
BlockPay ships a live Echo Merchant for end-to-end integration testing. It behaves exactly like a real merchant — advertising payment requirements, verifying your payload, settling on-chain — but refunds all payments immediately so testing costs nothing.
6.6 Facilitator Credentials
Tier
Volume
Facilitator fee
Free tier
First 1,000 settlements
$0
Standard
> 1,000 settlements
$0.001 per settlement
Note: Facilitator fees are separate from on-chain gas (Sui gas ≈ $0.0001 per transaction).
7. Why Sui Network
7.1 The Fundamental Problem with Account-Based Chains
Traditional blockchains (Ethereum, Solana) serialize transactions against a global state tree. Every transaction — even if it touches completely different assets — must be ordered and sequenced through consensus. This creates a throughput ceiling that is fundamentally incompatible with millions of daily AI agent micropayments.
7.2 Sui's Object-Centric Model
Sui's breakthrough is treating every asset as an independent owned Object. If two transactions touch different objects, they can execute in parallel — no waiting, no bottleneck.
7.3 Why This Matters for BlockPay
Property
Sui Value
BlockPay Impact
Transaction finality
~400ms
HTTP request round-trip completes before client timeout
Throughput
100,000+ TPS
Supports platform-scale A2A payment volume
Gas fee
< $0.001 per tx
Makes $0.001 micropayments economically viable
Parallel execution
Native object model
Thousands of agent payments execute simultaneously
PTBs
Atomic multi-step tx
Split payments + state update + NFT mint in one tx
Move language
Linear type system
Double-spend impossible at compile time
Owned objects
First-class
Agent identity NFT + stake live in one owned object
7.4 Move Language — Safety by Design
Move's linear type system makes digital assets behave like physical resources: they cannot be accidentally copied, duplicated, or destroyed. This directly prevents an entire class of re-entrancy and double-spend bugs.
Compare to Solidity, where a missing reentrancy guard caused the DAO hack ($60M, 2016) and numerous subsequent exploits.
7.5 Comparison Table
8. BlockPay Modules
8.1 Module Map
8.2 Payment Flow States
8.3 Revenue Splitting (Sui PTB)
BlockPay supports configurable revenue splitting — a single payment is atomically distributed to multiple recipients in one on-chain transaction:
9. SDK & Integration Guide
9.1 Installation
9.2 Quick Start — Merchant (Sell a service)
Express.js
Hono (Edge / Cloudflare Workers)
Flask (Python)
9.3 Quick Start — Client (Pay for a service)
TypeScript
Python (httpx)
Go
9.4 Agent Registration (ERC-8004 Identity)
9.5 MCP Server Integration
Expose BlockPay-protected services as MCP tools — discoverable by Claude, GPT-4, and any other MCP-compatible agent:
Resource requires payment — includes X-PAYMENT-REQUIRED header
400 Bad Request
Malformed payment payload
401 Unauthorized
Invalid payment signature
402 + error body
Payment failed — see error field for specific error code
500 Internal Server Error
Facilitator or settlement error
Appendix B: Glossary Quick Reference
Abbreviation
Full Term
A2A
Agent-to-Agent
CAIP
Chain Agnostic Improvement Proposal
EIP
Ethereum Improvement Proposal
HSM
Hardware Security Module
IoT
Internet of Things
M2M
Machine-to-Machine
MCP
Model Context Protocol
PTB
Programmable Transaction Block (Sui)
TPS
Transactions Per Second
TTL
Time To Live
USDC
USD Coin (Circle stablecoin)
zkML
Zero-Knowledge Machine Learning
BlockPay is open-source infrastructure. Contributions, issue reports, and feedback are welcome. The x402 standard is maintained by the x402 Foundation. BlockPay is an independent implementation built on top of it.
BlockPay Technical Documentation — v1.0 — March 2026Built on x402 open standard · Settled on Sui
# Test a real x402 payment against BlockPay's echo server
# Tokens are refunded instantly; BlockPay covers network fees
# Sui testnet
GET https://echo.blockpay.xyz/api/sui-testnet/paid-content
# Solana devnet
GET https://echo.blockpay.xyz/api/solana-devnet/paid-content
# Base Sepolia
GET https://echo.blockpay.xyz/api/base-sepolia/paid-content
# .env for production use
BLOCKPAY_FACILITATOR_URL=https://facilitator.blockpay.xyz
BLOCKPAY_API_KEY_ID=your_key_id
BLOCKPAY_API_KEY_SECRET=your_key_secret
Traditional Account-Based Model:
─────────────────────────────────
Global State:
balances: { Alice: 100, Bob: 50, Carol: 75 }
Tx A: Alice → Dave (reads/writes Alice's balance)
Tx B: Bob → Eve (reads/writes Bob's balance)
Problem: Both update the SAME state object.
Must execute: Tx A THEN Tx B (sequential)
──────────────────────────────────────────────
Sui Object-Based Model:
───────────────────────
Object 0x1a2b: { owner: Alice, balance: 100 }
Object 0x3c4d: { owner: Bob, balance: 50 }
Tx A touches Object 0x1a2b (Alice's object)
Tx B touches Object 0x3c4d (Bob's object)
No shared state → Execute A and B IN PARALLEL ✓
// Move enforces: once a resource is moved, it cannot be used again.
// The COMPILER rejects double-spend before it reaches the chain.
// ✗ IMPOSSIBLE in Move:
let coin = Coin { value: 100 };
let coin_copy = copy coin; // ERROR: Coin does not have 'copy' ability
transfer(coin, recipient_a);
transfer(coin, recipient_b); // ERROR: 'coin' was already moved
// ✓ CORRECT pattern — single transfer:
let coin = Coin { value: 100 };
transfer::public_transfer(coin, recipient);
// 'coin' no longer exists in this scope — safely moved
// Sensor node running on edge hardware
// Pays for each weather data fetch autonomously
import { BlockPayClient } from "@blockpay/client";
const sensor = new BlockPayClient({
keypair: loadKeypairFromSecureStorage(),
network: "sui:mainnet",
maxBudget: "10000", // Never pay more than 0.01 USDC per call
});
// Every 5 minutes, pay for and fetch calibration data
setInterval(async () => {
const data = await sensor.fetch(
"https://data.weather.io/api/v1/calibration"
);
const { temperature_offset, humidity_correction } = await data.json();
applySensorCalibration(temperature_offset, humidity_correction);
}, 5 * 60 * 1000);
// Standard web app — human user pays per article read
import { BlockPayBrowser } from "@blockpay/browser";
const client = new BlockPayBrowser({
walletProvider: window.suiWallet, // any Sui-compatible browser wallet
network: "sui:mainnet",
});
async function readPremiumArticle(articleId: string) {
const response = await client.fetch(
`https://publisher.example.com/articles/${articleId}`
);
if (!response.ok) {
throw new Error("Payment failed or article unavailable");
}
const article = await response.json();
renderArticle(article);
}
// User's wallet prompts for confirmation before signing payment
// No account signup, no subscription — pay exactly for what you read
// Agent A discovers Agent B's translation service and pays autonomously
import { BlockPayClient } from "@blockpay/client";
const agentA = new BlockPayClient({
keypair: agentAKeypair,
network: "sui:mainnet",
maxBudget: "50000", // 0.05 USDC max per call
});
// Agent A autonomously discovers and calls Agent B
const result = await agentA.fetch(
"https://agent-b.example.com/translate",
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ text: "Hello world", targetLang: "vi" }),
}
);
const { translation } = await result.json();
// translation: "Xin chào thế giới"
// Agent A paid 0.005 USDC autonomously — no human intervention
-- Payment events (append-only ledger)
CREATE TABLE payment_events (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tx_hash TEXT UNIQUE NOT NULL,
network TEXT NOT NULL, -- "sui:mainnet"
payer_wallet TEXT NOT NULL,
payee_wallet TEXT NOT NULL,
amount_usdc NUMERIC(18, 6) NOT NULL,
resource_uri TEXT NOT NULL,
scheme TEXT NOT NULL, -- "exact" | "upto" | "session"
settled_at TIMESTAMPTZ NOT NULL,
created_at TIMESTAMPTZ DEFAULT NOW()
);
-- TimescaleDB hypertable for time-series analytics
SELECT create_hypertable('payment_events', 'settled_at');
-- Agent registry (ERC-8004 mirror)
CREATE TABLE agent_registry (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
agent_id TEXT UNIQUE NOT NULL, -- on-chain NFT ID
wallet_address TEXT NOT NULL,
name TEXT NOT NULL,
capabilities TEXT[],
reputation_score INTEGER DEFAULT 5000, -- 0–10000 basis points
total_jobs INTEGER DEFAULT 0,
nft_object_id TEXT, -- Sui object ID
created_at TIMESTAMPTZ DEFAULT NOW()
);
-- Nonce registry (replay protection)
CREATE TABLE used_nonces (
nonce TEXT PRIMARY KEY,
network TEXT NOT NULL,
used_at TIMESTAMPTZ NOT NULL,
expires_at TIMESTAMPTZ NOT NULL -- prune after validBefore + buffer
);
-- Auto-expire nonces
CREATE INDEX ON used_nonces (expires_at);
const client = new BlockPayClient({
keypair,
network: "sui:mainnet",
// Spending limits — enforced client-side before signing
maxBudget: {
perRequest: "10000", // 0.01 USDC max per single request
perHour: "1000000", // 1.00 USDC max per hour
perDay: "10000000", // 10.00 USDC max per day
},
// Allowlist — only pay these merchants
allowedMerchants: [
"0xMERCHANT_WALLET_A",
"0xMERCHANT_WALLET_B",
],
// Require human confirmation above threshold
humanApprovalThreshold: "50000", // 0.05 USDC — prompt human above this
});