ClearPact SDK

Lightweight JavaScript/TypeScript client for the ClearPact ERC-8183 escrow API. Source on GitHub.

• Zero dependencies — uses native fetch (Node 18+ / modern browsers)
• Full TypeScript types for autocomplete and type safety
• Testnet by default — safe for development, flip network: 'mainnet' when ready

v1 deprecation notice: client.escrow is a deprecated alias kept for 7-day drainage compatibility (sunset 2026-05-23, removed in v0.4.0). Migrate to client.jobs — see migration guide.

Install

npm install clearpact

Or use the browser CDN build:

<script src="https://clearpact.polsia.app/sdk"></script>

Quick Start

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

const client = new ClearPact({
  apiKey: 'cpk_live_...',   // from https://clearpact.polsia.app/docs
});

// Create an ERC-8183 job
const { job } = await client.jobs.create(
  '0xProviderWalletAddress',
  '0xEvaluatorEOA',           // self-service evaluator — your wallet or a trusted EOA
  new Date(Date.now() + 7 * 86400_000).toISOString(),  // expiredAt (ISO 8601, 7 days)
  'Build landing page in Tailwind'                       // description
);

console.log(job.id, job.status);
// → "3f2ac1d0-..." "Open"

// Set the budget (USDC by default)
await client.jobs.setBudget(job.id, 100);

// Fund the job on-chain (record the tx hash)
await client.jobs.fund(job.id, { tx_hash: '0x...' });

// Provider submits the deliverable
await client.jobs.submit(job.id, 'https://deliverable.url/output');

// Evaluator (or client) approves and releases payment
await client.jobs.complete(job.id, 'Work accepted');

ESM

import { ClearPact } from 'clearpact';

TypeScript

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

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

try {
  const { job } = await client.jobs.create(
    '0xProvider',
    '0xEvaluatorEOA',
    new Date(Date.now() + 7 * 86400_000).toISOString(),
    'Write smart contract audit'
  );
} catch (err) {
  if (err instanceof ClearPactError) {
    console.error(err.status, err.message);
  }
}

API Reference

new ClearPact(options)

| Option | Type | Default | Description | |-----------|-----------|----------------------------------|--------------------------------| | apiKey | string | required | Your ClearPact API key | | network | string | 'testnet' | 'testnet' or 'mainnet' | | baseUrl | string | https://clearpact.polsia.app | Override API base URL |

client.jobs — ERC-8183 v2 (current)

| Method | Description | |---------------------------------|---------------------------------------------------------------| | create(provider, evaluator, expiredAt, description?, hook?) | Create a new job (ERC-8183 createJob) | | setProvider(jobId, provider) | Update provider address (Open state only) | | setBudget(jobId, amount, opts?) | Set budget + optional token / conditionRef | | fund(jobId, opts?) | Record on-chain funding event (Open → Funded) | | submit(jobId, deliverable, opts?) | Submit deliverable (Funded → Submitted) | | complete(jobId, reason, opts?) | Approve and release payment (Submitted → Completed) | | reject(jobId, reason, opts?) | Reject with automatic refund (E3 3-path ACL) | | claimRefund(jobId) | Claim expiry refund (Funded/Submitted, after expiredAt) | | get(jobId) | Get job state + event log | | list(filters?) | List jobs by status, with pagination |

create params

client.jobs.create(
  provider: string,      // Provider wallet address
  evaluator: string,     // Self-service evaluator EOA (chosen by job creator)
  expiredAt: string,     // ISO 8601 expiry datetime
  description?: string,  // Job description
  hook?: string          // IACPHook contract address (optional, must be whitelisted)
)

setBudget opts

{
  token?:        string;  // ERC-20 token address (default: USDC)
  conditionRef?: string;  // bytes32 conditional reference hash (Phase 2bis)
}

JobStatus values

| Status | Meaning | |-------------|--------------------------------------| | Open | Job created, awaiting funding | | Funded | Budget deposited on-chain | | Submitted | Provider submitted deliverable | | Completed | Evaluator/client approved, paid out | | Rejected | Rejected, symmetric refund issued | | Expired | Expired, refund claimable |

client.x402

| Method | Description | |-----------------------------|--------------------------------------| | verify(payload, options?) | Verify an x402 payment authorization | | settle(params?) | Settle a verified x402 payment | | health() | Facilitator health + config | | listTransactions(filters?)| List x402 transaction records | | getTransaction(id) | Get single x402 transaction |

client.webhooks

| Method | Description | |------------------|---------------------------------| | create(params) | Register a webhook endpoint | | list() | List registered webhooks | | delete(id) | Remove a webhook | | deliveries(webhookId, opts?) | List webhook delivery attempts |

Webhook payload envelope:

{
  "id": "uuid",
  "type": "job.completed",
  "created_at": "2025-01-01T00:00:00.000Z",
  "data": { ...job }
}

Verify payloads using the X-ClearPact-Signature: sha256=<hex> header (HMAC-SHA256).

Error handling

All errors throw a ClearPactError:

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

try {
  await client.jobs.get('bad-id');
} catch (err) {
  if (err instanceof ClearPactError) {
    console.error(err.status);  // 400
    console.error(err.message); // "Invalid job ID format"
    console.error(err.raw);     // Full response body
  }
}

client.escrow — deprecated (v1)

Deprecated. Preserved for 7-day drainage compatibility. Sunset 2026-05-23 — removed in v0.4.0. Migrate to client.jobs — see the migration guide.

| Method | v2 equivalent | |-------------------|----------------------------| | create(params) | client.jobs.create(...) | | get(id) | client.jobs.get(id) | | fund(id, params?) | client.jobs.fund(id, params?) | | settle(id, params?) | client.jobs.complete(id, reason) | | cancel(id, params?) | client.jobs.reject(id, reason) |

License

MIT — © ClearPact