API Reference

This is the complete endpoint map for the zkde.fi backend. Every route listed here is live and exercised by the backend showcase. The API is the programmatic surface of the proof pipeline — it exposes read endpoints, preparation/build routes, proof-generation routes, and a smaller set of execution paths.

One thing to understand upfront: most mutation endpoints don't execute on-chain directly. They prepare — building calldata, generating proofs, composing execution context — and then the frontend (or your integration) takes that prepared data and submits it through a wallet signature. This is by design. The system separates preparation from execution so that the user always has final signing authority.

Base URLs

Environment	URL
App	https://zkde.fi
Core API	https://zkde.fi/api/v1
zkdefi namespace	https://zkde.fi/api/v1/zkdefi/{resource}

Authentication

flowchart LR
  C["Your request"] --> R{What kind of endpoint?}
  R -->|"Public / read"| P["No header needed"]
  R -->|"User mutation"| W["X-Wallet-Address: 0x..."]
  R -->|"Admin operation"| A["X-Admin-Key: secret"]

Three auth tiers, applied per-endpoint:

• Public: no header. All GET endpoints and some informational POST routes.
• Wallet-protected: X-Wallet-Address header must match the target address. The server checks that the caller is operating on their own data.
• Admin-only: X-Admin-Key header. Used for destructive operations (merkle reset, policy reset, fleet management).

Important: not every POST/PUT endpoint has wallet-header protection wired via dependency injection today. Auth enforcement is endpoint-specific — verify per-route below, and follow release notes for changes.

---

Health & metadata

The basics. If /health doesn't respond, nothing else will either.

Method	Path	Purpose	Auth
GET	/health	Service liveness	Public
GET	/api/v1/phase4a/contracts	Contract address metadata	Public

---

Identity, reputation & compliance

This is the trust layer — reputation tiers, FICO-pack proofs, risk passports, compliance profiles, and linked-address management. If you're building anything that needs to know "how trusted is this wallet?", these are your endpoints.

For the full explanation of how reputation scoring works, see Reputation & Scoring. For the composed passport object, see Risk Passport.

Method	Path	Purpose	Auth
GET	/api/v1/zkdefi/reputation/tiers	Tier definitions (thresholds and labels)	Public
GET	/api/v1/zkdefi/reputation/user/{address}	User reputation snapshot — tier, score, history	Public
GET	/api/v1/zkdefi/reputation/proofs/{address}	FICO-pack proof status (all 5 proofs)	Public
POST	/api/v1/zkdefi/reputation/upgrade-tier	Request a tier upgrade	App flow
POST	/api/v1/zkdefi/reputation/proof/solvency	Generate solvency proof ("I can pay what I owe")	App flow
POST	/api/v1/zkdefi/reputation/proof/risk-passport	Generate risk passport tier proof	App flow
POST	/api/v1/zkdefi/reputation/proof/performance	Generate trader performance proof	App flow
POST	/api/v1/zkdefi/reputation/proof/strategy-integrity	Generate strategy integrity proof	App flow
POST	/api/v1/zkdefi/reputation/proof/execution-integrity	Generate execution integrity proof	App flow
GET	/api/v1/zkdefi/risk_passport/user/{address}	User passport — composed trust object	Public
GET	/api/v1/zkdefi/risk_passport/pool/{pool_id}	Pool passport — trust context for a target pool	Public
GET	/api/v1/zkdefi/risk_profile/{address}	Aggregated risk profile (superset of passport)	Public
GET	/api/v1/zkdefi/compliance/profiles/{user_address}	Compliance profiles	Public
GET	/api/v1/zkdefi/linked_addresses/{address}	Linked-address map (Starknet ↔ Ethereum)	Public
PUT	/api/v1/zkdefi/linked_addresses	Update linked addresses	App flow

