n3-sdk 0.1.0

package/README.md

@@ -0,0 +1,214 @@
+<a id="readme-top"></a>
+
+[![Contributors][contributors-shield]][contributors-url]
+[![Forks][forks-shield]][forks-url]
+[![Stargazers][stars-shield]][stars-url]
+[![Issues][issues-shield]][issues-url]
+[![MIT License][license-shield]][license-url]
+[![LinkedIn][linkedin-shield]][linkedin-url]
+
+<br />
+<div align="center">
+  <a href="https://n3.exchange">
+    <img src="images/logo.png" alt="Logo" width="80" height="80">
+  </a>
+
+  <h3 align="center">N3 SDK</h3>
+
+  <p align="center">
+    A modern, type-safe, and modular SDK for the N3 Network — a privacy-preserving trading and liquidity layer.
+    <br />
+    <a href="https://docs.n3.exchange"><strong>Explore the Docs »</strong></a>
+    <br />
+    <br />
+    <a href="https://github.com/n3labs/n3-sdk">View Demo</a>
+    ·
+    <a href="https://github.com/n3labs/n3-sdk/issues/new?labels=bug&template=bug-report.md">Report Bug</a>
+    ·
+    <a href="https://github.com/n3labs/n3-sdk/issues/new?labels=enhancement&template=feature-request.md">Request Feature</a>
+  </p>
+</div>
+
+<details>
+  <summary>Table of Contents</summary>
+  <ol>
+    <li>
+      <a href="#about-the-project">About The Project</a>
+      <ul>
+        <li><a href="#built-with">Built With</a></li>
+      </ul>
+    </li>
+    <li>
+      <a href="#getting-started">Getting Started</a>
+      <ul>
+        <li><a href="#prerequisites">Prerequisites</a></li>
+        <li><a href="#installation">Installation</a></li>
+      </ul>
+    </li>
+    <li><a href="#usage">Usage</a></li>
+    <li><a href="#architecture">Architecture</a></li>
+    <li><a href="#tooling">Tooling</a></li>
+    <li><a href="#license">License</a></li>
+    <li><a href="#contact">Contact</a></li>
+    <li><a href="#acknowledgments">Acknowledgments</a></li>
+  </ol>
+</details>
+
+## About The Project
+
+[![N3 SDK Screenshot][product-screenshot]](https://n3.exchange)
+
+The **N3 SDK** provides a unified, developer-friendly way to interact with the **N3 Network**, a privacy-preserving hybrid trading, liquidity, and settlement layer.
+
+It enables you to:
+- Fetch **market data** (GraphQL)
+- Subscribe to **real-time feeds** (WebSocket)
+- Execute **exchange actions** like orders, cancels, and deposits
+- Sync **Merkle-proven private notes** for encrypted balances
+
+### Why N3 SDK?
+
+* Built for privacy-first decentralized trading infrastructure  
+* Clean, type-safe, and DRY architecture  
+* Works seamlessly across Bun, Node, and browser environments  
+* Fully modular — import only what you need  
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+### Built With
+
+* [![TypeScript][TypeScript-shield]][TypeScript-url]
+* [![GraphQL][GraphQL-shield]][GraphQL-url]
+* [![Bun][Bun-shield]][Bun-url]
+* [![Viem][Viem-shield]][Viem-url]
+* [![WebSocket][WebSocket-shield]][WebSocket-url]
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Getting Started
+
+Follow these steps to get started with N3 SDK in your project.
+
+### Prerequisites
+
+You’ll need one of the following installed:
+* Node.js ≥ 18  
+* Bun ≥ 1.1
+
+Check your version:
+```bash
+node -v
+# or
+bun -v
+
+Installation
+
+Install from npm:
+
+npm install n3-sdk
+# or
+bun add n3-sdk
+# or
+pnpm add n3-sdk
+
+Usage
+
+Initialize the SDK
+import { N3SDK } from "n3-sdk";
+
+const sdk = new N3SDK({
+  gqlUrl: "https://api.n3.exchange/graphql",
+  wsUrl: "wss://api.n3.exchange/ws",
+});
+
+Fetch Market Data
+
+const candles = await sdk.info.candles.list(241, "1m", 100);
+const trades = await sdk.info.trades.list(241, 50);
+
+Subscribe to Live Streams
+
+const sub = sdk.subscriptions.trades.stream(241, (trade) => {
+  console.log("Live trade:", trade);
+});
+sub.off();
+
+
+await sdk.exchange.order({
+  hl: { /* order data */ },
+  grouping: "limit",
+  domain: { pool: "0xPool", chainIdDec: 42161, DOMAIN_DEC: 1 },
+});
+
+Deposit ERC20
+
+await sdk.exchange.depositERC20({
+  clients,
+  token: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+  assetId: 100, (Hyperliquid tokenIDs)
+  amount: 1000n * 10n ** 6n,
+});
+
+Receiver Sync
+
+const stop = sdk.startReceiverSync(noteStore, clients);
+stop();
+
+Architecture
+
+┌────────────────────────────┐
+│        Client App          │
+│   (Web / Node / Mobile)    │
+└────────────┬───────────────┘
+             │
+             ▼
+     ┌────────────────────┐
+     │       N3 SDK       │
+     │────────────────────│
+     │ Info (GraphQL)     │ → Historical data
+     │ Subscriptions (WS) │ → Live streams
+     │ Exchange Actions   │ → Orders & Withdrawals
+     │ Notes / Receiver   │ → Merkle tracking
+     └────────────────────┘
+             │
+             ▼
+     ┌────────────────────┐
+     │  N3 Gateway + TEE  │
+     └────────────────────┘
+
+
+     The SDK exposes three namespaces:
+	•	info → Historical GraphQL queries
+	•	subscriptions → WebSocket data fan-outs
+	•	exchange → Orders, cancels, deposits, withdrawals
+
+Tooling
+
+Tool
+Purpose
+TypeScript
+Full static typing
+Tsup
+High-speed bundler (ESM output)
+Viem
+Blockchain client abstraction
+GraphQL
+Data layer
+WebSocket
+Real-time transport
+Bun
+Dev runtime & test harness
+
+
+License
+Distributed under the MIT License. See LICENSE.txt for details.
+
+
+Contact
+
+N3 Labs
+Website: https://n3.exchange
+Docs: https://docs.n3.exchange
+Twitter: @n3labs
+Email: dev@n3.exchange
+Project Link: https://github.com/n3labs/n3-sdk