Katana - Injective Market Intelligence API

# Katana — Injective Market Intelligence API 🗡️

**Slicing through raw data to deliver actionable market intelligence.**

---

## 📖 Overview

**Katana** is a developer-first infrastructure layer built for the **Ninja API Forge**. It acts as a sharp abstraction over the Injective Protocol, transforming raw, noisy on-chain data into distinct, normalized, and computed market intelligence.

Unlike raw indexers that return massive payloads of difficult-to-parse data, Katana provides a clean, opinionated REST API designed for immediate developer consumption. It focuses on **"Intelligence"**—derived metrics like liquidity depth, volatility, and risk scoring that usually require complex client-side math.

## 🚀 Why Katana?

Developers building on Injective currently face high friction:
- **Complexity**: Raw Injective API responses are massive and require deep protocol knowledge.
- **Fragmentation**: assembling a simple "market health" view requires hitting 3+ different endpoints.
- **Redundancy**: Every developer re-writes the same volatility and spread calculations.

Katana solves this by being **"Stripe for Injective Market Data"**:
1.  **Normalized**: Consistent JSON schemas for all markets (Spot & Perp).
2.  **Computed**: We do the math (Spread, Liquidity Score, Imbalance) so you don't have to.
3.  **Identity-Aware**: Integrated with **N1NJ4** for developer identity context.

## 🥷 N1NJ4 Identity Integration

Katana implements a lightweight **Identity-Aware** layer. It doesn't just serve data; it knows *who* is asking.

- **Check Identity**: `GET /api/v1/katana/identity/inspect`
- **Behavior**:
  - **Anonymous**: Standard rate limits, base metrics.
  - **Identified**: (via `x-n1nj4-id` header) Unlocks advanced analytics & higher quotas.
  - **Trusted**: Priority execution and real-time streaming capabilities.

## ⚡ API Endpoints

Base URL: `http://localhost:3000/api/v1/katana`

### 1. Market Summary
`GET /markets/summary`
Returns a normalized list of top markets with computed liquidity scores.
```json
[
  {
    "marketId": "0xa508...",
    "base": "INJ",
    "quote": "USDT",
    "lastPrice": 35.42,
    "liquidityScore": 85,
    "spread": 0.0004
  }
]
```

### 2. Market Metrics (The "Intelligence" Layer)
`GET /markets/:marketId/metrics`
Key derived data for smart applications.
```json
{
  "volatility24h": 4.5,
  "liquidityDepth": 1250000,
  "marketHealth": "healthy",
  "riskLevel": "low"
}
```

### 3. Orderbook Snapshot
`GET /markets/:marketId/orderbook?depth=20`
Clean, simplified orderbook with liquidity calculations.

### 4. Identity Inspection
`GET /identity/inspect`
Input: `x-n1nj4-id` header.
Returns your developer tier and quota status.

## 🛠️ Tech Stack & Data Strategy

- **Runtime**: Node.js + Fastify + TypeScript
- **Metadata**: Real-time via Injective Mainnet LCD (`sentry.lcd.injective.network`)
- **Intelligence**:
  - **Price/Markets**: Derived from LCD & Oracle data.
  - **Depth/Volume**: **Simulated** (Deterministic model seeded by Market ID) due to public Indexer API REST restrictions.
  - **Metrics**: Real computed logic applied to hybrid data universe.
- **Identity**: N1NJ4 header-based inspection.

## 📦 How to Run

1. **Install Dependencies**
   ```bash
   npm install
   ```

2. **Start Server**
   ```bash
   npm run dev
   ```

3. **Verify**
   ```bash
   curl http://localhost:3000/api/v1/katana/markets/summary
   ```

## 🏆 Notes for Judges

- **Architecture**: Clean separation of `Services` (Logic), `Controllers` (Orchestration), and `Utils` (Math).
- **Hybrid Data**: We prioritize **Availability** and **Experience**. When the Indexer API proved inaccessible via standard REST, we pivoted to a robust LCD + Oracle + Simulation model to ensure the API *works* and *demonstrates value* immediately.
- **Abstraction**: We never expose raw Injective structures. Everything is re-mapped to Katana's clean Interface.
- **Extensibility**: The Identity layer is designed to be swapped with on-chain DID logic.

---
*Built for the Ninja API Forge 2025.*