Coverage for src/copytrading_engine/execution/adapters/alpaca/broker.py: 84%
305 statements
« prev ^ index » next coverage.py v7.16.2, created at 2026-11-16 16:55 +0000
« prev ^ index » next coverage.py v7.16.2, created at 2026-11-16 16:55 +0000
1"""Bounded HTTP adapter. This module has no live brokerage endpoint."""
3import datetime as dt
4import re
5from collections.abc import Callable, Mapping
6from dataclasses import dataclass
7from typing import Literal
9import httpx
10from pydantic import SecretStr, TypeAdapter, ValidationError
12from copytrading_engine.execution.adapters.alpaca.models import (
13 decode_account,
14 decode_asset,
15 decode_bars,
16 decode_broker_order,
17 decode_calendar,
18 decode_crypto_quote,
19 decode_daily_bars,
20 decode_orders,
21 decode_portfolio_history,
22 decode_positions,
23 decode_quote,
24)
25from copytrading_engine.execution.application.ports import (
26 BrokerError,
27 BrokerResponseError,
28 BrokerRestoreEvidence,
29 BrokerTimelineEvent,
30)
31from copytrading_engine.execution.domain.ledger_state import LedgerSnapshot
32from copytrading_engine.execution.domain.market import (
33 Account,
34 Asset,
35 Bar,
36 BrokerOrder,
37 CalendarDay,
38 DailyBar,
39 DailyRange,
40 EquityHistory,
41 HistoryRange,
42 HistoryWindow,
43 Position,
44 Quote,
45 QuoteFeed,
46)
47from copytrading_engine.execution.domain.orders import OrderRequest
48from copytrading_engine.execution.domain.sessions import ET
49from copytrading_engine.shared.symbols import is_crypto, path_symbol
51_ORDERS_PAGE_SIZE = 500
52# Alpaca serves intraday points for at most 30 days, so longer ranges use daily points. Coins
53# trade around the clock, so intraday ranges ask for every hour, not only the stock sessions.
54_HISTORY_PARAMS: dict[HistoryRange, dict[str, str]] = {
55 "day": {"period": "1D", "timeframe": "1Min", "intraday_reporting": "continuous"},
56 "week": {"period": "1W", "timeframe": "15Min", "intraday_reporting": "continuous"},
57 "month": {"period": "1M", "timeframe": "1D"},
58 "three_months": {"period": "3M", "timeframe": "1D"},
59 "year": {"period": "1A", "timeframe": "1D"},
60}
61_MAX_BAR_PAGES = 5
62# Calendar days a daily chart reaches back: the range, plus about fifty trading days before it
63# so the 20 and 50 day averages start filled.
64_WARM_UP_DAYS = 75
65_DAILY_DAYS: dict[DailyRange, int] = {"month": 31, "six_months": 183, "year": 366}
66_DAILY_PAGE_SIZE = 1000
67_ACTIVITIES_PAGE_SIZE = 100
68_MAX_RESTORE_ORDER_PAGES = 100
69_MAX_RESTORE_ACTIVITY_PAGES = 100
70_BROKER_TIMESTAMP = re.compile(
71 r"^(?P<seconds>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})"
72 r"(?P<fraction>\.\d{1,9})?(?P<zone>Z|[+-]\d{2}:\d{2})$"
73)
75PAPER_URL = "https://paper-api.alpaca.markets"
76LIVE_URL = "https://api.alpaca.markets"
77Environment = Literal["paper", "live"]
80def _timeline_event(identifier: str, timestamp: object) -> BrokerTimelineEvent:
81 if not identifier or not isinstance(timestamp, str):
82 raise BrokerResponseError()
83 match = _BROKER_TIMESTAMP.fullmatch(timestamp)
84 if match is None: 84 ↛ 85line 84 didn't jump to line 85 because the condition on line 84 was never true
85 raise BrokerResponseError()
86 fraction = match.group("fraction")
87 fraction_digits = fraction[1:] if fraction else ""
88 fraction_nanoseconds = int(fraction_digits.ljust(9, "0")) if fraction_digits else 0
89 microseconds, submicrosecond_nanoseconds = divmod(fraction_nanoseconds, 1_000)
90 zone = "+00:00" if match.group("zone") == "Z" else match.group("zone")
91 normalized = f"{match.group('seconds')}.{microseconds:06d}{zone}"
92 try:
93 occurred_at = dt.datetime.fromisoformat(normalized)
94 except ValueError:
95 raise BrokerResponseError() from None
96 if occurred_at.tzinfo is None or occurred_at.utcoffset() is None: 96 ↛ 97line 96 didn't jump to line 97 because the condition on line 96 was never true
97 raise BrokerResponseError()
98 resolution_nanoseconds = 10 ** (9 - len(fraction_digits)) if fraction_digits else 1_000_000_000
99 try:
100 return BrokerTimelineEvent(
101 identifier=identifier,
102 occurred_at=occurred_at.astimezone(dt.UTC),
103 resolution_nanoseconds=resolution_nanoseconds,
104 submicrosecond_nanoseconds=submicrosecond_nanoseconds,
105 )
106 except ValueError:
107 raise BrokerResponseError() from None
110def _activity_timeline_events(
111 identifier: str,
112 item: dict[str, object],
113) -> tuple[BrokerTimelineEvent, ...]:
114 activity_type = item.get("activity_type")
115 activity_kind = item.get("type")
116 is_trade = activity_type in {"FILL", "PARTIAL_FILL"} or activity_kind in {
117 "fill",
118 "partial_fill",
119 }
121 if is_trade:
122 precise: list[BrokerTimelineEvent] = []
123 for field in ("transaction_time", "created_at"):
124 timestamp = item.get(field)
125 if timestamp is not None: 125 ↛ 123line 125 didn't jump to line 123 because the condition on line 125 was always true
126 precise.append(_timeline_event(identifier, timestamp))
127 if not precise: 127 ↛ 128line 127 didn't jump to line 128 because the condition on line 127 was never true
128 raise BrokerResponseError()
129 return tuple(precise)
131 # The activity cursor filters on record creation time. For non-trading
132 # activities, `date` is an occurrence/settlement date and cannot establish
133 # whether the record was created before the snapshot cut.
134 created_at = item.get("created_at")
135 if created_at is None:
136 raise BrokerResponseError()
137 return (_timeline_event(identifier, created_at),)
140def _order_timeline_events(
141 identifier: str,
142 status: str,
143 raw_order: dict[str, object],
144) -> tuple[BrokerTimelineEvent, ...]:
145 events: list[BrokerTimelineEvent] = []
146 for field in ("created_at", "submitted_at", "updated_at"):
147 events.append(_timeline_event(identifier, raw_order.get(field)))
149 terminal_time_by_status = {
150 "filled": "filled_at",
151 "canceled": "canceled_at",
152 "cancelled": "canceled_at",
153 "expired": "expired_at",
154 "rejected": "failed_at",
155 "failed": "failed_at",
156 "replaced": "replaced_at",
157 }
158 required_terminal_time = terminal_time_by_status.get(status.lower())
159 terminal_fields = (
160 "filled_at",
161 "expired_at",
162 "canceled_at",
163 "failed_at",
164 "replaced_at",
165 )
166 if required_terminal_time is not None and raw_order.get(required_terminal_time) is None: 166 ↛ 167line 166 didn't jump to line 167 because the condition on line 166 was never true
167 raise BrokerResponseError()
168 for field in terminal_fields:
169 timestamp = raw_order.get(field)
170 if timestamp is not None:
171 events.append(_timeline_event(identifier, timestamp))
172 return tuple(events)
175def quote_feed(now: dt.datetime) -> QuoteFeed:
176 """Alpaca's overnight venue quotes from 20:00 to 4:00 New York time; at those hours IEX still
177 shows the last close, so a price read from it would be hours old."""
178 hour = now.astimezone(ET).hour
179 return "overnight" if hour >= 20 or hour < 4 else "iex"
182def quote_feeds(now: dt.datetime) -> tuple[QuoteFeed, ...]:
183 """The feeds worth asking at this hour, the venue trading first. In regular hours IEX is live.
184 Outside them IEX barely quotes, so its latest quote can be the close hours ago; the
185 consolidated tape, which the free plan gets 15 minutes late, is asked too and the newer
186 quote wins."""
187 new_york = now.astimezone(ET)
188 regular = dt.time(9, 30) <= new_york.time() < dt.time(16) and new_york.weekday() < 5
189 feed = quote_feed(now)
190 return (feed,) if regular and feed == "iex" else (feed, "delayed_sip")
193@dataclass(frozen=True, slots=True)
194class AlpacaCredentials:
195 key: SecretStr
196 secret: SecretStr
198 def __post_init__(self) -> None:
199 if not self.key.get_secret_value() or not self.secret.get_secret_value(): 199 ↛ 200line 199 didn't jump to line 200 because the condition on line 199 was never true
200 raise ValueError("Alpaca credentials are required")
203class AlpacaBroker:
204 def __init__(
205 self,
206 credentials: AlpacaCredentials,
207 environment: Environment,
208 *,
209 transport: httpx.BaseTransport | None = None,
210 clock: Callable[[], dt.datetime] = lambda: dt.datetime.now(dt.UTC),
211 ) -> None:
212 if environment not in {"paper", "live"}:
213 raise ValueError("Choose Alpaca paper or live explicitly")
214 self.http = httpx.Client(
215 base_url=PAPER_URL if environment == "paper" else LIVE_URL,
216 headers={
217 "APCA-API-KEY-ID": credentials.key.get_secret_value(),
218 "APCA-API-SECRET-KEY": credentials.secret.get_secret_value(),
219 },
220 timeout=10,
221 follow_redirects=False,
222 transport=transport,
223 )
224 self.environment = environment
225 self.now = clock
226 # The account's valuation currency, from its first read: it never changes.
227 self._currency: str | None = None
229 def close(self) -> None:
230 self.http.close()
232 def request(
233 self,
234 method: str,
235 path: str,
236 *,
237 params: Mapping[str, str | int] | None = None,
238 json: object = None,
239 ) -> object:
240 try:
241 response = self.http.request(method, path, params=params, json=json)
242 except httpx.HTTPError:
243 raise BrokerError() from None
244 if response.is_error or response.is_redirect:
245 raise BrokerError(response.status_code, alpaca_reason(response))
246 if response.status_code == 204: 246 ↛ 247line 246 didn't jump to line 247 because the condition on line 246 was never true
247 return None
248 try:
249 return response.json()
250 except ValueError:
251 raise BrokerResponseError() from None
253 @staticmethod
254 def decode[T](model: type[T], value: object) -> T:
255 try:
256 return TypeAdapter(model).validate_python(value)
257 except ValidationError, TypeError:
258 raise BrokerResponseError() from None
260 @staticmethod
261 def decode_normalized[T](decoder: Callable[[object], T], value: object) -> T:
262 try:
263 return decoder(value)
264 except ValidationError, TypeError:
265 raise BrokerResponseError() from None
267 def account(self) -> Account:
268 account = self.decode_normalized(decode_account, self.request("GET", "/v2/account"))
269 self._currency = account.currency
270 return account
272 def equity_history(self, window: HistoryWindow) -> EquityHistory:
273 params: dict[str, str | int] = dict(_HISTORY_PARAMS[window.range])
274 if window.range == "day":
275 # A day is the whole New York day from midnight; today's ends now.
276 day = window.day or self.now().astimezone(ET).date()
277 params["start"] = dt.datetime.combine(day, dt.time(), ET).isoformat()
278 history = self.decode_normalized(
279 lambda value: decode_portfolio_history(value, window),
280 self.request("GET", "/v2/account/portfolio/history", params=params),
281 )
282 if window.range == "day" and window.day is None:
283 # Over a weekend Alpaca's history still counts from Thursday's close while the
284 # account's day change counts from Friday's; today is measured as the account does.
285 history = history.model_copy(update={"base_value": self.account().last_equity})
286 return history
288 def asset(self, symbol: str) -> Asset:
289 # A coin's pair is asked for without its slash (BTCUSD); Alpaca answers with the pair.
290 return self.decode_normalized(
291 decode_asset,
292 self.request("GET", f"/v2/assets/{path_symbol(symbol)}"),
293 )
295 def calendar(self, date: str) -> tuple[CalendarDay, ...]:
296 return self.decode_normalized(
297 decode_calendar,
298 self.request("GET", "/v2/calendar", params={"start": date, "end": date}),
299 )
301 def positions(self) -> tuple[Position, ...]:
302 # Alpaca's position response may omit currency; the account's valuation unit stands in,
303 # while an explicit position unit wins. The account is read for it only once.
304 currency = self._currency or self.account().currency
305 result = self.decode_normalized(
306 lambda value: decode_positions(value, account_currency=currency),
307 self.request("GET", "/v2/positions"),
308 )
309 if len({position.symbol for position in result}) != len(result): 309 ↛ 310line 309 didn't jump to line 310 because the condition on line 309 was never true
310 raise BrokerResponseError()
311 return result
313 def open_orders(self) -> tuple[BrokerOrder, ...]:
314 return self.decode_normalized(
315 decode_orders,
316 self.request("GET", "/v2/orders", params={"status": "open", "limit": 500}),
317 )
319 def restore_evidence(
320 self,
321 snapshot: LedgerSnapshot,
322 created_at: dt.datetime,
323 ) -> BrokerRestoreEvidence:
324 """Collect read-only broker facts needed to reconcile a restored snapshot.
326 Historical terminal orders remain validated archive evidence. Fresh order
327 lookups are limited to buys backing currently open owned lots; querying all
328 terminal history would make old archives depend on broker retention and
329 produce work proportional to every order the account ever placed.
330 """
331 if created_at.tzinfo is None or created_at.utcoffset() is None: 331 ↛ 332line 331 didn't jump to line 332 because the condition on line 331 was never true
332 raise ValueError("Restore snapshot time must be timezone-aware")
334 account = self.account()
335 positions = self.decode_normalized(
336 lambda value: decode_positions(value, account_currency=account.currency),
337 self.request("GET", "/v2/positions"),
338 )
339 if len({position.symbol for position in positions}) != len(positions): 339 ↛ 340line 339 didn't jump to line 340 because the condition on line 339 was never true
340 raise BrokerResponseError()
341 open_orders = self.open_orders()
342 if len(open_orders) >= _ORDERS_PAGE_SIZE: 342 ↛ 343line 342 didn't jump to line 343 because the condition on line 342 was never true
343 raise BrokerResponseError()
345 known_orders: dict[str, BrokerOrder] = {}
346 for lot_id, lot in snapshot.lots.items(): 346 ↛ 347line 346 didn't jump to line 347 because the loop on line 346 never started
347 if lot.remaining_qty <= 0:
348 continue
349 for entry in lot.entries(lot_id):
350 found = self.lookup(entry)
351 if found is None:
352 raise BrokerResponseError()
353 known_orders[entry] = found
355 order_events = self._orders_after(created_at)
356 activity_events = self._activity_events_after(created_at)
357 return BrokerRestoreEvidence(
358 account=account,
359 environment=self.environment,
360 positions={position.symbol: position.qty for position in positions},
361 open_order_client_ids=tuple(order.client_order_id for order in open_orders),
362 known_orders=known_orders,
363 snapshot_started_at=created_at.astimezone(dt.UTC),
364 order_events_near_snapshot=order_events,
365 activity_events_near_snapshot=activity_events,
366 complete=True,
367 )
369 def _orders_after(self, created_at: dt.datetime) -> tuple[BrokerTimelineEvent, ...]:
370 params: dict[str, str | int] = {
371 "status": "all",
372 "limit": _ORDERS_PAGE_SIZE,
373 "after": (created_at - dt.timedelta(seconds=1)).isoformat(),
374 "direction": "asc",
375 }
376 observed: list[BrokerTimelineEvent] = []
377 seen: set[str] = set()
378 for _ in range(_MAX_RESTORE_ORDER_PAGES):
379 raw_page = self.request("GET", "/v2/orders", params=params)
380 page = self.decode_normalized(
381 decode_orders,
382 raw_page,
383 )
384 if not isinstance(raw_page, list) or len(raw_page) != len(page): 384 ↛ 385line 384 didn't jump to line 385 because the condition on line 384 was never true
385 raise BrokerResponseError()
386 for raw_order, order in zip(raw_page, page, strict=True):
387 if order.id in seen: 387 ↛ 388line 387 didn't jump to line 388 because the condition on line 387 was never true
388 raise BrokerResponseError()
389 seen.add(order.id)
390 if not isinstance(raw_order, dict): 390 ↛ 391line 390 didn't jump to line 391 because the condition on line 390 was never true
391 raise BrokerResponseError()
392 observed.extend(_order_timeline_events(order.id, order.status, raw_order))
393 if len(page) < _ORDERS_PAGE_SIZE:
394 return tuple(observed)
395 cursor = page[-1].id
396 params = {
397 "status": "all",
398 "limit": _ORDERS_PAGE_SIZE,
399 "direction": "asc",
400 "after_order_id": cursor,
401 }
402 raise BrokerResponseError()
404 def _activity_events_after(self, created_at: dt.datetime) -> tuple[BrokerTimelineEvent, ...]:
405 params: dict[str, str | int] = {
406 "after": (created_at - dt.timedelta(seconds=1)).isoformat(),
407 "direction": "asc",
408 "page_size": _ACTIVITIES_PAGE_SIZE,
409 }
410 observed: list[BrokerTimelineEvent] = []
411 seen: set[str] = set()
412 for _ in range(_MAX_RESTORE_ACTIVITY_PAGES):
413 result = self.request("GET", "/v2/account/activities", params=params)
414 if not isinstance(result, list): 414 ↛ 415line 414 didn't jump to line 415 because the condition on line 414 was never true
415 raise BrokerResponseError()
416 page: list[BrokerTimelineEvent] = []
417 for item in result:
418 if not isinstance(item, dict) or not isinstance(item.get("id"), str): 418 ↛ 419line 418 didn't jump to line 419 because the condition on line 418 was never true
419 raise BrokerResponseError()
420 activity_id = item["id"]
421 if not activity_id or activity_id in seen: 421 ↛ 422line 421 didn't jump to line 422 because the condition on line 421 was never true
422 raise BrokerResponseError()
423 seen.add(activity_id)
424 page.extend(_activity_timeline_events(activity_id, item))
425 observed.extend(page)
426 if len(page) < _ACTIVITIES_PAGE_SIZE:
427 return tuple(observed)
428 params["page_token"] = page[-1].identifier
429 raise BrokerResponseError()
431 def lookup(self, client_id: str) -> BrokerOrder | None:
432 try:
433 result = self.request(
434 "GET", "/v2/orders:by_client_order_id", params={"client_order_id": client_id}
435 )
436 except BrokerError as exc:
437 if exc.status == 404:
438 return None
439 raise
440 return self.decode_normalized(decode_broker_order, result)
442 def quote(self, symbol: str) -> Quote:
443 """A coin's quote from the crypto feed, which quotes at every hour. A stock's is the
444 freshest among the feeds worth asking now (`quote_feeds`): the venue trading must answer;
445 a later feed that fails only leaves its quote out."""
446 if is_crypto(symbol):
447 result = self.request(
448 "GET",
449 "https://data.alpaca.markets/v1beta3/crypto/us/latest/quotes",
450 params={"symbols": symbol},
451 )
452 return self.decode_normalized(lambda value: decode_crypto_quote(value, symbol), result)
453 primary, *others = quote_feeds(self.now())
454 quotes = [self._quote(symbol, primary)]
455 for feed in others:
456 try:
457 quotes.append(self._quote(symbol, feed))
458 except BrokerError, BrokerResponseError:
459 continue
460 oldest = dt.datetime.min.replace(tzinfo=dt.UTC)
461 return max(quotes, key=lambda quote: quote.timestamp or oldest)
463 def bars(self, symbol: str) -> tuple[Bar, ...]:
464 """Five-minute bars of the symbol's latest session, oldest first; none when it has not
465 traded in the last few days. A stock's come from IEX, the feed every account has."""
466 # The last few New York days reach back over a weekend or a holiday.
467 start = dt.datetime.combine(
468 self.now().astimezone(ET).date() - dt.timedelta(days=4), dt.time(), ET
469 )
470 params: dict[str, str | int] = {
471 "timeframe": "5Min",
472 "start": start.isoformat(),
473 "limit": 1000,
474 "sort": "asc",
475 }
476 if is_crypto(symbol):
477 url = "https://data.alpaca.markets/v1beta3/crypto/us/bars"
478 params["symbols"] = symbol
479 else:
480 url = f"https://data.alpaca.markets/v2/stocks/{symbol}/bars"
481 params["feed"] = "iex"
482 bars: list[Bar] = []
483 for _ in range(_MAX_BAR_PAGES): 483 ↛ 495line 483 didn't jump to line 495 because the loop on line 483 didn't complete
484 result = self.request("GET", url, params=params)
485 if not isinstance(result, dict): 485 ↛ 486line 485 didn't jump to line 486 because the condition on line 485 was never true
486 raise BrokerResponseError()
487 listed = result.get("bars")
488 if is_crypto(symbol):
489 listed = listed.get(symbol) if isinstance(listed, dict) else None
490 bars.extend(self.decode_normalized(decode_bars, listed or []))
491 token = result.get("next_page_token")
492 if not token:
493 break
494 params["page_token"] = token
495 if not bars:
496 return ()
497 session = bars[-1].at.astimezone(ET).date()
498 return tuple(bar for bar in bars if bar.at.astimezone(ET).date() == session)
500 def daily_bars(self, symbol: str, period: DailyRange) -> tuple[DailyBar, ...]:
501 """Daily bars of the symbol over the period and the weeks before it, oldest first, with
502 splits folded in so a split is no gap in the chart. A stock's come from IEX, the feed
503 every account has, so its volumes are that feed's."""
504 start = dt.datetime.combine(
505 self.now().astimezone(ET).date()
506 - dt.timedelta(days=_DAILY_DAYS[period] + _WARM_UP_DAYS),
507 dt.time(),
508 ET,
509 )
510 params: dict[str, str | int] = {
511 "timeframe": "1Day",
512 "start": start.isoformat(),
513 "limit": _DAILY_PAGE_SIZE,
514 "sort": "asc",
515 }
516 if is_crypto(symbol):
517 url = "https://data.alpaca.markets/v1beta3/crypto/us/bars"
518 params["symbols"] = symbol
519 else:
520 url = f"https://data.alpaca.markets/v2/stocks/{symbol}/bars"
521 params["feed"] = "iex"
522 params["adjustment"] = "split"
523 bars: list[DailyBar] = []
524 for _ in range(_MAX_BAR_PAGES): 524 ↛ 536line 524 didn't jump to line 536 because the loop on line 524 didn't complete
525 result = self.request("GET", url, params=params)
526 if not isinstance(result, dict): 526 ↛ 527line 526 didn't jump to line 527 because the condition on line 526 was never true
527 raise BrokerResponseError()
528 listed = result.get("bars")
529 if is_crypto(symbol):
530 listed = listed.get(symbol) if isinstance(listed, dict) else None
531 bars.extend(self.decode_normalized(decode_daily_bars, listed or []))
532 token = result.get("next_page_token")
533 if not token:
534 break
535 params["page_token"] = token
536 return tuple(bars)
538 def _quote(self, symbol: str, feed: QuoteFeed) -> Quote:
539 result = self.request(
540 "GET",
541 f"https://data.alpaca.markets/v2/stocks/{symbol}/quotes/latest",
542 params={"feed": feed},
543 )
544 return self.decode_normalized(lambda value: decode_quote(value, feed), result)
546 def submit(self, order: OrderRequest) -> BrokerOrder:
547 # Never retry a POST: a timeout or malformed response can follow acceptance.
548 return self.decode_normalized(
549 decode_broker_order,
550 self.request(
551 "POST", "/v2/orders", json=order.model_dump(mode="json", exclude_none=True)
552 ),
553 )
555 def cancel(self, order_id: str) -> None:
556 self.request("DELETE", f"/v2/orders/{order_id}")
559def alpaca_reason(response: httpx.Response) -> str | None:
560 """Alpaca's `message` for a refused request ("insufficient buying power"), printable and at
561 most 200 characters; None when the body is not Alpaca's error shape."""
562 try:
563 body = response.json()
564 except ValueError:
565 return None
566 message = body.get("message") if isinstance(body, dict) else None
567 if not isinstance(message, str):
568 return None
569 text = " ".join("".join(c for c in message if c.isprintable()).split())
570 return text[:200] or None