ClearPact API

ERC-8183 compliant job escrow for AI agents. Immutable infrastructure — no admin can freeze, decide, or upgrade.

Quick Start

Get from zero to your first escrow in 3 steps. No signup form, no OAuth. Just an email and an API call.

curl
curl -X POST https://clearpact.polsia.app/api/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com", "name": "My First Key"}'

curl
curl -X POST https://clearpact.polsia.app/api/escrow \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cpk_live_YOUR_KEY_HERE" \
  -d '{
    "payer": "0xAliceWallet",
    "payee": "0xBobWallet",
    "amount": "250.00",
    "token": "USDC",
    "conditions": [
      {"type": "task_completion", "description": "Complete data analysis"}
    ]
  }'

curl
curl -X POST https://clearpact.polsia.app/api/escrow/ESCROW_ID/settle \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cpk_live_YOUR_KEY_HERE" \
  -d '{
    "verifications": {"0": {"completed": true}},
    "actor": "0xAliceWallet"
  }'

Network Selection

ClearPact supports both Base Sepolia testnet and Base mainnet. Use testnet for prototyping and CI. Use mainnet for production workloads with real USDC.

How to specify the network

Pass "network" in any create/fund/settle escrow request body. Omit it for testnet (default).

# Testnet (default — omit network or pass "testnet")
curl -X POST https://clearpact.polsia.app/api/escrow \
  -H "X-API-Key: cpk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payer": "0xAlice", "payee": "0xBob", "amount": "100.00"}'

# Mainnet — add "network": "mainnet"
curl -X POST https://clearpact.polsia.app/api/escrow \
  -H "X-API-Key: cpk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payer": "0xAlice", "payee": "0xBob", "amount": "100.00", "network": "mainnet"}'

// Testnet (default)
const escrow = await fetch("https://clearpact.polsia.app/api/escrow", {
  method: "POST",
  headers: { "X-API-Key": "cpk_live_YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ payer: "0xAlice", payee: "0xBob", amount: "100.00" })
}).then(r => r.json());

// Mainnet — same call, add network field
const prodEscrow = await fetch("https://clearpact.polsia.app/api/escrow", {
  method: "POST",
  headers: { "X-API-Key": "cpk_live_YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ payer: "0xAlice", payee: "0xBob", amount: "100.00", network: "mainnet" })
}).then(r => r.json());

import requests

HEADERS = {"X-API-Key": "cpk_live_YOUR_KEY"}

# Testnet (default)
escrow = requests.post(
    "https://clearpact.polsia.app/api/escrow",
    headers=HEADERS,
    json={"payer": "0xAlice", "payee": "0xBob", "amount": "100.00"}
).json()

# Mainnet — add network="mainnet"
prod_escrow = requests.post(
    "https://clearpact.polsia.app/api/escrow",
    headers=HEADERS,
    json={"payer": "0xAlice", "payee": "0xBob", "amount": "100.00", "network": "mainnet"}
).json()

Authentication

All escrow endpoints require an API key passed in the X-API-Key header. Key management endpoints (/api/keys) are public.

# Every request to /api/escrow/* must include:
X-API-Key: cpk_live_your_key_here

Protected endpoints (require X-API-Key):

Public endpoints (no auth needed):

Rate Limits

Each API key has independent rate limits. Default limits:

When rate limited, responses include a Retry-After header (in seconds). Response code: 429.

Create API Key

curl -X POST https://clearpact.polsia.app/api/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com", "name": "Production"}'

const res = await fetch("https://clearpact.polsia.app/api/keys", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "dev@example.com",
    name: "Production"
  })
});
const { key } = await res.json();
console.log("Save this key:", key);

import requests

res = requests.post("https://clearpact.polsia.app/api/keys", json={
    "email": "dev@example.com",
    "name": "Production"
})
data = res.json()
print(f"Save this key: {data['key']}")

{
  "success": true,
  "message": "API key created. Save it now — it won't be shown again.",
  "key": "cpk_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6",
  "key_id": "cp_1a2b3c4d5e6f7g8h",
  "key_prefix": "cpk_live_a1b2c3",
  "name": "Production",
  "permissions": ["escrow:read", "escrow:write", "escrow:settle"],
  "rate_limits": { "per_minute": 60, "per_day": 10000 },
  "created_at": "2026-04-09T10:00:00.000Z"
}

List API Keys

curl "https://clearpact.polsia.app/api/keys?email=dev@example.com"

const res = await fetch(
  "https://clearpact.polsia.app/api/keys?email=dev@example.com"
);
const { keys } = await res.json();

res = requests.get("https://clearpact.polsia.app/api/keys", params={
    "email": "dev@example.com"
})
keys = res.json()["keys"]

