@ethosagent/tools-india-broker-zerodha 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mitesh Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# @ethosagent/tools-india-broker-zerodha
+
+Zerodha Kite Connect broker tools for Ethos AI agents. Read equity holdings, positions, orders, margins, and place orders with human confirmation via the Kite Connect REST API.
+
+> **Part of the [Ethos](https://github.com/ethosagent/ethos) AI agent ecosystem.**
+> These tools are designed to be registered with an Ethos agent via `createZerodhaTools()`. They can also be used standalone via the CLI.
+
+## Prerequisites
+
+- **Zerodha trading account** (free) at [zerodha.com](https://zerodha.com)
+- **Kite Connect API subscription** — INR 2,000/month from [kite.trade](https://kite.trade)
+- `api_key` and `api_secret` from the Kite Connect developer console
+
+## Auth Flow
+
+Zerodha uses session-based OAuth. The access token must be renewed daily — there is no automatic refresh.
+
+### Setup: Register redirect URLs in Zerodha developer portal
+
+Log in to [kite.trade/apps](https://kite.trade/apps) and add both redirect URLs to your app:
+
+| Surface | Redirect URL |
+|---|---|
+| Ethos Desktop | `ethos://auth/zerodha` |
+| Ethos Web | `https://your-domain.com/auth/zerodha/callback` |
+
+You only need to register the surface(s) you use.
+
+### Desktop (Ethos app)
+
+The desktop app shows a **Connect Zerodha** button when the token is expired. Clicking it:
+1. Opens `https://kite.trade/connect/login?v=3&api_key=XXX` in your system browser
+2. After you log in, Zerodha redirects to `ethos://auth/zerodha?request_token=YYY`
+3. The app catches the redirect, exchanges the token, and stores it automatically
+
+### Web
+
+Configure `https://your-domain.com/auth/zerodha/callback` as the redirect URL.
+The web app handles the callback at that route, exchanges the token, and stores it.
+
+### CLI / Agent
+
+```bash
+zerodha-broker auth                       # print login URL
+zerodha-broker auth --request-token TOKEN # complete token exchange
+zerodha-broker auth status                # check token validity
+```
+
+Or ask the agent — it can call `zerodha_auth_status` to check validity and `zerodha_auth_complete` with the `request_token` to exchange the token.
+
+### Daily token renewal
+
+All tokens expire at midnight IST. The `zerodha_auth_status` tool returns whether the current token is still valid.
+
+## Install
+
+```bash
+npm install @ethosagent/tools-india-broker-zerodha
+```
+
+## CLI Usage
+
+```bash
+# Auth setup (one-time)
+mkdir -p ~/.ethos/secrets/brokers/zerodha
+echo "YOUR_API_KEY"    > ~/.ethos/secrets/brokers/zerodha/apiKey
+echo "YOUR_API_SECRET" > ~/.ethos/secrets/brokers/zerodha/apiSecret
+chmod 600 ~/.ethos/secrets/brokers/zerodha/*
+
+# Daily auth
+zerodha-broker auth                       # print login URL
+zerodha-broker auth --request-token TOKEN # complete token exchange
+zerodha-broker auth status                # check token validity
+
+# Portfolio
+zerodha-broker holdings                   # equity holdings with P&L
+zerodha-broker positions                  # open positions
+zerodha-broker orders                     # today's order book
+zerodha-broker margins                    # available funds
+
+# Orders
+zerodha-broker order --symbol RELIANCE --qty 10 --side BUY --type LIMIT --price 2980
+zerodha-broker order --symbol RELIANCE --qty 10 --side BUY --type LIMIT --price 2980 --confirm
+zerodha-broker cancel --order-id ORD123
+
+# Audit
+zerodha-broker log                        # agent order log
+zerodha-broker clean                      # wipe local cache
+```
+
+## Library / Ethos Integration
+
+```typescript
+import { createZerodhaTools } from '@ethosagent/tools-india-broker-zerodha';
+
+// Register all 6 tools with Ethos
+for (const tool of createZerodhaTools()) {
+  toolRegistry.register(tool);
+}
+```
+
+### Available Tools
+
+| Tool | Description |
+|---|---|
+| `zerodha_auth_status` | Check if access token is valid |
+| `zerodha_account` | Account summary — funds and margins |
+| `zerodha_holdings` | Equity holdings with P&L (cached) |
+| `zerodha_positions` | Open intraday and overnight positions |
+| `zerodha_orders` | Today's order book |
+| `zerodha_place_order` | Propose or place an equity order (dry-run default) |
+
+## SEBI Compliance Notice
+
+This tool is designed for **human-supervised, delivery-based (CNC) equity trading only**:
+
+- Order placement defaults to dry-run mode (`dry_run: true`)
+- Real orders require explicit human confirmation
+- No algorithmic or high-frequency trading (requires SEBI/exchange approval)
+- No intraday margin (MIS) or F&O orders in v1
+- Full audit trail of all proposed and placed orders
+
+## Development
+
+```bash
+npm install          # install dependencies
+npm run check        # typecheck + lint + test
+npm run build        # tsup -> dist/
+npm run dev          # tsup --watch
+make help            # list all targets
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node