kbot-finance: add read-only Alpaca brokerage adapter#64
Draft
isaacsight wants to merge 1 commit into
Draft
Conversation
Fills the "brokerage API" adapter slot referenced in the kbot-finance issue template and design-partner SOW, following the same five-file pattern (types/client/commands/index + live smoke test) as the Polymarket and EDGAR adapters. - src/adapters/alpaca/: account, positions, and order-status commands against the Alpaca Trading API. Defaults to the paper-trading base URL; no order placement in v1 (read-only, matching the Polymarket adapter's read-first wedge and the SOW's compliance-sign-off gate for live brokerage execution). - src/tools/alpaca-query.ts: wires account/positions/orders queries through the content-addressed envelope, regulatory verifier, and hash-chained audit log, mirroring polymarket-query.ts / edgar-query.ts. - alpaca_query registered in kbotFinanceTools and exported from the package's public surface (src/index.ts, package.json exports). - test/alpaca.test.ts: offline unit tests (normalization, missing- credentials error path, mocked-engine tool wiring, audit-log integrity). - test/alpaca.live.test.ts: live smoke against the real paper-trading API, skipped (not failed) when KBOT_FINANCE_ALPACA_KEY_ID / KBOT_FINANCE_ALPACA_SECRET_KEY aren't configured, in addition to the existing KBOT_FINANCE_OFFLINE gate. - README + issue template updated to list the new adapter.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a new engine adapter to
packages/kbot-financefor the Alpaca brokerage API — account info, open positions, and order status, all read-only. This fills the "brokerage API" adapter slot that was already referenced (but unimplemented) in the kbot-finance issue template and the design-partner SOW.Why
kbot-financeshipped with Polymarket and SEC EDGAR adapters but no brokerage adapter, even though the issue template lists "Adapter request (new engine — pricing, brokerage, data source)" as a category and the design-partner SOW explicitly scopes "wiring of one Customer engine adapter — typically the pricing API, brokerage API, or filing-data source." This closes that gap with a concrete, testable adapter.How
Follows the five-file adapter pattern from
CONTRIBUTING.md(types.ts,client.ts,commands.ts,index.ts, + a live smoke test), using Polymarket as the template:src/adapters/alpaca/— HTTPS client against the Alpaca Trading API, authenticated viaAPCA-API-KEY-ID/APCA-API-SECRET-KEYheaders. Credentials are read fromKBOT_FINANCE_ALPACA_KEY_ID/KBOT_FINANCE_ALPACA_SECRET_KEY, falling back to theAPCA_API_KEY_ID/APCA_API_SECRET_KEYconvention Alpaca's own SDKs use. Defaults to the paper-trading base URL — switching to live requires explicitly settingKBOT_FINANCE_ALPACA_BASE, matching the SOW's "read-only unless compliance officer has signed off" pattern for brokerage engines.getAccount,listPositions,getPosition,listOrders(order status, not submission) — the AI layer cannot move money through this tool, same read-first wedge as the Polymarket adapter's "no trading" stance.src/tools/alpaca-query.ts— wiresaccount/positions/position_by_symbol/ordersmodes through the existing content-addressed envelope, regulatory verifier, and hash-chained audit log, mirroringpolymarket-query.ts/edgar-query.tsexactly.byte_identical_replayable: false(account/position state changes with every fill).alpaca_queryregistered inkbotFinanceTools(so it's automatically exposed via the MCP server and any kbot integration) and exported from the package's public surface.Testing
npm run buildpassesnpm testpasses (58 passed, 5 skipped — Alpaca and Polymarket live-smoke tests skip without credentials/network)npx tsc --noEmitpassesKBOT_FINANCE_OFFLINE=1 npm testpassesnpm run test:live— Alpaca portion requires a free paper-trading key pair from alpaca.markets; skips gracefully (not a failure) without oneNew tests added:
test/alpaca.test.ts— numeric decoding, missing-credentials error path, mocked-engine tool wiring for all four modes, audit-log hash-chain integrity.test/alpaca.live.test.ts— live smoke against the real paper-trading API, gated on bothKBOT_FINANCE_OFFLINEand credential presence.test/kbot-tool.test.ts— extended the tool-registry assertions to coveralpaca_query.Also updated: README (adapters list, layout, public API, env var docs) and the
kbot-financeissue template's component checklist.Generated by Claude Code