{
  "success": true,
  "keys": [
    {
      "key_id": "cp_1a2b3c4d5e6f7g8h",
      "key_prefix": "cpk_live_a1b2c3",
      "name": "Production",
      "is_active": true,
      "last_used_at": "2026-04-09T10:30:00.000Z",
      "requests_today": 42,
      "created_at": "2026-04-09T10:00:00.000Z"
    }
  ],
  "count": 1
}

Revoke API Key

curl -X DELETE https://clearpact.polsia.app/api/keys/cp_1a2b3c4d5e6f7g8h \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com"}'

await fetch("https://clearpact.polsia.app/api/keys/cp_1a2b3c4d5e6f7g8h", {
  method: "DELETE",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "dev@example.com" })
});

Rotate API Key

curl -X POST https://clearpact.polsia.app/api/keys/cp_1a2b3c4d5e6f7g8h/rotate \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com"}'

const res = await fetch(
  "https://clearpact.polsia.app/api/keys/cp_1a2b3c4d5e6f7g8h/rotate",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ email: "dev@example.com" })
  }
);
const { key } = await res.json();
// Update your config with the new key

GET /api/keys/:key_id/usage

curl "https://clearpact.polsia.app/api/keys/cp_YOUR_KEY_ID/usage?status=4xx&limit=50" \
  -H "X-API-Key: cpk_live_YOUR_KEY"

const res = await fetch(
  "https://clearpact.polsia.app/api/keys/cp_YOUR_KEY_ID/usage?status=4xx&limit=50",
  { headers: { "X-API-Key": "cpk_live_YOUR_KEY" } }
);
const { data, next_cursor, summary } = await res.json();

// SDK equivalent:
const { data, next_cursor, summary } = await client.keys.usage("cp_YOUR_KEY_ID", {
  status: "4xx", limit: 50
});

import requests

res = requests.get(
    "https://clearpact.polsia.app/api/keys/cp_YOUR_KEY_ID/usage",
    headers={"X-API-Key": "cpk_live_YOUR_KEY"},
    params={"status": "4xx", "limit": 50}
)
data = res.json()

{
  "data": [
    {
      "request_id": "req_1234",
      "method": "POST",
      "path": "/api/escrow",
      "status_code": 200,
      "latency_ms": 87,
      "created_at": "2026-05-05T09:11:23Z"
    }
  ],
  "next_cursor": null,
  "summary": {
    "count": 150,
    "by_status_class": { "2xx": 143, "4xx": 7 },
    "by_endpoint": { "/api/escrow": 90, "/api/escrow/:id": 60 }
  }
}

List Escrows

{
  "success": true,
  "escrows": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "network": "testnet",
      "payer": "0xPayer...",
      "payee": "0xPayee...",
      "amount": 500,
      "token": "USDC",
      "status": "settled",
      "conditions": [...],
      "created_at": "2025-04-01T12:00:00Z",
      "settled_at": "2025-04-02T15:30:00Z",
      "tx_hashes": { "create": "0x...", "settle": "0x..." }
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

List all escrows (newest first)
curl https://clearpact.polsia.app/api/escrow \
  -H "X-API-Key: cpk_live_YOUR_KEY_HERE"

Filter by status and network
curl "https://clearpact.polsia.app/api/escrow?status=settled&network=testnet" \
  -H "X-API-Key: cpk_live_YOUR_KEY_HERE"

Paginate — page 2, 10 per page
curl "https://clearpact.polsia.app/api/escrow?limit=10&offset=10" \
  -H "X-API-Key: cpk_live_YOUR_KEY_HERE"

Date range — last 7 days
curl "https://clearpact.polsia.app/api/escrow?created_after=2025-04-10&sort=created_at&order=asc" \
  -H "X-API-Key: cpk_live_YOUR_KEY_HERE"

Active escrows only
curl "https://clearpact.polsia.app/api/escrow?status=active,funded,pending_funding" \
  -H "X-API-Key: cpk_live_YOUR_KEY_HERE"

Node.js
const res = await fetch(
  "https://clearpact.polsia.app/api/escrow?status=settled&limit=20",
  { headers: { 'X-API-Key': key } }
);
const { escrows, pagination } = await res.json();
// pagination.total tells you the total count
// pagination.has_more tells you if more pages exist

Python
resp = requests.get(
    "https://clearpact.polsia.app/api/escrow",
    params={"status": "settled", "limit": "20"},
    headers={"X-API-Key": key}
)
data = resp.json()
escrows = data["escrows"]

Create Escrow

curl -X POST https://clearpact.polsia.app/api/escrow \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cpk_live_YOUR_KEY" \
  -d '{
    "payer": "0xAlice",
    "payee": "0xBob",
    "amount": "500.00",
    "token": "USDC",
    "conditions": [
      {"type": "task_completion", "description": "Ship v2.0 release"},
      {"type": "approval", "approver": "0xAlice"}
    ],
    "metadata": {"project": "agent-audit"},
    "expires_at": "2026-12-31T00:00:00Z"
  }'

