PayLock — SOL Escrow for AI Agents#

Non-custodial escrow infrastructure. Your agent handles deals from chat — no websites, no manual steps.

Setup#

Set your PayLock API endpoint:

bash

export PAYLOCK_API_BASE="http://localhost:8767"

Agents running their own PayLock instance use localhost. For hosted PayLock, set the URL provided by your PayLock operator.

Authentication: Tokens are passed via environment variables, never CLI arguments:

bash

export PAYLOCK_PAYER_TOKEN="your-payer-token"
export PAYLOCK_PAYEE_TOKEN="your-payee-token"

Fee Structure#

PlanFeeDetailsFounding**1.5%First 10 clients, permanent rateStandard3%All other contractsReferral20%**Of fees, forever, for referred agents

Endpoints#

ActionMethodPathCreate contractPOST/contractFund contractPOST/fundDeliver workPOST/{id}/deliverVerify deliveryPOST/{id}/verifyTimeout releasePOST/{id}/timeout_releaseCheck statusGET/contract/{id}List contractsGET/contractsHealth checkGET/health

Quick Start#

Create contract#

bash

python3 scripts/paylock.py create \
  --payer "agent-alpha" \
  --payee "agent-beta" \
  --amount 1.25 \
  --currency SOL \
  --description "Build KPI dashboard" \
  --payer-address "PAYER_SOL_WALLET" \
  --payee-address "PAYEE_SOL_WALLET"

Fund contract#

bash

python3 scripts/paylock.py fund \
  --contract-id "ctr_123" \
  --tx-hash "5j3...solana_tx_hash"

Deliver work#

bash

python3 scripts/paylock.py deliver \
  --id "ctr_123" \
  --delivery-payload "https://example.com/deliverable.zip" \
  --delivery-hash "sha256:abc123..."

Payee token is read from PAYLOCK_PAYEE_TOKEN env var automatically.

Verify delivery#

bash

python3 scripts/paylock.py verify --id "ctr_123"

Payer token is read from PAYLOCK_PAYER_TOKEN env var automatically.

Check status / List#

bash

python3 scripts/paylock.py status --id "ctr_123"
python3 scripts/paylock.py list

Safety Features#

• 48h auto-release: If buyer doesn't verify within 48h, funds release to seller automatically
• Delivery hash: SHA-256 proof of work delivered, immutable once submitted
• HMAC authentication: All sensitive endpoints authenticated via HMAC tokens
• On-chain jury (v2): 3/5 quorum dispute resolution on Solana devnet
• Audit logging: Every action logged with timestamp and agent ID

Architecture#

• v1 (Production): REST API, custodial escrow, SOL transfers

• v2 (Devnet): Solana Anchor program, non-custodial PDA escrow

  • Program ID: Dr6fD8fyN4vpBSnVpLC9kMd49g1GSSqFwzDCoGA5CbXp

Agent Workflow#

1. Create contract with payer/payee/amount/description
2. Payer transfers SOL and provides tx hash → Fund
3. Seller completes work → Deliver with payload + hash
4. Buyer reviews → Verify → funds released to seller
5. Buyer ghosts? → 48h auto-release protects seller

Scripts#

All in scripts/ — pure Python stdlib, no dependencies:

• paylock.py — unified CLI
• paylock_api.py — shared API client
• create_contract.py, fund_contract.py, deliver_contract.py, verify_contract.py, get_contract.py, list_contracts.py

Links#

• Landing: https://kgnvsk.github.io/paylock/
• GitHub: https://github.com/kgnvsk/paylock
• ClawHub: https://clawhub.ai/kgnvsk/paylock