# TradeLock AI Integration Spec

Purpose: machine-readable integration requirements for AI coding assistants.

> Public onboarding has been consolidated into `/docs/getting-started` and `/docs/manager-api-reference`. This file remains available as a prompt-friendly raw reference.

## 1) Base settings

- Base URL: `https://tradelock.net/api`
- Auth header: `X-Trader-Api-Key: <API_KEY>`
- Content type: `application/json`

## 2) Recommended integration order

1. Implement quantity mode first (`trade_type` + `quantity`).
2. Use `POST /logTrade` for explicit control.
3. Add quick path support for `POST /quick-trade`.
4. Add status polling via `GET /trade-status`.

## 3) Endpoint contracts

### A) `POST /logTrade` (recommended for robust integrations)

Required fields (quantity mode):
- `user_strategy_name` (string)
- `asset` (string)
- `trade_type` (`buy` | `sell`)
- `quantity` (number > 0)
- `idempotency_key` (string, 8..200)

Optional sizing alternative:
- `allocation_percent` (0..100) instead of quantity mode
- `allocation_percent: 10` means target 10% of strategy equity in that asset
- `allocation_percent: 0` means close the position (target zero exposure)

Response:
- `200`: trade logged immediately
- `202`: trade queued for market-open processing
- `4xx`: validation/auth/conflict

### B) `POST /quick-trade` (minimal payload)

Common qty payload:
```json
{
  "ticker": "AAPL",
  "qty": 25,
  "side": "buy",
  "strategy": "Momentum Core",
  "idempotency_key": "signal-20260223-001"
}
```

Accepted aliases include:
- ticker/symbol/asset
- side/action/trade_type
- qty/quantity
- strategy/strategy_name/user_strategy_name

### C) `GET /trade-status`

Query params:
- `strategyName`
- `tradeId`

Use after receiving `tradeId` or `pendingTradeId`.

## 4) Unique Trade ID rules (`idempotency_key`)

Treat this as **Unique Trade ID** in your app.

Rules:
1. Retry same signal/request => reuse same value.
2. New signal => generate new value.
3. Same value + different payload => conflict response.

Recommended source:
- existing signal/order ID from client system.
- fallback to generated UUID-based value if no signal ID exists.

## 5) Live-trade field restrictions

Do not send CSV-only fields for live submissions:
- `reported_date`
- `user_reported_price`
- `reference_price`
- `allocation_reference_price`

## 6) Retry policy requirements

- Retry only on network errors and 5xx.
- Do not blind-retry 4xx validation errors.
- Keep timeout finite (10s-30s typical).

## 7) Output requirements for AI-generated code

Generated integration should include:
1. Function to build/reuse `idempotency_key`.
2. Submission function for qty mode.
3. Optional `%` sizing path via comment or toggle.
4. Structured logging of request/response/error.
5. Optional status follow-up call.

## 8) Starter prompt for any AI assistant

```text
Integrate TradeLock trade submission into my system.

Use:
- Base URL: https://tradelock.net/api
- Auth: X-Trader-Api-Key header
- Quantity mode first using POST /logTrade
- Required fields: user_strategy_name, asset, trade_type, quantity, idempotency_key

Idempotency rules:
- Treat idempotency_key as Unique Trade ID
- Retry same signal => reuse same value
- New signal => generate new value

Also include:
- optional commented allocation_percent alternative
- safe retries on network/5xx only
- concise error handling and logging
- optional GET /trade-status support

Return production-ready code for my stack.
```