---
id: "0088c"
title: "Trading: broker interface + adapter paper"
status: pendiente
type: feature
domain:
  - trading
scope: multi-app
priority: alta
depends: []
blocks: []
related: []
created: 2026-05-17
updated: 2026-05-17
tags: []
---
# 0088c — Trading: broker interface + adapter paper

**Status:** pendiente
**Created:** 2026-05-14
**Type:** feature
**Parent:** 0088
**Depends:** 0088a, 0088d (necesita ledger funcionando para reflejar fills)
**Blocks:** 0088g, 0088h, 0088l (broker real)

## Problema

No hay contrato comun broker. Sin contrato, cada broker se cablearia ad-hoc en cada app. El primer adapter debe ser `paper` — simula fills usando OHLCV + modelo de slippage simple — y debe ser totalmente intercambiable con un broker real bajo la misma interfaz.

## Piezas

1. Tipo Python `BrokerInterface` (protocolo / abstract class) con metodos minimos:
   - `place_order(order: OrderIntent) -> OrderAck`
   - `cancel_order(client_order_id: str) -> None`
   - `get_positions() -> list[Position]`
   - `get_balance() -> Balance`
   - `stream_fills() -> Iterator[Fill]`
2. Tipos del registry: `OrderIntent`, `OrderAck`, `Fill`, `Position`, `Balance` en `python/types/finance/`.
3. Funciones puras de soporte:
   - `make_client_order_id_py_finance(strategy_id, intent_ts, intent_payload) -> str` (idempotencia).
   - `simulate_fill_paper_py_finance(intent, ohlcv_snapshot, slippage_model) -> Fill`.
4. Adapter `broker_paper`:
   - `broker_paper_place_order_py_finance` (impure: persiste intent + simula fill via OHLCV ultimo).
   - `broker_paper_get_balance_py_finance` (impure: lee ledger).
   - `broker_paper_get_positions_py_finance` (impure: lee ledger).
   - `broker_paper_stream_fills_py_finance` (impure: tail del ledger).
5. Tag `broker` aplicado a interface + adapter functions. Pagina madre `docs/capabilities/broker.md`.

## Aceptacion

- Demo en `analysis/strategy_lab` (o test): `place_order → fill → reconciliacion ledger → balance updated`.
- `BrokerInterface` implementable por un broker real sin tocar el codigo de la app que lo consume.
- `client_order_id` deterministico: misma intent reproduce misma id (idempotencia comprobada).

## No-objetivos

- Adapters binance/IB/alpaca reales — sale a 0088l.
- Order book matching realista (FIFO/queue position). El paper inicial usa slippage simple sobre OHLCV.