Metadata-Version: 2.4
Name: tradekartapi
Version: 0.1.3
Summary: Tradekart wrapper SDK for Groww trading APIs
Author-email: Vikalp <tradekart@gmail.com>, Siddhant <tradekart@gmail.com>, Lakshay <tradekart@gmail.com>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: growwapi
Requires-Dist: pydantic
Provides-Extra: dev
Requires-Dist: pytest>=8.3.2; extra == "dev"
Requires-Dist: ruff>=0.12.1; extra == "dev"
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: twine>=5.1.1; extra == "dev"
Provides-Extra: aws
Requires-Dist: boto3>=1.34.0; extra == "aws"

# TradeKart API

TradeKart API is a Python wrapper around the official Groww SDK with a service-oriented design for trading workflows.

It provides custom service layers for common operations (Orders, Portfolio) with request models, response models, and consistent exception handling so teams can build reliable trading integrations faster.

## Why TradeKart API

- Built on top of `growwapi`, so you can continue to use Groww's official SDK.
- Clean service abstraction for business use-cases instead of raw SDK calls everywhere.
- Typed request models for safer payload construction.
- Structured response handling for predictable downstream processing.
- Custom exceptions for easier debugging and application-level error handling.

## Installation

```bash
pip install tradekartapi
```

## Quick Start (Jupyter / Notebook)

```python
from tradekartapi.client import TradeKartClient
from growwapi import GrowwAPI

access_token = "your_access_token"
client = TradeKartClient.from_access_token(access_token, GrowwAPI)
# Now client is ready to use the service
```

## Service Architecture

TradeKart API uses:

1. **Groww SDK Adapter** to initialize and hold the SDK client.
2. **Custom Services** to expose trading operations as business-level methods.
3. **Models** to keep request and response shapes explicit and reusable.

### Available Services

- **Order Service**
  - Place order
  - Modify order
  - Cancel order
  - Get order status
  - Get order list
  - Get order detail
- **Portfolio Service**
  - Get holdings
  - Get positions
  - Get positions by trading symbol

### Margin Service

Margin-related service support is planned as part of upcoming releases.

## Orders Example

```python
from tradekartapi.models.orders import PlaceOrderRequest
from tradekartapi.models.annexures import (
    Exchange, Segment, Product, OrderType, TransactionType, Validity
)

request = PlaceOrderRequest(
    trading_symbol="SBIN",
    quantity=1,
    validity=Validity.DAY,
    exchange=Exchange.NSE,
    segment=Segment.CASH,
    product=Product.CNC,
    order_type=OrderType.MARKET,
    transaction_type=TransactionType.BUY,
)

response = client.order_service.place_order(request)
print(response)
```

## Portfolio Example

```python
holdings = client.portfolio_service.get_holdings()
positions = client.portfolio_service.get_positions()

print([h.to_dict() for h in holdings])
print([p.to_dict() for p in positions])
```

## Response Formats

Depending on the service method, you may receive:

- Native `dict` from direct SDK passthrough methods.
- Dataclass-based response objects from modeled service methods.

For dataclass responses, use:

- `to_dict()` for Python dictionary output.
- `to_json()` for JSON string output.

## Error Handling

TradeKart API raises structured custom exceptions for validation and service-level failures, making it easier to map failures to API responses or logs in production systems.

## Compatibility

- Python `>=3.10`
- Depends on `growwapi`

## Changelog
Full changelog: https://tradekartapi.readthedocs.io/en/latest/changelog.html

## License

MIT
