# Trading Contracts
JSON Schema validation library for trading platform events. This package provides schemas and validation tools for Kafka events used across the trading platform services.
## Features
- **JSON Schema Validation**: Pre-defined schemas for all trading platform events
- **Python Package**: Easy integration with Python services
- **Version Management**: Schema versioning with semantic versioning support
- **Type Safety**: Full type hints and validation
## Installation
```bash
pip install trading-contracts
```
## Quick Start
```python
from trading_contracts import validate_event, load_schema
# Validate an event
event_data = {
"event_id": "evt_123",
"version": 1,
"instance_id": "inst_001",
"symbol": "BTCUSDT",
"side": "BUY",
"price": "45000.50",
"ts": "2024-01-15T10:30:00Z"
}
try:
validate_event("strategy.signal@v1", event_data)
print("Event is valid!")
except ValidationError as e:
print(f"Validation failed: {e}")
# Load schema for inspection
schema = load_schema("strategy.signal@v1")
print(f"Schema title: {schema['title']}")
```
## Available Schemas
| Event | Schema File | Description |
|-------|-------------|-------------|
| `md.candle.closed@v1` | `md.candle.closed.v1.schema.json` | Market data candle close events |
| `strategy.signal@v1` | `strategy.signal.v1.schema.json` | Trading signals from strategy service |
| `risk.signal.allowed@v1` | `risk.signal.allowed.v1.schema.json` | Risk validation approvals |
| `risk.signal.denied@v1` | `risk.signal.denied.v1.schema.json` | Risk validation denials |
| `risk.limit.breached@v1` | `risk.limit.breached.v1.schema.json` | Risk limit breaches |
| `exec.order.placed@v1` | `exec.order.placed.v1.schema.json` | Order placement events |
| `exec.order.rejected@v1` | `exec.order.rejected.v1.schema.json` | Order rejection notifications |
| `exec.order.filled@v1` | `exec.order.filled.v1.schema.json` | Order execution confirmations |
| `pf.position.updated@v1` | `pf.position.updated.v1.schema.json` | Portfolio position updates |
| `pf.balance.updated@v1` | `pf.balance.updated.v1.schema.json` | Account balance updates |
| `pf.pnl.updated@v1` | `pf.pnl.updated.v1.schema.json` | Portfolio P&L updates |
| `runs.started@v1` | `runs.started.v1.schema.json` | Strategy run lifecycle events |
| `runs.status.changed@v1` | `runs.status.changed.v1.schema.json` | Run status transitions |
| `runs.finished@v1` | `runs.finished.v1.schema.json` | Run completion events |
## HTTP API
OpenAPI specification for HTTP endpoints is available in [http/openapi.yaml](http/openapi.yaml).
## Schema Naming Convention
Schemas follow the pattern: `{service}.{event_type}@v{version}`
- **service**: Service identifier (strategy, exec, risk, pf, runs)
- **event_type**: Specific event type (signal, order.filled, etc.)
- **version**: Schema version number
## Development
### Setup
```bash
git clone <repository>
cd contracts
pip install -e ".[dev]"
```
### Running Tests
```bash
pytest
```
### Code Quality
```bash
black src/
isort src/
mypy src/
```
## Adding New Schemas
1. Create schema file in `kafka/` directory
2. Follow naming convention: `{event}.v{version}.schema.json`
3. Add example in `examples/` directory
4. Update this README with new event details
## Schema Requirements
All schemas must include:
- `event_id`: Unique event identifier
- `version`: Schema version (const value)
- `ts`: Timestamp in ISO 8601 format
- `additionalProperties: false` for strict validation
## License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "trading-contracts",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "trading, kafka, json-schema, validation",
"author": "Trading Platform Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a0/06/1a6c0cfdbd83d94981c8b7c9537539eb850bb3ea262c1a93d68aaa3d985b/trading_contracts-0.2.0.tar.gz",
"platform": null,
"description": "# Trading Contracts\n\nJSON Schema validation library for trading platform events. This package provides schemas and validation tools for Kafka events used across the trading platform services.\n\n## Features\n\n- **JSON Schema Validation**: Pre-defined schemas for all trading platform events\n- **Python Package**: Easy integration with Python services\n- **Version Management**: Schema versioning with semantic versioning support\n- **Type Safety**: Full type hints and validation\n\n## Installation\n\n```bash\npip install trading-contracts\n```\n\n## Quick Start\n\n```python\nfrom trading_contracts import validate_event, load_schema\n\n# Validate an event\nevent_data = {\n \"event_id\": \"evt_123\",\n \"version\": 1,\n \"instance_id\": \"inst_001\",\n \"symbol\": \"BTCUSDT\",\n \"side\": \"BUY\",\n \"price\": \"45000.50\",\n \"ts\": \"2024-01-15T10:30:00Z\"\n}\n\ntry:\n validate_event(\"strategy.signal@v1\", event_data)\n print(\"Event is valid!\")\nexcept ValidationError as e:\n print(f\"Validation failed: {e}\")\n\n# Load schema for inspection\nschema = load_schema(\"strategy.signal@v1\")\nprint(f\"Schema title: {schema['title']}\")\n```\n\n## Available Schemas\n\n| Event | Schema File | Description |\n|-------|-------------|-------------|\n| `md.candle.closed@v1` | `md.candle.closed.v1.schema.json` | Market data candle close events |\n| `strategy.signal@v1` | `strategy.signal.v1.schema.json` | Trading signals from strategy service |\n| `risk.signal.allowed@v1` | `risk.signal.allowed.v1.schema.json` | Risk validation approvals |\n| `risk.signal.denied@v1` | `risk.signal.denied.v1.schema.json` | Risk validation denials |\n| `risk.limit.breached@v1` | `risk.limit.breached.v1.schema.json` | Risk limit breaches |\n| `exec.order.placed@v1` | `exec.order.placed.v1.schema.json` | Order placement events |\n| `exec.order.rejected@v1` | `exec.order.rejected.v1.schema.json` | Order rejection notifications |\n| `exec.order.filled@v1` | `exec.order.filled.v1.schema.json` | Order execution confirmations |\n| `pf.position.updated@v1` | `pf.position.updated.v1.schema.json` | Portfolio position updates |\n| `pf.balance.updated@v1` | `pf.balance.updated.v1.schema.json` | Account balance updates |\n| `pf.pnl.updated@v1` | `pf.pnl.updated.v1.schema.json` | Portfolio P&L updates |\n| `runs.started@v1` | `runs.started.v1.schema.json` | Strategy run lifecycle events |\n| `runs.status.changed@v1` | `runs.status.changed.v1.schema.json` | Run status transitions |\n| `runs.finished@v1` | `runs.finished.v1.schema.json` | Run completion events |\n\n## HTTP API\n\nOpenAPI specification for HTTP endpoints is available in [http/openapi.yaml](http/openapi.yaml).\n\n## Schema Naming Convention\n\nSchemas follow the pattern: `{service}.{event_type}@v{version}`\n\n- **service**: Service identifier (strategy, exec, risk, pf, runs)\n- **event_type**: Specific event type (signal, order.filled, etc.)\n- **version**: Schema version number\n\n## Development\n\n### Setup\n\n```bash\ngit clone <repository>\ncd contracts\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\npytest\n```\n\n### Code Quality\n\n```bash\nblack src/\nisort src/\nmypy src/\n```\n\n## Adding New Schemas\n\n1. Create schema file in `kafka/` directory\n2. Follow naming convention: `{event}.v{version}.schema.json`\n3. Add example in `examples/` directory\n4. Update this README with new event details\n\n## Schema Requirements\n\nAll schemas must include:\n- `event_id`: Unique event identifier\n- `version`: Schema version (const value)\n- `ts`: Timestamp in ISO 8601 format\n- `additionalProperties: false` for strict validation\n\n## License\n\nMIT License - see LICENSE file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "JSON Schemas for trading platform events",
"version": "0.2.0",
"project_urls": null,
"split_keywords": [
"trading",
" kafka",
" json-schema",
" validation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3986bd9600812f7d6f3725d3eea5a1f2cc03e1dc9b7c0188294f18bff66e5107",
"md5": "fe056edeacc5530fc9014934d92b80fc",
"sha256": "4ecaf7fe7ce45f074860388c4cdf0077deb7908916d4e4c37d4a8d7ee962602e"
},
"downloads": -1,
"filename": "trading_contracts-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fe056edeacc5530fc9014934d92b80fc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 4713,
"upload_time": "2025-08-31T09:48:56",
"upload_time_iso_8601": "2025-08-31T09:48:56.179975Z",
"url": "https://files.pythonhosted.org/packages/39/86/bd9600812f7d6f3725d3eea5a1f2cc03e1dc9b7c0188294f18bff66e5107/trading_contracts-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a0061a6c0cfdbd83d94981c8b7c9537539eb850bb3ea262c1a93d68aaa3d985b",
"md5": "d65e0be9942d1a3ea72f2e8cdd1c87e8",
"sha256": "a229c5a52cdee82934febe837690975263acfa28398780466902966dbd768f1a"
},
"downloads": -1,
"filename": "trading_contracts-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "d65e0be9942d1a3ea72f2e8cdd1c87e8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 11192,
"upload_time": "2025-08-31T09:48:57",
"upload_time_iso_8601": "2025-08-31T09:48:57.294072Z",
"url": "https://files.pythonhosted.org/packages/a0/06/1a6c0cfdbd83d94981c8b7c9537539eb850bb3ea262c1a93d68aaa3d985b/trading_contracts-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-31 09:48:57",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "trading-contracts"
}
JSON