Kyvrane

Every trade must prove itself.

Kyvrane is a pre-execution firewall for AI-assisted crypto trading. It verifies SoSoValue market evidence, prices the proposal against SoDEX order-book depth, applies deterministic policy, and returns a hash-sealed APPROVE, REVIEW, or BLOCK receipt before capital moves.

Live Demo · Scenarios · Provider Status · Docs · Repository

AI can explain evidence. It does not authorize capital. Kyvrane's verdict is owned by deterministic TypeScript.

Problem

AI trading agents can make trades look profitable without checking the execution path that decides whether the trade survives in the real market.

A proposal can show a 2.40% expected return, but the top of the book may only hold 0.40 ETH. A larger order walks deeper into the book, raises the average fill price, adds slippage and fees, and can turn a positive-looking trade into a negative one before it is placed.

For solo traders and builders using AI-assisted trading agents, the missing control is not another strategy generator. The missing control is a proof step that says: this trade has fresh evidence, enough liquidity, acceptable slippage, and a policy verdict before funds move.

Solution

Kyvrane sits before execution. It receives a proposed trade, gathers sponsor-backed evidence, computes the real executable edge, and returns an auditable receipt.

The MVP is deliberately narrow:

• It evaluates trade proposals.
• It issues APPROVE, REVIEW, or BLOCK.
• It records sources, calculations, policy version, verdict, time, and a SHA-256 receipt hash.
• It does not connect a wallet, place orders, custody funds, or give financial advice.

Product demo

Fastest judge path: open /scenarios, run all three proposals, then open /status to see whether providers are live or demo.

Route	What to verify
/	Trade authorization workspace and product framing
/scenarios	Reproducible APPROVE, REVIEW, and BLOCK verdicts
/status	Provider mode transparency for SoSoValue and SoDEX
/docs	Pipeline, verdicts, provenance, receipts, and API notes

Screenshots are pending. The live deployment is the current product proof.

How it works

1. A user or agent submits a trade proposal.
2. Kyvrane requests market evidence from the SoSoValue adapter.
3. Kyvrane requests order-book execution conditions from the SoDEX adapter.
4. The engine calculates net executable edge: expectedReturn - slippage - fees - marketImpact.
5. Deterministic policy checks edge, slippage, evidence age, contradiction count, and notional exposure.
6. The engine returns APPROVE, REVIEW, or BLOCK with reason codes.
7. A Trade Proof Receipt records inputs, source modes, calculations, policy version, verdict, and issue time.
8. The receipt is sealed with a canonical SHA-256 hash and can be replayed.

Key features

• Deterministic authorization - no LLM decides whether capital can move.
• Sponsor-backed evidence path - SoSoValue evidence freshness and contradiction counts affect the verdict.
• Execution-aware pricing - SoDEX order-book depth is walked with estimateFill, so a 1 ETH order and a 5 ETH order can produce different verdicts.
• Hash-sealed receipts - every decision gets a tamper-evident proof receipt.
• Replay API - captured assessments can be re-evaluated without hiding their original source metadata.
• Provider transparency - /status publishes whether each adapter is using live sponsor data or seeded demo data.
• No custody by design - Kyvrane cannot move funds, connect a wallet, or place orders.

Why it is different

Alternative	What it does	Kyvrane difference
Trading bot	Generates or executes trades	Kyvrane is a pre-execution control, not a strategy engine.
LLM risk summary	Explains a proposed trade	Kyvrane lets AI explain, but deterministic code owns the verdict.
Static checklist	Asks a user to review manually	Kyvrane computes slippage, evidence freshness, contradiction count, and policy outcomes.
Demo-only sponsor integration	Shows sponsor logos or sample cards	Kyvrane routes sponsor data through the decision engine, and labels demo mode honestly.

Architecture

flowchart LR
  U[User or AI agent] --> API[POST /api/trades/analyze]
  API --> SSV[SoSoValue adapter]
  API --> SOD[SoDEX adapter]
  SSV --> E[Deterministic policy engine]
  SOD --> E
  E --> R[Trade Proof Receipt]
  R --> H[SHA-256 contentHash]
  R --> UI[Workspace, scenarios, receipts]
  API --> Status[GET /api/health]

