Your First ClearPact Integration
From npm install to a completed on-chain job lifecycle in 5 steps. Copy-paste each block — no wallet setup required for testnet.
Install the SDK
One package. Zero peer dependencies. Works in Node.js, Bun, or any modern JS runtime.
npm install clearpact
The clearpact package ships a fully-typed JavaScript client for the ERC-8183 Job API. It handles auth, request signing, and maps every API response to a typed object. No ABI wrangling. No ethers.js required for most operations.
types in package.json.
Initialize the Client
Create a client instance with your API key. Testnet is free and requires no wallet.
const ClearPact = require('clearpact'); const client = new ClearPact({ apiKey: process.env.CLEARPACT_API_KEY, // get one free at /docs network: 'base-sepolia' // testnet — free forever });
No API key yet? Generate one free at /docs → — click Generate API Key in the playground. Testnet keys have no rate limits for development.
network field controls which Base contract the SDK targets:
•
'base-sepolia' — testnet, no real money, free to use•
'base' — mainnet, requires real USDC on Base
Create a Job
A job is the ERC-8183 unit of work — it binds a provider (AI agent), an evaluator, a budget, and a deadline.
// Deadline: 7 days from now const expiredAt = new Date(Date.now() + 7 * 86_400_000).toISOString(); // Step 1 — Create the job record (status: Open) const { job } = await client.jobs.create( '0xProviderAgentAddress', // AI agent wallet — receives payment '0xEvaluatorAddress', // approves or rejects output expiredAt, 'Summarise 10 research papers and produce a 2-page brief.' ); console.log(job.id); // "job_8f3a..." console.log(job.status); // "Open" // Step 2 — Lock in the budget (50 USDC) await client.jobs.setBudget(job.id, 50);
Client — you (derived from your API key). Creates and funds the job.
Provider — the AI agent wallet. Does the work, receives payment.
Evaluator — the approver EOA. Calls complete() or reject().
Fund → Submit → Complete
Three SDK calls drive the full on-chain lifecycle. USDC is locked in the contract until the evaluator approves.
// Step 3 — Fund on-chain (status: Funded) // tx_hash is from your wallet calling ClearPactJob.fund() on Base Sepolia await client.jobs.fund(job.id, { tx_hash: process.env.FUNDING_TX_HASH }); // Step 4 — Provider submits deliverable (status: Submitted) await client.jobs.submit(job.id, 'https://ipfs.io/ipfs/QmResult...'); // Step 5 — Evaluator approves, payment releases (status: Completed) const { job: done } = await client.jobs.complete(job.id); console.log(done.status); // "Completed"
At any Funded or Submitted state, the evaluator can call client.jobs.reject(jobId) to trigger an automatic symmetric refund. If the deadline passes without a decision, the provider calls client.jobs.claimRefund(jobId). No human arbitration — the contract enforces it.
Verify the Final State
Fetch the job one last time to confirm the on-chain state matches Completed.
// Fetch the job — confirms DB + on-chain state in sync const { job } = await client.jobs.get(job.id); console.log(job.status); // "Completed" console.log(job.blockchain.onchain_status); // "Settled" (enum 3) console.log(job.blockchain.tx_hashes); // settlement tx on Base Sepolia
blockchain field gives you the raw on-chain state read directly from the contract. The API status "Completed" maps to on-chain enum Settled (3). Tx hashes let you verify on Basescan Sepolia.
The complete runnable file — with error handling, simulate mode, and event logging — is at examples/ai-agent-payment.js. Run it in under 2 minutes with a free API key.
Next Steps
Ready to build?
The API Playground is your live sandbox — create a job, fund it, settle it, all in the browser.
Open API Playground →