ClawPay — Escrow Payments for AI Agents

You can send and receive trustless escrow payments on Solana using ClawPay. This skill handles the full payment lifecycle: locking funds, confirming delivery, releasing payments, and checking receipts.

Setup

First, check if clawpay is installed:

pip3 show clawpay

If not installed:

pip3 install clawpay

The user's Solana wallet keypair is required. Check for it at the path in the SOLANA_KEYPAIR_PATH environment variable, or look for common locations:

• ~/wallet.json
• ~/.config/solana/id.json
• ~/projects/clawpay/program-keypair.json

If no keypair is found, ask the user to provide one or generate one with solana-keygen new --outfile ~/wallet.json.

How ClawPay Works

ClawPay is a time-locked escrow protocol on Solana. Every payment follows this flow:

1. T0 — Lock: Buyer locks SOL into an escrow account
2. T1 — Deliver: Seller must deliver before the deadline, or funds auto-refund to buyer
3. T2 — Verify: Buyer confirms delivery, or funds auto-release to seller after the window
4. Settle: 98% goes to seller, 1% to ClawPay, 1% to referrer (if any)
5. Receipt: Cryptographic receipt minted on-chain for both parties

No trust required between agents. The timeline enforces everything.

Core Operations

Pay Another Agent (Create Escrow)

When asked to pay an agent or buy a service:

from clawpay import Client
from solders.keypair import Keypair
from solders.pubkey import Pubkey

keypair = Keypair.from_json(open("KEYPAIR_PATH").read())
client = Client(keypair)

escrow = client.create_escrow(
    seller=Pubkey.from_string("SELLER_PUBKEY"),
    amount_sol=AMOUNT,
    delivery_secs=DELIVERY_TIME,       # seconds until delivery deadline
    verification_secs=VERIFICATION_TIME # seconds for dispute window (min 10)
)
print(f"Escrow created: {escrow.address}")
print(f"Amount: {escrow.amount_sol} SOL")
print(f"Delivery deadline: {escrow.t1}")
print(f"Verification ends: {escrow.t2}")

Default values if not specified:

• delivery_secs: 600 (10 minutes)
• verification_secs: 30 (30 seconds)
• amount_sol: Ask the user — never assume an amount

Confirm Delivery (As Seller)

When you've completed a service and need to confirm delivery:

from clawpay import Client
from solders.keypair import Keypair
from solders.pubkey import Pubkey

keypair = Keypair.from_json(open("KEYPAIR_PATH").read())
client = Client(keypair)

escrow_address = Pubkey.from_string("ESCROW_ADDRESS")
client.confirm_delivery(escrow_address, keypair)
print("Delivery confirmed. Waiting for verification window.")

Release Funds (After Verification)

After the verification window passes, anyone can trigger release:

client.auto_release(Pubkey.from_string("ESCROW_ADDRESS"))
print("Funds released to seller.")

Refund (Missed Delivery Deadline)

If the seller missed the delivery deadline:

client.auto_refund(Pubkey.from_string("ESCROW_ADDRESS"))
print("Funds refunded to buyer.")

Check Escrow Status

escrow = client.get_escrow(Pubkey.from_string("ESCROW_ADDRESS"))
print(f"Status: {escrow.status}")
print(f"Amount: {escrow.amount_sol} SOL")
print(f"Delivered: {escrow.delivered}")
print(f"Released: {escrow.released}")

Check Agent Reputation (Receipts)

receipts = client.get_receipts(Pubkey.from_string("AGENT_PUBKEY"))
print(f"Total transactions: {len(receipts)}")
for r in receipts:
    outcome = ["released", "refunded", "disputed"][r.outcome]
    print(f"  #{r.receipt_index}: {r.amount_sol} SOL — {outcome}")

Important Constraints

• Minimum escrow: 0.05 SOL
• Maximum escrow: 10.0 SOL
• Minimum verification window: 10 seconds
• Maximum delivery time: 30 days
• Fee: 2% on settlement (1% ClawPay + 1% referrer)
• Network: Solana Mainnet (default) or Devnet

Guardrails

• NEVER create an escrow without confirming the amount with the user first
• NEVER send funds without verifying the seller's public key
• Always display the escrow address after creation — the user needs it
• Always check escrow status before attempting release or refund
• If a keypair file is not found, ask the user — do not guess
• Report all errors clearly, especially insufficient balance errors
• When checking reputation, mention both successful and failed transactions for honesty

Verification

After any transaction, you can verify on Solana Explorer:

• Program: https://explorer.solana.com/address/F2nwkN9i2kUDgjfLwHwz2zPBXDxLDFjzmmV4TXT6BWeD
• Transaction: https://explorer.solana.com/tx/TRANSACTION_SIGNATURE

Links

• Website: https://claw-pay.com
• SDK: https://pypi.org/project/clawpay/
• GitHub: https://github.com/jakemeyer125-design/ClawPay-SDK