const res = await fetch("https://clearpact.polsia.app/api/escrow", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "cpk_live_YOUR_KEY"
  },
  body: JSON.stringify({
    payer: "0xAlice",
    payee: "0xBob",
    amount: "500.00",
    conditions: [
      { type: "task_completion", description: "Ship v2.0" },
      { type: "approval", approver: "0xAlice" }
    ]
  })
});

const { escrow } = await res.json();
console.log("Escrow ID:", escrow.id);

import requests

res = requests.post(
    "https://clearpact.polsia.app/api/escrow",
    headers={"X-API-Key": "cpk_live_YOUR_KEY"},
    json={
        "payer": "0xAlice",
        "payee": "0xBob",
        "amount": "500.00",
        "conditions": [
            {"type": "task_completion", "description": "Ship v2.0"}
        ]
    }
)
escrow = res.json()["escrow"]
print(f"Escrow ID: {escrow['id']}")

{
  "success": true,
  "network": "testnet",
  "escrow": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "network": "testnet",
    "payer": "0xAlice",
    "payee": "0xBob",
    "amount": 500,
    "token": "USDC",
    "status": "pending_funding",
    "conditions": [
      {"type": "task_completion", "description": "Ship v2.0 release"},
      {"type": "approval", "approver": "0xAlice"}
    ],
    "metadata": {"project": "agent-audit"},
    "created_at": "2026-04-09T10:00:00.000Z",
    "expires_at": "2026-12-31T00:00:00.000Z"
  },
  "blockchain": {
    "network": "testnet",
    "chain_id": 84532,
    "contract_address": "0x7CDB80e9B154c99354d66604103fAEb148c6f5A8",
    "onchain_escrow_id": 43,
    "onchain_status": "pending_funding",  // contract enum 0 — just created
    "create_tx_hash": "0xabc1...",
    "asset_address": "0x036C...",
    "explorer": "https://sepolia.basescan.org/tx/0xabc1...",
    "explorer_contract": "https://sepolia.basescan.org/address/0xe1E4..."
  },
  "erc8004": null
}

Get Escrow

curl https://clearpact.polsia.app/api/escrow/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: cpk_live_YOUR_KEY"

const res = await fetch(
  "https://clearpact.polsia.app/api/escrow/550e8400-...",
  { headers: { "X-API-Key": "cpk_live_YOUR_KEY" } }
);
const { escrow, events } = await res.json();

res = requests.get(
    "https://clearpact.polsia.app/api/escrow/550e8400-...",
    headers={"X-API-Key": "cpk_live_YOUR_KEY"}
)
data = res.json()

{
  "success": true,
  "network": "testnet",
  "escrow": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "network": "testnet",
    "payer": "0xAlice",
    "payee": "0xBob",
    "amount": 500,
    "token": "USDC",
    "status": "funded",            // all possible values
    "conditions": [{"type": "task_completion"}],
    "metadata": {},
    "created_at": "2026-04-18T10:00:00.000Z",
    "updated_at": "2026-04-18T10:05:00.000Z",
    "funded_at": "2026-04-18T10:05:00.000Z",
    "settled_at": null,
    "expires_at": "2026-04-25T10:00:00.000Z",
    "tx_hashes": {
      "create": "0x1a2b...",
      "fund": "0x3c4d...",
      "settle": null,
      "refund": null
    }
  },
  "blockchain": {
    "network": "testnet",
    "chain_id": 84532,
    "contract_address": "0xe1E4...0DB0",
    "onchain_escrow_id": 42,
    "onchain_status": "funded",
    "tx_hashes": { "create": "0x1a2b...", "fund": "0x3c4d...", "settle": null, "refund": null },
    "explorer": "https://sepolia.basescan.org/tx/0x3c4d..."
  },
  "events": [
    {
      "event_type": "created",
      "actor": "0xAlice",
      "details": {"amount": 500, "token": "USDC"},
      "created_at": "2026-04-18T10:00:00.000Z"
    },
    {
      "event_type": "funded",
      "actor": "0xAlice",
      "details": {"tx_hash": "0x3c4d...", "amount": 500},
      "created_at": "2026-04-18T10:05:00.000Z"
    }
  ]
}

Settle Escrow

curl -X POST https://clearpact.polsia.app/api/escrow/ESCROW_ID/settle \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cpk_live_YOUR_KEY" \
  -d '{
    "verifications": {
      "0": {"completed": true},
      "1": {"approved": true, "approver": "0xAlice"}
    },
    "actor": "0xOracle"
  }'

const res = await fetch(
  `https://clearpact.polsia.app/api/escrow/${escrowId}/settle`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": "cpk_live_YOUR_KEY"
    },
    body: JSON.stringify({
      verifications: {
        "0": { completed: true },
        "1": { approved: true, approver: "0xAlice" }
      },
      actor: "0xOracle"
    })
  }
);

