Developers

This is the landing page for anyone building on, integrating with, or verifying the zkde.fi proof system. Whether you're piping API endpoints into your own product, verifying proofs independently on-chain, or running the full stack locally — start here.

The fast version

What you want	Where to go
See every claim verified live	zkde.fi/test — the live backend showcase
Read the source	github.com/obsqra-labs/zkdefi
Hit the API	API Reference — every endpoint, auth model, caveats
Understand proof flow	Proof Pipeline — lanes, verifiers, settlement
Look up contract addresses	Contracts — deployed on Starknet mainnet, Starknet Sepolia, Ethereum Sepolia, Madara L3
Connect over WebSocket	WebSocket Events — push-based real-time updates

System shape

The architecture is simpler than it looks from the outside. There's a Next.js frontend, a FastAPI backend that does most of the heavy lifting, and two downstream services for proving and settlement:

flowchart LR
  UI["Next.js frontend<br/><i>:3001</i>"] --> API["FastAPI backend<br/><i>:8003</i>"]
  API --> SN["Starknet L2<br/><i>contract settlement</i>"]
  API --> PX["Proof services<br/><i>EZKL, Stone, Garaga</i>"]
  API --> OBS["obsqra backend<br/><i>:8002 — aggregation</i>"]
  OBS --> MAD["Madara L3<br/><i>:9944 — fact registry</i>"]
  SN --> UI
  MAD --> UI

The frontend never talks to proof services directly. Everything routes through the FastAPI backend, which orchestrates proof generation, policy checks, calldata building, and receipt lifecycle. The obsqra backend handles proof aggregation and bridges facts to the Madara L3 appchain.

Three integration patterns

1. Product integration (deep-linking)

If you want to send users into specific app surfaces, use the route-state conventions:

/agent?v=vault     → Capital OS: vault view
/agent?v=oracle    → Capital OS: oracle view
/agent?v=brain     → Capital OS: brain view
/profile?tab=trust → Profile: trust posture tab
/trade             → Trade Desk

These are stable routes. The query parameters control which view loads.

2. Backend integration (API calls)

Call the API directly for programmatic access. The auth model is straightforward:

• Public/read endpoints: no header required
• User-protected mutations: include X-Wallet-Address header with the caller's Starknet address
• Admin operations: include X-Admin-Key header

Not every mutation endpoint has wallet-header protection wired today — auth enforcement varies per endpoint. Check the API Reference for per-route details.

3. Proof verification (on-chain)

You can verify proofs independently without touching the API at all. Every proof that settles on-chain goes through one of the deployed verifier contracts:

Verifier	What it checks
GaragaVerifier	Groth16 (SNARK) pairing checks in Cairo
SolvencyProofVerifier	Can-this-wallet-cover-its-liabilities
RiskPassportTierVerifier	Risk tier attestation
TraderPerformanceVerifier	Historical trading performance
StrategyIntegrityVerifier	Strategy constraint compliance
ExecutionIntegrityVerifier	Execution fairness

Full addresses: Contracts. Verification artifacts: zkde.fi/test.

Stable fixtures

These endpoints are safe to pin against — they won't change path or contract without a major version bump:

GET  /api/v1/zkdefi/session_keys/list/{owner_address}
POST /api/v1/zkdefi/auth/session/start
POST /api/v1/zkdefi/lending/proof/credit-eligibility
POST /api/v1/zkdefi/zkml/scan
GET  /api/v1/zkdefi/reputation/user/{address}
GET  /api/v1/zkdefi/risk_passport/user/{address}

Experimental routes that are still evolving:

/api/v1/phase4a/*        — phase 4a orchestration (dashboard, stats)
/api/v1/vault-live/*     — live vault execution paths
/api/v1/zkdefi/sim/*     — simulation sandbox

Treat experimental routes as version-sensitive. Monitor release notes before depending on their response shapes.

Local development

git clone https://github.com/obsqra-labs/zkdefi
cd zkdefi

Key reference docs inside the repo:

File	What it covers
docs/SETUP.md	Local development setup — dependencies, process startup
docs/ENV.md	Environment variables — what each one controls
docs/ARCHITECTURE.md	Internal architecture — service boundaries, data flow
docs/AGENT_FLOW.md	Agent execution flow — how actions move through the pipeline

The system runs via PM2. Start everything with pm2 start ecosystem.config.js, then verify with pm2 status. The frontend is on :3001, backend on :8003, and the docs build from docs-site/ into frontend/public/docs/.