Trading as Git

Every trade in OpenAlice follows a git-like workflow: stage operations, commit with a message, push to execute. This gives you a full audit trail with 8-char commit hashes, the ability to review before execution, and a complete history of every decision.

The Analogy

Git	Trading
`git add`	Stage an order (placeOrder, closePosition, modifyOrder, cancelOrder)
`git commit -m "..."`	Bundle staged operations with a message, get an 8-char hash
`git push`	Execute — send orders to the broker (requires your approval)
`git log`	Review commit history with hashes, timestamps, and results
`git show <hash>`	Inspect a specific commit's operations and outcomes
`git status`	See what's currently staged

Stage

Staging adds operations to the staging area without executing them. Alice stages operations through AI tools:

placeOrder — Stage a new order (buy/sell with order type, quantity, price)
closePosition — Stage closing an existing position (full or partial)
modifyOrder — Stage a change to a pending order
cancelOrder — Stage cancellation of a pending order

Multiple operations can be staged before committing. For example, Alice might stage closing one position and opening another in a single commit.

Commit

Committing bundles all staged operations with a descriptive message and generates an 8-char SHA-256 hash:

commit a3f8c1d2 — "Rotate from AAPL to NVDA based on AI momentum analysis"
  placeOrder: SELL 10 AAPL @ MKT
  placeOrder: BUY 5 NVDA @ LMT 135.00

At this point, nothing has been sent to the broker. The commit is prepared and waiting for approval.

Push

Push is the execution step — and it always requires your explicit approval. When Alice calls tradingPush, the system:

Runs the guard pipeline — Pre-execution safety checks (position size limits, cooldowns, symbol whitelist) evaluate each operation
Dispatches to the broker — Approved operations are sent to the broker API
Records results — Each operation gets a status: submitted, filled, rejected, or cancelled
Takes a snapshot — Account state is captured for equity curve tracking
Saves the commit — The full commit (operations + results + state) is persisted to disk

If any guard rejects an operation, the entire push can be blocked with a reason.

Reject

Instead of pushing, you can reject a commit. This records the operations as user-rejected in the history — Alice sees what you turned down and why, which informs future decisions.

commit b7e2f190 — "[rejected] Aggressive leveraged position — too much risk for current portfolio"
  placeOrder: BUY 100 TQQQ @ MKT (user-rejected)

Sync

After a push, orders may not be immediately filled — exchanges are asynchronous. The tradingSync tool checks the broker for order status updates:

Pending orders that have been filled get their fill price and quantity recorded
Cancelled or expired orders are marked accordingly
A sync commit is created with the updates

commit c4d9e0a1 — "[sync] 2 order(s) updated"
  synced → filled @135.20 (5 filled)

Reading History

Three tools let you inspect the trading history:

tradingLog — List recent commits with hashes, messages, and operation summaries. Filter by symbol to see all activity on a specific asset.
tradingShow — Inspect a specific commit by hash — see every operation, its result, and the account state at that point.
tradingStatus — See what's currently in the staging area and the head commit hash.

Example Conversation

You: Buy 10 shares of AAPL at market price.

Alice: I've staged a market buy order for 10 AAPL shares.

      Staging area:
      • placeOrder: BUY 10 AAPL @ MKT

      Committing as "Buy 10 AAPL — market order per user request"
      Commit hash: a3f8c1d2

      Ready to push. Shall I execute?

You: Yes, go ahead.

Alice: Pushed commit a3f8c1d2.
      • BUY 10 AAPL @ MKT → submitted (orderId: abc123)

      The order has been submitted to Alpaca. Let me sync to check
      if it's been filled...

      Synced: order abc123 filled @ $187.42

Why This Design?

The git workflow solves several problems:

Auditability — Every decision has a hash, timestamp, and message. You can trace exactly what happened and why.
Safety — The push approval step prevents accidental execution. Guards add automated safety checks on top.
Batching — Multiple related operations can be committed together as a logical unit.
Async settlement — The sync step cleanly handles the gap between order submission and fill.
AI learning — Rejected commits teach Alice what you don't want, improving future suggestions.

Search Documentation