Loading

Trust boundaries:

• Provider adapters own HTTP and authentication.
• API routes orchestrate requests and validation.
• The decision engine is pure TypeScript with no network or AI calls.
• UI components never call sponsor APIs directly.
• Sponsor keys are server-side only.

Sponsor integrations

SoSoValue

• Supplies timestamped market evidence.
• Kyvrane derives evidence freshness and contradiction count from that evidence.
• Stale evidence can trigger REVIEW; evidence outside the policy window can trigger BLOCK.
• Environment variables: SOSOVALUE_API_KEY, SOSOVALUE_API_BASE_URL.

SoDEX

• Supplies order-book depth for execution checks.
• Kyvrane walks the book with estimateFill to compute average fill price and slippage for the requested size.
• Slippage above policy can trigger BLOCK; larger notional can trigger REVIEW.
• Environment variable: SODEX_API_BASE_URL.

Live vs demo status

Sponsor credentials are not provisioned in this repo, so both adapters currently run seeded demo data through the same code path. The UI and API label those values as DEMO, and /status publishes the mode of each provider.

Demo mode still exercises the real engine, policy math, receipt hashing, and routes. What changes is the origin of the inputs, not the verdict path.

Live deployment and proof

Proof item	Value
Live app	https://kyvrane.vercel.app
Scenarios	https://kyvrane.vercel.app/scenarios
Provider status	https://kyvrane.vercel.app/status
Repository	https://github.com/mystiquemide/kyvrane
Sponsor credential status	Pending - adapters currently run labelled demo data
Demo video	Pending

Tech stack

• Frontend: Next.js 16 App Router, React 19, TypeScript, Tailwind CSS 4
• Testing: Vitest, ESLint, TypeScript typecheck
• Decision engine: Pure TypeScript policy engine
• Proof: SHA-256 content hash over canonical receipts
• Deployment: Vercel
• State: Browser-local receipt history for the MVP

Installation instructions

git clone https://github.com/mystiquemide/kyvrane.git
cd kyvrane
npm install
npm run setup:hooks
cp .env.example .env.local
npm run dev

Kyvrane runs without credentials in labelled demo mode.

To connect live providers, set:

SOSOVALUE_API_KEY=your_sosovalue_key
SOSOVALUE_API_BASE_URL=https://example.sosovalue.api
SODEX_API_BASE_URL=https://example.sodex.api

Then open /status to confirm the provider modes.

Testing

npm run verify

npm run verify runs:

npm run lint
npm run typecheck
npm test
npm run build

The suite covers deterministic verdicts, provider adapters, receipt hashing, replay behavior, and API-route behavior for the reproducible APPROVE, REVIEW, and BLOCK scenarios.

Challenges and lessons

• Sponsor data must be integral to the verdict, not decorative.
• A narrow working firewall is stronger than a broad trading-agent demo.
• The UI must never blur live provider data and fallback demo data.
• Receipt hashes prove tamper evidence for a specific issued receipt, not profit or market truth.
• The clean product boundary is important: Kyvrane evaluates and proves; it does not execute.

Roadmap

Before submission

• Record the submission walkthrough from docs/DEMO_SCRIPT.md.
• Add final demo video link to this README.
• Keep /scenarios and /status stable for judges.

Post-hackathon V1

• Provision live SoSoValue and SoDEX credentials.
• Add signed testnet execution handoff while keeping custody out of scope.
• Export receipts for external audit trails.

Longer term

• Multi-venue execution checks.
• Policy templates for different trader risk profiles.
• Agent integration SDK for pre-trade authorization.

Scope and safety

Kyvrane is unaudited hackathon software. It does not custody assets, connect wallets, place trades, or provide financial advice. It is a pre-execution risk and proof layer for trade proposals.

License

MIT. See LICENSE.