The five POST .../proof/* endpoints each generate a zero-knowledge proof for one component of the FICO-pack. Each takes a request body with the user's address and returns a proof artifact. These are the endpoints that actually invoke the EZKL → Groth16 → Garaga pipeline.

---

Onboarding & agent registration

New users go through onboarding to bind their wallet and register with the agent system. This is a two-step flow: generate an authorization payload, then submit it. Once onboarding completes, the user's wallet is known to the system and can interact with protected routes.

Method	Path	Purpose	Auth
POST	/api/v1/zkdefi/onboarding/generate_authorization	Generate onboarding authorization payload	App flow
POST	/api/v1/zkdefi/onboarding/submit_agent	Submit onboarding/agent registration	App flow
GET	/api/v1/zkdefi/onboarding/status/{user_address}	Check onboarding status	Public

---

Orchestration (deploy & utilities)

The orchestration endpoints handle multi-step deployment flows — building the calldata, recording a receipt, then confirming the on-chain tx hash. The receipt pattern matters: you get a receipt ID before execution, then attach the tx hash after the wallet signs and submits.

Method	Path	Purpose	Auth
POST	/api/v1/zkdefi/orchestration/deploy	Build/record deploy orchestration flow	App flow
GET	/api/v1/zkdefi/orchestration/receipt/{receipt_id}	Read deploy receipt	Public
POST	/api/v1/zkdefi/orchestration/receipt/confirm	Attach tx hash to receipt (post-signing)	App flow
POST	/api/v1/zkdefi/orchestration/swap-strk-to-usdc	Build STRK→USDC swap calldata	App flow
POST	/api/v1/zkdefi/orchestration/faucet/eth	Testnet ETH faucet	App flow

---

Session keys & rebalancer

Session keys let you delegate bounded authority to the agent system — "execute within these constraints for the next N hours without asking me to sign each time." The rebalancer uses session keys for autonomous operation.

For the conceptual explanation of session keys, see Session Keys. For the rebalancing pipeline, see Rebalancing.

Method	Path	Purpose	Auth
POST	/api/v1/zkdefi/session_keys/grant	Build session grant request	App flow
POST	/api/v1/zkdefi/session_keys/grant/confirm	Confirm granted session	App flow
POST	/api/v1/zkdefi/session_keys/revoke	Build session revoke request	App flow
POST	/api/v1/zkdefi/session_keys/revoke/confirm	Confirm revocation	App flow
GET	/api/v1/zkdefi/session_keys/list/{owner_address}	List active sessions	Public
POST	/api/v1/zkdefi/rebalancer/propose	Create rebalance proposal	App flow
POST	/api/v1/zkdefi/rebalancer/check	Run risk/anomaly checks (strict — blocks on failure)	App flow
POST	/api/v1/zkdefi/rebalancer/advisory-check	Non-blocking policy check (advisory only)	App flow
POST	/api/v1/zkdefi/rebalancer/prepare	Prepare execution context	App flow
POST	/api/v1/zkdefi/rebalancer/execute	Execute prepared rebalance	App flow
POST	/api/v1/zkdefi/rebalancer/autonomous/start	Start autonomous mode	X-Wallet-Address
POST	/api/v1/zkdefi/rebalancer/autonomous/stop	Stop autonomous mode	X-Wallet-Address
POST	/api/v1/zkdefi/rebalancer/autonomous/pause/{user_address}	Pause autonomous mode	X-Wallet-Address
POST	/api/v1/zkdefi/rebalancer/autonomous/resume/{user_address}	Resume autonomous mode	X-Wallet-Address
GET	/api/v1/zkdefi/rebalancer/autonomous/all	Fleet status (all active autonomous agents)	X-Admin-Key

The rebalancer pipeline is sequential: propose → check → prepare → execute. Skipping steps will fail. The autonomous endpoints wrap this pipeline in a loop with session-key-scoped authority.

---

Auth session (dual-wallet bind)

zkde.fi supports linking a Starknet wallet to an Ethereum wallet for cross-chain identity. The auth session endpoints manage this binding.

Method	Path	Purpose	Auth
POST	/api/v1/zkdefi/auth/session/start	Start dual-wallet auth session	App flow
POST	/api/v1/zkdefi/auth/session/complete	Complete dual-wallet auth session	App flow
GET	/api/v1/zkdefi/auth/session/{starknet_address}	Read active auth session	Public
DELETE	/api/v1/zkdefi/auth/session/{starknet_address}	Revoke active auth session	App flow

---

Trade, market & Ekubo

The trading surface. Market data is read-only. Ekubo operations (swap, LP, fee collection) produce prepared calldata that the frontend submits through wallet signing.

For the UI-level explanation, see Trade Desk and Deploy to Ekubo.

Method	Path	Purpose	Auth
GET	/api/v1/zkdefi/market/surface	Market surface bundle (pools, rates, opportunities)	Public
GET	/api/v1/zkdefi/ekubo/capabilities	Ekubo capability metadata	Public
GET	/api/v1/zkdefi/ekubo/positions	Ekubo position view	App flow
POST	/api/v1/zkdefi/ekubo/swap/quote	Swap quote	App flow
POST	/api/v1/zkdefi/ekubo/swap/build	Build swap calldata	App flow
POST	/api/v1/zkdefi/ekubo/lp/add/build	Build LP add calldata	App flow
POST	/api/v1/zkdefi/ekubo/lp/remove/build	Build LP remove calldata	App flow
POST	/api/v1/zkdefi/ekubo/lp/collect-fees/build	Build fee-collect calldata	App flow
POST	/api/v1/zkdefi/ekubo/lp/recommend	LP recommendation (suggested ranges, allocations)	App flow

Adapter routes return prepared execution data that still depends on valid session state, proof readiness, and market conditions at submission time.

---

Reputation-based lending

Lending without traditional collateral ratios — instead, your reputation and FICO-pack attestations determine eligibility and terms. This is still evolving; integrators should verify artifact availability before assuming a fully automated borrow lifecycle.

Method	Path	Purpose	Auth
GET	/api/v1/zkdefi/lending/pool	Lending pool stats	Public
GET	/api/v1/zkdefi/lending/positions/{address}	User lending positions	Public
POST	/api/v1/zkdefi/lending/supply	Build supply calldata	App flow
POST	/api/v1/zkdefi/lending/borrow	Build borrow calldata (attestation-oriented)	App flow
POST	/api/v1/zkdefi/lending/repay	Build repay calldata	App flow
POST	/api/v1/zkdefi/lending/withdraw	Build withdraw calldata	App flow
GET	/api/v1/zkdefi/lending/health/{address}	Health factor context	Public
POST	/api/v1/zkdefi/lending/proof/credit-eligibility	Credit eligibility proof generation	App flow

---

zkML inference & circuit scan

A single endpoint that takes model/circuit inputs and returns zkML risk signals. This is the entry point for the 13-circuit bundle — the backend determines which circuits fire based on the input data.

Method	Path	Purpose	Auth
POST	/api/v1/zkdefi/zkml/scan	Scan inputs, return zkML risk signals	App flow

---

Privacy & state

The privacy endpoints implement the privacy pipeline — commitment generation, registration, withdrawal proof generation, and merkle state management. The unified deposit/withdraw endpoints are the recommended surface; the full_privacy/* routes expose the internal steps.

Method	Path	Purpose	Auth
POST	/api/v1/zkdefi/full_privacy/deposit/generate_commitment	Generate privacy commitment	App flow
POST	/api/v1/zkdefi/full_privacy/deposit/register_commitment	Register commitment in merkle tree	App flow
POST	/api/v1/zkdefi/full_privacy/withdraw/generate_proof	Generate withdrawal proof	App flow
GET	/api/v1/zkdefi/full_privacy/merkle/root	Current merkle root state	Public
POST	/api/v1/zkdefi/full_privacy/merkle/reset	Reset merkle tree (destructive)	X-Admin-Key
POST	/api/v1/zkdefi/privacy/deposit	Unified privacy deposit	App flow
POST	/api/v1/zkdefi/privacy/withdraw	Unified privacy withdraw	App flow
GET	/api/v1/zkdefi/wallet/state/{user_address}	Wallet state snapshot	Public
POST	/api/v1/zkdefi/execution/preflight	Preflight execution checks	App flow
POST	/api/v1/zkdefi/state/manual-wallet-event	Manual wallet event injection	App flow

---

Policy, relayer & ledger

Policy endpoints let you read and update vault constraints — what the agent is allowed to do. The relayer handles transaction submission for gas-abstracted flows. The ledger provides transfer history.

Method	Path	Purpose	Auth
GET	/api/v1/zkdefi/policy/vault/{user_address}	Read vault policy	Public
PUT	/api/v1/zkdefi/policy/vault/{user_address}	Update vault policy	X-Wallet-Address
POST	/api/v1/zkdefi/policy/compile	Compile policy (validate constraints)	App flow
POST	/api/v1/zkdefi/policy/reset/{user_address}	Reset policy state	X-Admin-Key
POST	/api/v1/zkdefi/relayer/request	Submit relay request	App flow
GET	/api/v1/zkdefi/relayer/pending/{address}	Pending relay queue	Public
GET	/api/v1/zkdefi/ledger/transfers	Ledger transfer history	Public
POST	/api/v1/zkdefi/ledger/demo-credit	Demo credit path (testnet utility)	App flow

---

Integrator APIs (outside /zkdefi)

These endpoints live outside the main zkdefi namespace. They serve cross-cutting concerns — identity proofs, agent management, strategy recommendations, and deployment execution.

Method	Path	Purpose	Auth
POST	/api/v1/identity/credit-proof	Identity credit proof flow	App flow
GET	/api/v1/identity/commitment/{commitment}	Commitment lookup	Public
GET	/api/v1/agents/models/list	Model catalog (available zkML models)	Public
POST	/api/v1/agents/create	Create agent entry	App flow
GET	/api/v1/strategies/price/live	Live price feed	Public
POST	/api/v1/strategies/recommend	Strategy recommendation	App flow
POST	/api/v1/deployments/execute	Deployment execution	App flow
POST	/api/v1/vault/execute	Vault execution path	App flow

---

Experimental scope

These endpoints are changing faster than the rest. They're live and functional, but their paths, request shapes, and response contracts may shift between releases.

GET  /api/v1/phase4a/status
GET  /api/v1/phase4a/orchestrated/dashboard
GET  /api/v1/phase4a/rebalancer/stats
GET  /api/v1/vault-live/positions/{user_address}
POST /api/v1/vault-live/rebalance
POST /api/v1/vault-live/execute
GET  /api/v1/zkdefi/sim/health
GET  /api/v1/zkdefi/sim/state
GET  /api/v1/zkdefi/sim/events
GET  /api/v1/zkdefi/sim/contracts

---

These docs describe technical capabilities and API behavior. They are not legal advice, investment advice, or a representation that any user automatically meets regulatory requirements.

Next: Developers · Architecture · Troubleshooting