Quickstart Guide
Two paths to your first result. The demo path requires no API keys and runs in under 5 minutes. The SDK path connects to your own data sources.
What Settler does: It matches records across your data sources, surfaces every variance with context, and writes a hash-linked evidence artifact you can replay and share. It does not make decisions — your team reviews the results.
Path A — Run the Demo (No API Key Needed)
Runs a Stripe↔QuickBooks reconciliation using fixture data. Generates evidence you can inspect and replay.
Clone and Install
No database or API keys required for the demo path.
git clone https://github.com/Hardonian/Settler.git
cd Settler
pnpm installCopy Environment File
For the demo, DATABASE_URL is not required. Leave it blank.
cp .env.example .env
# DATABASE_URL is not needed for pnpm demoRun the Demo
Executes a Stripe↔QuickBooks reconciliation using fixture data. Writes four output files to examples/demo-output/.
pnpm demo
# Expected output:
# ✓ Workflow executed deterministically
# ✓ evidence.json written
# ✓ results.json written
# ✓ report.html writtenInspect Results and Evidence
The evidence file contains the full hash-linked audit artifact. Open report.html to browse mismatches visually.
# Summary: matched, unmatched, and variance counts
cat examples/demo-output/results.json
# Hash-linked audit artifact for this run
cat examples/demo-output/evidence.json
# Open in browser for a visual mismatch report
open examples/demo-output/report.htmlReplay Verification
Re-runs the reconciliation from stored artifacts and verifies the output hash matches the original. Confirms determinism.
pnpm settler:replay examples/demo-output/evidence.json
# Expected output:
# ✓ Replay complete — hash match confirmedPath B — Connect Your Own Data (SDK)
Connect your own Stripe, Shopify, QuickBooks, or custom data sources using the TypeScript SDK.
Install the SDK
TypeScript and Python SDKs are available.
npm install @settler/sdkCreate a Reconciliation Job
Connect your data sources and define matching rules in code. Rules are version-controlled and testable.
import { SettlerClient } from '@settler/sdk';
const client = new SettlerClient({
apiKey: process.env.SETTLER_API_KEY,
});
const job = await client.jobs.create({
name: "Stripe → Shopify Reconciliation",
source: {
adapter: "stripe",
config: { apiKey: process.env.STRIPE_SECRET_KEY },
},
target: {
adapter: "shopify",
config: { apiKey: process.env.SHOPIFY_API_KEY },
},
rules: {
matching: [
{ field: "order_id", type: "exact" },
{ field: "amount", type: "exact", tolerance: 0.01 },
],
},
});
console.log("Job created:", job.id);Run and Review Results
Execute the job and inspect the mismatch report. Every run produces a verifiable evidence artifact.
const report = await client.reports.get(job.id);
console.log("Matched:", report.summary.matched);
console.log("Unmatched:", report.summary.unmatched);
// Each mismatch includes: field, expected, actual, rule applied, evidence hash
const mismatches = await client.reconciliations.getMismatches(job.id);