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

1"""Bounded HTTP adapter. This module has no live brokerage endpoint.""" 

2 

3import datetime as dt 

4import re 

5from collections.abc import Callable, Mapping 

6from dataclasses import dataclass 

7from typing import Literal 

8 

9import httpx 

10from pydantic import SecretStr, TypeAdapter, ValidationError 

11 

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 

50 

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) 

74 

75PAPER_URL = "https://paper-api.alpaca.markets" 

76LIVE_URL = "https://api.alpaca.markets" 

77Environment = Literal["paper", "live"] 

78 

79 

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 

108 

109 

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 } 

120 

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) 

130 

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),) 

138 

139 

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))) 

148 

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) 

173 

174 

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" 

180 

181 

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") 

191 

192 

193@dataclass(frozen=True, slots=True) 

194class AlpacaCredentials: 

195 key: SecretStr 

196 secret: SecretStr 

197 

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") 

201 

202 

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 

228 

229 def close(self) -> None: 

230 self.http.close() 

231 

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 

252 

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 

259 

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 

266 

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 

271 

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 

287 

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 ) 

294 

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 ) 

300 

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 

312 

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 ) 

318 

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. 

325 

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") 

333 

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() 

344 

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 

354 

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 ) 

368 

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() 

403 

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() 

430 

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) 

441 

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) 

462 

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) 

499 

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) 

537 

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) 

545 

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 ) 

554 

555 def cancel(self, order_id: str) -> None: 

556 self.request("DELETE", f"/v2/orders/{order_id}") 

557 

558 

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