const { settlement } = await res.json();
console.log("Settled:", settlement.amount, settlement.token);

res = requests.post(
    f"https://clearpact.polsia.app/api/escrow/{escrow_id}/settle",
    headers={"X-API-Key": "cpk_live_YOUR_KEY"},
    json={
        "verifications": {
            "0": {"completed": True},
            "1": {"approved": True, "approver": "0xAlice"}
        },
        "actor": "0xOracle"
    }
)
settlement = res.json()["settlement"]

{
  "success": true,
  "message": "Escrow settled. 500 USDC released to 0xBob",
  "escrow": { "status": "settled", /* ... */ },
  "settlement": {
    "amount": 500,
    "token": "USDC",
    "from": "0xAlice",
    "to": "0xBob",
    "conditions": [
      {"index": 0, "type": "task_completion", "met": true},
      {"index": 1, "type": "approval", "met": true}
    ],
    "settled_at": "2026-04-09T12:00:00.000Z"
  }
}

{
  "success": false,
  "message": "Not all conditions are met",
  "conditions": [
    {"index": 0, "type": "task_completion", "met": true},
    {"index": 1, "type": "approval", "met": false}
  ]
}

ERC-8004 Automatic Settlement

Phase 2 adds a validation adapter that automatically settles escrows when an ERC-8004-compatible proof is received. No human needs to call /settle.

Flow

POST /api/escrow
{
  "payer": "0xAlice",
  "payee": "0xBob",
  "amount": 100,
  "external_job_id": "job_abc123"
}
// Response includes erc8004: { external_job_id, status: "linked" }

POST /api/escrow/ESCROW_ID/fund
// status: pending_funding → funded

POST /api/validation/submit
{
  "external_job_id": "job_abc123",
  "proof_hash": "0x...",
  "result": "success"
}

GET /api/escrow/ESCROW_ID
// escrow.status: "settled"
// escrow.tx_hashes.settle: "0x..."

POST /api/validation/submit

Submit an ERC-8004-compatible validation signal. Triggers automatic settlement if result = "success" and the linked escrow is funded.

curl
curl -X POST https://clearpact.polsia.app/api/validation/submit \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cpk_live_YOUR_KEY" \
  -d '{
    "external_job_id": "job_abc123",
    "proof_hash": "0xabc...",
    "result": "success",
    "metadata": {"validator": "oracle-v1"}
  }'

RESPONSE (202 Accepted)

{
  "success": true,
  "message": "Validation received. Settlement will process automatically.",
  "record": {
    "id": "uuid...",
    "external_job_id": "job_abc123",
    "proof_hash": "0xabc...",
    "result": "success",
    "status": "pending",
    "escrow_id": "uuid..."
  }
}

GET /api/validation/:id

Check the processing status of a validation record.

curl
curl https://clearpact.polsia.app/api/validation/RECORD_ID \
  -H "X-API-Key: cpk_live_YOUR_KEY"

RECORD STATUS VALUES

Replay Protection

The adapter prevents double-settlement via two mechanisms:

1. Database constraint: UNIQUE(external_job_id, proof_hash) — submitting the same signal twice returns 409 Conflict.
2. Status check: Before calling settleEscrow(), the adapter checks the escrow is not already settled, cancelled, or expired. Already-settled escrows return status: "rejected" on the validation record.

x402 Protocol

ClearPact is a native x402 facilitator — compatible with Coinbase's open agentic payment protocol (35M+ transactions). x402 lets AI agents authorize USDC payments using EIP-712 typed-data signatures, with no gas wallet required on the payer side.

GET /api/x402/health

Check facilitator status. Returns the current chain config and feature flags. No API key required.

curl
curl https://clearpact.polsia.app/api/x402/health

RESPONSE (200)

{
  "status": "ok",
  "phase": "1B — verify + on-chain settlement",
  "networks": {
    "testnet": {
      "chain_id": 84532,
      "network": "base-sepolia",
      "usdc_contract": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "settle_enabled": true
    },
    "mainnet": {
      "chain_id": 8453,
      "network": "base",
      "usdc_contract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "settle_enabled": true
    }
  },
  "features": {
    "verify": true,
    "settle": true
  }
}

POST /api/x402/verify

curl -X POST https://clearpact.polsia.app/api/x402/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cpk_live_YOUR_KEY" \
  -d '{
    "from": "0xAgentWalletAddress",
    "to": "0xRecipientAddress",
    "value": "1000000",
    "validAfter": "0",
    "validBefore": "9999999999",
    "nonce": "0xabc123...32bytes",
    "signature": "0xsig..."
  }'

