Quickstart

1. Install

npm install @0xclearinghouse/core

Requires Node 22+. The published 0.0.1 is a name reservation; 0.1.0 carries the ledger and executor.

2. Pick a chain

Native USDC only — bridged variants are deliberately not supported, because settling into the wrong token is a fund-loss bug, not a configuration detail.

3. Configure

# .env — never commit this file
AGENT_WALLET_KEY=0x...              # paying wallet: USDC + small ETH gas reserve
CLEARINGHOUSE_CHAIN=base           # base | arbitrum | optimism
PROTOCOL_TREASURY_ADDRESS=0x...    # receives the 0.5% fee
SETTLE_THRESHOLD_USDC=1.00         # settle when debt crosses this
SETTLE_INTERVAL_HOURS=12           # ...or when the oldest charge is this old
LEDGER_DRIVER=sqlite               # no external database needed

4. Charge and settle

import { Clearinghouse, CHAINS, ONE_USDC } from "@0xclearinghouse/core";

const ch = new Clearinghouse({ chain: "base", threshold: ONE_USDC });

// record usage: local, instant, zero gas
ch.charge({ payer: consumer, payee: provider, amount: 250_000n });
ch.charge({ payer: consumer, payee: provider, amount: 750_000n });

// 1.00 USDC reached — one transfer, fee split out
await ch.settle();

Amounts are micro-USDC (bigint), never floats. CHAINS.base.usdc holds the token address if you need it directly.

5. Go live carefully

createExecutor() defaults to dryRun: true: it plans and verifies but broadcasts nothing, and returns settled: [] so tabs are never cleared for money that did not move. Turn it off only after a dry run produces the plan you expect.

Known gap before production: a crash between broadcast and confirmation can double-pay. Persisted settlement intents are not implemented yet — do not run dryRun: false unattended money until they are.

Machine-readable

Agents can skip this page: protocol.json has chains, addresses, defaults, and environment variables; llms.txt is the condensed version. Deeper design notes live in docs/.