The x402 protocol from Coinbase and Cloudflare revived the HTTP 402 status code and turned it into a machine-readable payment layer for the internet. When an AI agent hits a paid endpoint, the server returns a 402 with payment details, the agent pays in USDC, and retries the request with a payment receipt header. Simple, elegant, and open.

But x402 is a pay-first protocol. The agent pays before it sees the result. For a $0.001 API call, that's fine. For a $50 research report or a multi-step workflow where each step costs real money? You need guarantees that the work will actually be delivered — and a way to get your money back if it isn't.

That's where ClawPay comes in.

The gap x402 leaves open

x402 solves payment negotiation brilliantly. A server says "this costs X," the agent pays X, and the server delivers. But it assumes the server will deliver. There's no escrow, no dispute mechanism, and no on-chain reputation to help an agent decide whether a given service is trustworthy in the first place.

Consider a real scenario: your research agent needs to buy a market analysis report from another agent. The seller wants 5 USDC. With x402 alone, your agent pays 5 USDC up front and hopes the report arrives and is actually useful. If the seller delivers garbage (or nothing), the payment is already gone.

With ClawPay wrapping that transaction, the funds sit in a time-locked escrow until your agent confirms the delivery meets expectations. If the seller ghosts, the escrow auto-refunds when the deadline expires. If there's a dispute, stake-weighted arbitration resolves it — no humans, no support tickets.

Architecture: x402 for negotiation, ClawPay for settlement

The cleanest pattern is to use both protocols together:

  1. x402 handles discovery and pricing. Your agent hits an endpoint, gets a 402 response with the price and payment details.
  2. ClawPay handles the actual money. Instead of paying directly via the x402 payment header, your agent creates a ClawPay escrow for the amount. The seller sees the locked funds and begins work.
  3. Delivery and verification happen on ClawPay's timeline. The seller delivers, the buyer confirms, funds release. Both agents get a cryptographic receipt added to their on-chain identity.

This gives you the best of both worlds: x402's clean HTTP-native negotiation and ClawPay's trustless settlement guarantees.

Tutorial: Wrapping an x402 endpoint with ClawPay escrow

Here's a working example. We'll build a Python agent that discovers a paid service via x402, then settles the payment through ClawPay.

Prerequisites

BASH
pip install clawpay requests

You'll need a ClawPay API key from claw-pay.com.

Step 1: Discover the service via x402

PYTHON payment_flow.py
import requests

# Hit a paid endpoint — get the 402 response
response = requests.get("https://api.example-agent.com/market-report")

if response.status_code == 402:
  # x402 tells us what the service costs
  payment_details = response.json()
  price = payment_details["amount"]           # e.g., 5.00
  currency = payment_details["currency"]      # "USDC"
  seller = payment_details["payTo"]        # seller's Solana address
  service = payment_details["description"]    # "Market Analysis Report"

  print(f"Service: {service}")
  print(f"Price: {price} {currency}")
  print(f"Seller: {seller}")

Step 2: Check the seller's reputation on ClawPay

Before spending money, check whether this seller has a track record:

PYTHON payment_flow.py
from clawpay import Client

client = Client("sk_live_your_api_key")

# Pull the seller's receipt chain
receipts = client.get_receipts(seller)
completed = [r for r in receipts if r.status == "settled"]
disputed = [r for r in receipts if r.status == "disputed"]

print(f"Seller has {len(completed)} completed transactions")
print(f"Seller has {len(disputed)} disputes")

# Your agent decides: is this seller trustworthy?
if len(completed) < 3 or len(disputed) > len(completed) * 0.2:
  print("Seller doesn't have enough reputation. Skipping.")
  exit()

Step 3: Create an escrow instead of paying directly

PYTHON payment_flow.py
# Lock funds in escrow — seller sees the money but can't touch it yet
escrow = client.create_escrow(
  amount=price,
  seller=seller,
  deadline_minutes=60,            # seller has 1 hour to deliver
  verification_minutes=120,         # buyer has 2 hours to verify
  content_hash=service              # ties the escrow to the specific service
)

print(f"Escrow created: {escrow.id}")
print(f"Status: {escrow.status}")  # "locked"
print(f"Deadline: {escrow.deadline}")

Step 4: Request delivery using the escrow ID

PYTHON payment_flow.py
# Tell the seller's endpoint about the escrow
# The seller can verify the locked funds on-chain before starting work
response = requests.post(
  "https://api.example-agent.com/market-report/deliver",
  headers={
    "X-ClawPay-Escrow": escrow.id,
    "X-ClawPay-Buyer": "your_agent_pubkey"
  }
)

report = response.json()

Step 5: Verify and release

PYTHON payment_flow.py
# Your agent reviews the delivery
if report_meets_expectations(report):
  # Confirm delivery — funds release to seller
  client.confirm_delivery(escrow.id)
  print("Payment released. Receipt added to both chains.")
else:
  # Raise a dispute — arbitration pool handles it
  client.dispute(escrow.id, reason="Report was incomplete")
  print("Dispute filed. Arbitration in progress.")

The complete flow

PYTHON x402_clawpay_agent.py
from clawpay import Client
import requests

client = Client("sk_live_your_api_key")

# 1. Discover via x402
resp = requests.get("https://api.example-agent.com/market-report")
if resp.status_code != 402:
  exit()

details = resp.json()

# 2. Check reputation
receipts = client.get_receipts(details["payTo"])
if len([r for r in receipts if r.status == "settled"]) < 3:
  print("Insufficient seller reputation")
  exit()

# 3. Escrow the payment
escrow = client.create_escrow(
  amount=details["amount"],
  seller=details["payTo"],
  deadline_minutes=60,
  verification_minutes=120
)

# 4. Request delivery
report = requests.post(
  "https://api.example-agent.com/market-report/deliver",
  headers={"X-ClawPay-Escrow": escrow.id}
).json()

# 5. Verify and settle
if report.get("data") and len(report["data"]) > 0:
  client.confirm_delivery(escrow.id)
  print(f"Settled. Escrow {escrow.id} complete.")
else:
  client.dispute(escrow.id, reason="Empty report delivered")

What happens at each failure point

This is where the escrow model earns its keep:

Failure x402 alone With ClawPay
Seller never delivers Money gone Auto-refund at deadline
Seller delivers garbage Money gone Dispute → arbitration
Buyer ghosts verification Seller waits forever Auto-release to seller after verification window
Network issues mid-delivery Ambiguous state Escrow holds until resolution

Every failure mode resolves deterministically. No party can stall, ghost, or game the system.

When to use each protocol

Use x402 alone for micropayments where the cost of a bad outcome is negligible — sub-cent API calls, token-gated content access, rate-limited endpoints. The overhead of escrow isn't worth it for a $0.001 transaction.

Add ClawPay when the transaction amount matters, when the service requires delivery time, when you're dealing with an unknown counterparty, or when you need an auditable receipt chain. The sweet spot is transactions between 0.01 and 10 SOL (roughly $1.50 to $1,500 at current prices) where trust actually needs to be established.

Use both together for the strongest pattern: x402 for how agents find and negotiate with each other, ClawPay for how they actually settle. This is what we're building toward — a composable trust layer that slots in wherever agents transact.

Get started

BASH
pip install clawpay

Grab an API key at claw-pay.com, read the docs, and check out the Python SDK reference. The ClawPay protocol is live on Solana mainnet at program address F2nwkN9i2kUDgjfLwHwz2zPBXDxLDFjzmnV4TXT6BWeD.

ClawPay is trustless escrow infrastructure for AI agent commerce on Solana. Questions? Reach out at claw-pay.com.