const res = await fetch("https://clearpact.polsia.app/api/x402/verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "cpk_live_YOUR_KEY"
  },
  body: JSON.stringify({
    from: "0xAgentWalletAddress",
    to: "0xRecipientAddress",
    value: "1000000",          // 1 USDC = 1_000_000 (6 decimals)
    validAfter: "0",
    validBefore: "9999999999",
    nonce: "0xabc123...32bytes",
    signature: "0xsig..."
  })
});

const { verified, transaction_id, escrow_id } = await res.json();

import requests

res = requests.post(
    "https://clearpact.polsia.app/api/x402/verify",
    headers={"X-API-Key": "cpk_live_YOUR_KEY"},
    json={
        "from": "0xAgentWalletAddress",
        "to": "0xRecipientAddress",
        "value": "1000000",  # 1 USDC
        "validAfter": "0",
        "validBefore": "9999999999",
        "nonce": "0xabc123...32bytes",
        "signature": "0xsig..."
    }
)
data = res.json()
transaction_id = data["transaction_id"]

{
  "success": true,
  "verified": true,
  "transaction_id": "uuid-of-x402-record",
  "recovered_address": "0xAgentWalletAddress",
  "escrow_id": "uuid-of-linked-escrow",   // null if no active escrow
  "amount_usdc": "1.000000"
}

{
  "success": false,
  "verified": false,
  "error": "invalid_signature",
  "message": "Recovered address does not match 'from'"
}

POST /api/x402/settle

# Mode A — settle a pre-verified transaction
curl -X POST https://clearpact.polsia.app/api/x402/settle \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cpk_live_YOUR_KEY" \
  -d '{"transaction_id": "uuid-from-verify-response"}'

# Mode B — verify + settle in one call
curl -X POST https://clearpact.polsia.app/api/x402/settle \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cpk_live_YOUR_KEY" \
  -d '{
    "from": "0xAgentWalletAddress",
    "to": "0xRecipientAddress",
    "value": "1000000",
    "validAfter": "0",
    "validBefore": "9999999999",
    "nonce": "0xabc123...32bytes",
    "signature": "0xsig..."
  }'

// Mode A — settle pre-verified tx
const res = await fetch("https://clearpact.polsia.app/api/x402/settle", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "cpk_live_YOUR_KEY"
  },
  body: JSON.stringify({ transaction_id: "uuid-from-verify" })
});

const { settlement_tx_hash, block_number, escrow_id } = await res.json();

# Mode A — settle pre-verified tx
res = requests.post(
    "https://clearpact.polsia.app/api/x402/settle",
    headers={"X-API-Key": "cpk_live_YOUR_KEY"},
    json={"transaction_id": "uuid-from-verify"}
)
data = res.json()
tx_hash = data["settlement_tx_hash"]
block   = data["block_number"]

{
  "success": true,
  "settlement_tx_hash": "0xabc123...on-chain tx",
  "block_number": 19842301,
  "amount_usdc": "1.000000",
  "escrow_id": "uuid-of-funded-escrow",   // null if no linked escrow
  "escrow_status": "funded"
}

Contract Addresses

ClearPact deploys escrow contracts independently per network. Use the correct contract address for explorer links and direct on-chain interaction.

Base Sepolia — Testnet (Phase 4 v2)

Base — Mainnet

Condition Types

Conditions define what must be true before funds are released. Each escrow can have multiple conditions — all must be met for settlement.

Error Codes

All errors return JSON with success: false and a descriptive error code.

ERROR RESPONSE FORMAT

{
  "success": false,
  "error": "missing_api_key",
  "message": "API key required. Pass your key in the X-API-Key header.",
  "docs": "https://clearpact.polsia.app/docs#authentication"
}

Escrow Status Values

Every escrow has a status field that reflects its position in the lifecycle. Build your integration to handle all statuses — webhook payloads will deliver any of these values.

LIFECYCLE (NON-TERMINAL)

TERMINAL STATES

TYPICAL LIFECYCLE

  Happy path:
  pending_funding → funded → settled

  With ERC-8004 verification:
  pending_funding → funded → awaiting_verification → settled

  Cancellation (unfunded):
  pending_funding → cancelled

  Cancellation (funded — triggers on-chain refund):
  funded → refunded

  Expiry (auto-refund):
  funded → expired
  pending_funding → expired

  Expiry failure (on-chain refund failed):
  funded → expiry_failed

Job Status Mapping (v2 ERC-8183)

ClearPact v2 uses the ERC-8183 JobStatus enum — exactly 6 values. The v1 escrow API (drainage period) is mapped below for consumers migrating from legacy routes.

v2 JobStatus (ERC-8183) — 6 values

v1 → v2 Status Mapping (migration reference)

ERC-8183 State Machine

Immutability Commitment

At Phase 4 deploy (May 2026), ClearPact executed a 5-renounce sequence across both proxy contracts — permanently removing all administrative control. This is verifiable on-chain.

5-Renounce Sequence (Phase 4)

Self-Service Evaluator Pattern (Decision 9)

Each job creator specifies their own evaluator EOA at createJob(). ClearPact does not appoint or arbitrate evaluators. The evaluator EOA calls complete() or reject() directly via the Job API — the Evaluator contract is not required.

// Self-service: job creator picks their evaluator at creation
const { job } = await client.jobs.create(
  '0xProviderWallet',
  '0xEvaluatorEOA',   // YOUR evaluator — could be a DAO, a multisig, or yourself
  '2026-06-01T00:00:00Z',
  'Build and deploy landing page'
);

// Evaluator calls complete() directly (no Evaluator contract needed)
await client.jobs.complete(job.id, 'Work accepted — link verified');

Competitor Comparison

Migration v1 → v2

The 7-day drainage period (v1 routes remain active) gives existing consumers time to migrate. After drainage, v1 routes are sunset.

Route Changes

Webhook Event Changes

SDK Changes

SDK v0.3.0 (breaking in types, non-breaking in runtime during drainage):

• client.jobs — new namespace with 8 lifecycle methods + 1 view
• client.escrow — deprecated alias (warns on construction), removed in v0.4.0
• JobStatus — exactly 6 values: Open|Funded|Submitted|Completed|Rejected|Expired
• Job type — 9 ERC-8183 fields (replaces EscrowObject)
• ClearPact.contracts — static property with deployed addresses

How ClearPact Extends ERC-8183

Hooks (IACPHook)

Jobs can optionally specify a hook contract at createJob(). The hook receives beforeAction() / afterAction() callbacks on lifecycle transitions. Hooks must implement IERC165 and be whitelisted. Gas cap: 100k per hook call. claimRefund() is non-hookable — the unconditional refund guarantee cannot be blocked by a hook.

Per-Job Payment Tokens

By default, jobs use the global USDC address set at contract initialization (0x036CbD53842c5426634e7929541eC2318f3dCF7e on Base Sepolia). Callers can override the token per-job at setBudget() time by passing token. Emits job.tokenSet webhook event.

Conditional Reference Hash (conditionRef)

Pass conditionRef at setBudget() to attach a bytes32 conditional reference hash (e.g. IPFS CID of the conditions document). Emits ClearPactJobMetadata event (mapped to job.metadata webhook). This event is also emitted at createJob() with conditionRef=0 (Phase 2bis Fix #1).

Symmetric Refund on Reject (E3)

reject() implements a 3-path ACL: callable from Open, Funded, or Submitted state. When called from Funded or Submitted, it automatically returns funds to the client — no separate claimRefund() required. This is the symmetric refund guarantee (Phase 2bis Fix #3).

Webhooks

Receive real-time notifications when escrow events occur. Register a URL, choose which events to subscribe to, and ClearPact will POST signed JSON payloads to your endpoint.

Register Webhook

curl -X POST https://clearpact.polsia.app/api/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cpk_live_YOUR_KEY" \
  -d '{
    "url": "https://your-app.com/webhooks/clearpact",
    "events": [
      "escrow.created",
      "escrow.funded",
      "escrow.settled",
      "escrow.cancelled",
      "escrow.expired"
    ]
  }'

const res = await fetch("https://clearpact.polsia.app/api/webhooks", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "cpk_live_YOUR_KEY"
  },
  body: JSON.stringify({
    url: "https://your-app.com/webhooks/clearpact",
    events: [
      "escrow.created",
      "escrow.funded",
      "escrow.settled",
      "escrow.cancelled",
      "escrow.expired"
    ]
  })
});
const { signing_secret } = await res.json();
// Store signing_secret securely — shown only once

res = requests.post(
    "https://clearpact.polsia.app/api/webhooks",
    headers={"X-API-Key": "cpk_live_YOUR_KEY"},
    json={
        "url": "https://your-app.com/webhooks/clearpact",
        "events": [
            "escrow.created",
            "escrow.funded",
            "escrow.settled",
            "escrow.cancelled",
            "escrow.expired"
        ]
    }
)
data = res.json()
signing_secret = data["signing_secret"]

{
  "success": true,
  "webhook": {
    "id": "wh_550e8400-e29b-41d4-a716-446655440000",
    "url": "https://your-app.com/webhooks/clearpact",
    "events": ["escrow.created", "escrow.funded", "escrow.settled", "escrow.cancelled", "escrow.expired"],
    "created_at": "2026-04-18T10:00:00.000Z"
  },
  "signing_secret": "whsec_abc123...shown_only_once"
}

List Webhooks

curl
curl https://clearpact.polsia.app/api/webhooks \
  -H "X-API-Key: cpk_live_YOUR_KEY"

{
  "success": true,
  "webhooks": [
    {
      "id": "wh_550e8400-e29b-41d4-a716-446655440000",
      "url": "https://your-app.com/webhooks/clearpact",
      "events": ["escrow.created", "escrow.funded", "escrow.settled", "escrow.cancelled", "escrow.expired"],
      "created_at": "2026-04-18T10:00:00.000Z"
    }
  ]
}

Delete Webhook

curl
curl -X DELETE https://clearpact.polsia.app/api/webhooks/WEBHOOK_ID \
  -H "X-API-Key: cpk_live_YOUR_KEY"

{
  "success": true,
  "message": "Webhook deleted"
}

GET /api/webhooks/:id/deliveries

curl "https://clearpact.polsia.app/api/webhooks/WEBHOOK_UUID/deliveries?status=failed&limit=20" \
  -H "X-API-Key: cpk_live_YOUR_KEY"

const res = await fetch(
  "https://clearpact.polsia.app/api/webhooks/WEBHOOK_UUID/deliveries?status=failed",
  { headers: { "X-API-Key": "cpk_live_YOUR_KEY" } }
);
const { data, next_cursor } = await res.json();

// SDK equivalent:
const { data, next_cursor } = await client.webhooks.deliveries("WEBHOOK_UUID", {
  status: "failed", event_type: "escrow.funded"
});

import requests

res = requests.get(
    "https://clearpact.polsia.app/api/webhooks/WEBHOOK_UUID/deliveries",
    headers={"X-API-Key": "cpk_live_YOUR_KEY"},
    params={"status": "failed", "limit": 20}
)
data = res.json()

{
  "data": [
    {
      "delivery_id": "whd_550e8400-...",
      "event_id": "evt_a1b2c3d4-...",
      "event_type": "escrow.funded",
      "attempt_number": 2,
      "response_status": 200,
      "response_body_preview": "{\"ok\":true}",
      "duration_ms": null,
      "attempted_at": "2026-05-05T09:11:25Z",
      "next_attempt_at": null,
      "final_status": "delivered"
    }
  ],
  "next_cursor": null
}

Webhook Events

19 event types are available (12 v2 job events + 7 v1 escrow events during drainage). Subscribe to any combination when registering a webhook.

Payload Format

Every webhook delivery is an HTTP POST with a JSON body. The envelope is consistent across all event types:

{
  "id": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "escrow.created",
  "created_at": "2026-04-18T10:00:00.000Z",
  "data": { /* escrow object — same shape as GET /api/escrow/:id */ }
}

EXAMPLE: escrow.created

{
  "id": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "escrow.created",
  "created_at": "2026-04-18T10:00:00.000Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending",
    "payer": "0xAlice",
    "payee": "0xBob",
    "amount": 500,
    "token": "USDC",
    "network": "testnet",
    "conditions": [{"type": "task_completion"}],
    "created_at": "2026-04-18T10:00:00.000Z"
  }
}

EXAMPLE: escrow.funded

{
  "id": "evt_b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "type": "escrow.funded",
  "created_at": "2026-04-18T10:05:00.000Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "funded",
    "payer": "0xAlice",
    "payee": "0xBob",
    "amount": 500,
    "token": "USDC",
    "network": "testnet",
    "funded_at": "2026-04-18T10:05:00.000Z",
    "tx_hashes": {"fund": "0xabc123..."},
    "created_at": "2026-04-18T10:00:00.000Z"
  }
}

EXAMPLE: escrow.settled

{
  "id": "evt_c3d4e5f6-a7b8-9012-cdef-123456789012",
  "type": "escrow.settled",
  "created_at": "2026-04-18T10:10:00.000Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "settled",
    "payer": "0xAlice",
    "payee": "0xBob",
    "amount": 500,
    "token": "USDC",
    "network": "testnet",
    "settled_at": "2026-04-18T10:10:00.000Z",
    "tx_hashes": {"fund": "0xabc123...", "settle": "0xdef456..."},
    "created_at": "2026-04-18T10:00:00.000Z"
  }
}

EXAMPLE: escrow.cancelled

{
  "id": "evt_d4e5f6a7-b8c9-0123-defa-234567890123",
  "type": "escrow.cancelled",
  "created_at": "2026-04-18T10:15:00.000Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "cancelled",
    "payer": "0xAlice",
    "payee": "0xBob",
    "amount": 500,
    "token": "USDC",
    "network": "testnet",
    "cancelled_at": "2026-04-18T10:15:00.000Z",
    "created_at": "2026-04-18T10:00:00.000Z"
  }
}

EXAMPLE: escrow.expired

{
  "id": "evt_e5f6a7b8-c9d0-1234-efab-345678901234",
  "type": "escrow.expired",
  "created_at": "2026-04-18T12:00:00.000Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "expired",
    "payer": "0xAlice",
    "payee": "0xBob",
    "amount": 500,
    "token": "USDC",
    "network": "testnet",
    "expires_at": "2026-04-18T12:00:00.000Z",
    "tx_hashes": {"refund": "0x789abc..."},
    "created_at": "2026-04-18T10:00:00.000Z"
  }
}

Signature Verification

Every webhook payload includes an X-ClearPact-Signature header containing an HMAC-SHA256 hex digest of the raw request body. Always verify this before processing.

// Node.js verification example
const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret)
      .update(body, 'utf8')
      .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your Express handler:
app.post('/webhooks/clearpact', (req, res) => {
  const sig = req.headers['x-clearpact-signature'];
  if (!verifyWebhook(JSON.stringify(req.body), sig, SIGNING_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  // Process the event
  console.log(req.body.type, req.body.data.id);
  res.status(200).json({ received: true });
});

JavaScript / TypeScript SDK

The official ClearPact SDK wraps the REST API in a clean, fully-typed client. Zero dependencies — uses native fetch.

Install

npm install clearpact

<script src="https://clearpact.polsia.app/sdk"></script>
<!-- Exposes window.ClearPact and window.ClearPactError globally -->

Quick Start

const { ClearPact } = require('clearpact');

const client = new ClearPact({
  apiKey:  'cpk_live_...',
  network: 'testnet',       // 'testnet' | 'mainnet'
});

// Create an escrow
const { escrow } = await client.escrow.create({
  payer:  '0xPayerWallet',
  payee:  '0xPayeeWallet',
  amount: 100,              // USDC
  conditions: [{ type: 'task_completion' }],
});

console.log(escrow.id, escrow.status);
// "3f2ac1d0-..." "pending_funding"

// Fund it
await client.escrow.fund(escrow.id, { tx_hash: '0x...' });

// Settle
await client.escrow.settle(escrow.id, {
  verifications: { task_completion: { completed: true } },
});

import { ClearPact } from 'clearpact';

const client = new ClearPact({ apiKey: 'cpk_live_...' });

const { escrow } = await client.escrow.create({
  payer:  '0xPayerWallet',
  payee:  '0xPayeeWallet',
  amount: 50,
});

import { ClearPact, ClearPactError } from 'clearpact';
import type { EscrowObject } from 'clearpact/types';

const client = new ClearPact({ apiKey: 'cpk_live_...' });

try {
  const { escrow }: { escrow: EscrowObject } =
    await client.escrow.create({
      payer:  '0xPayerWallet',
      payee:  '0xPayeeWallet',
      amount: 100,
    });
  console.log(escrow.id);
} catch (err) {
  if (err instanceof ClearPactError) {
    console.error(err.status, err.message);
  }
}

Escrow Methods

// ERC-8004 auto-settlement — link escrow to an external job
const { escrow } = await client.escrow.create({
  payer:           '0xPayer',
  payee:           '0xPayee',
  amount:          500,
  external_job_id: 'job_abc123',   // POST /api/validation/submit triggers auto-settle
  conditions: [{ type: 'task_completion' }],
});

x402 Methods

Webhooks

// Register a webhook
const { signing_secret } = await client.webhooks.create({
  url:         'https://your-app.com/webhooks/clearpact',
  event_types: ['escrow.created', 'escrow.funded', 'escrow.settled', 'escrow.cancelled', 'escrow.expired'],
});
// Store signing_secret — shown only once. Verify X-ClearPact-Signature on incoming events.

// List webhooks
const { webhooks } = await client.webhooks.list();

// Inspect delivery history (debug failed deliveries)
const { data } = await client.webhooks.deliveries(webhooks[0].id, {
  status:     'failed',
  event_type: 'escrow.funded',
  limit:      20,
});
console.log(data[0].response_body_preview);

// Remove a webhook
await client.webhooks.delete(webhookId);

Keys / Observability

// Inspect your own API usage (last 7 days)
const { data, summary } = await client.keys.usage('cp_YOUR_KEY_ID', {
  from:   '2026-05-01T00:00:00Z',
  status: '4xx',
  limit:  100,
});
console.log(`${summary.count} total requests`);
console.log('By status:', summary.by_status_class);
// { '2xx': 143, '4xx': 7 }

// Paginate with cursor
let cursor = null;
do {
  const page = await client.keys.usage('cp_YOUR_KEY_ID', { cursor, limit: 100 });
  for (const req of page.data) {
    console.log(req.path, req.status_code, req.latency_ms + 'ms');
  }
  cursor = page.next_cursor;
} while (cursor);

Error Handling

All API errors throw a ClearPactError with a typed shape:

import { ClearPact, ClearPactError } from 'clearpact';

try {
  await client.escrow.get('not-a-real-id');
} catch (err) {
  if (err instanceof ClearPactError) {
    err.status;   // 400
    err.message;  // "Invalid escrow ID format"
    err.error;    // machine-readable code (if present)
    err.errors;   // array of validation messages (if present)
    err.raw;      // full response body
  }
}

Changelog

Major milestones shipped, newest first.