tastytrade 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4642b3bfaeb7906f2733b1da34c2bafea177177fb6670f2271b50b720673236
-  data.tar.gz: d65a41b22c7eba317269b454e38188b1e19c504726771d140d72653aa7e7c617
+  metadata.gz: aa2b6fbe38925319fd0577393a7c12f9b852500c85185c51ad73da56b8724422
+  data.tar.gz: 5c650bdbceeb19a32ddcc6e4c610f63d5a0cb8212df4c3875c1544ef91714204
 SHA512:
-  metadata.gz: 7dd6ac7a321ed6d7c6b9519f82988029f5e49515acfff9583d22bba99b2da2ab61666e9054ee232a71afdd3179bcc97c1765e071081722160251ef207340f2d2
-  data.tar.gz: 20b1acf6efba69d72bee9448c39825178701a0e4a20be5de813f1607860fa201b5ed68d2269b2d465fa085bc817d7ffa0ff7f7d89dd68849d197f18463841d51
+  metadata.gz: 9c3a31572d50be8e5bf74aed909e08c0befa1882de0d671c40ad8b9de956ad9c62c1fbededb5bbc5ea883a96aeaee9e1a27c63616c3ef21eaef7e9888a1ea746
+  data.tar.gz: dcf15ae057baeb7aa067c21444efbe481ea6bdc23515ab9f286935d8a406b5fa5d91c0b2e439fa3103bba0c97b76996074d569253a5b7f6671172a0c8a9d4376

data/.claude/commands/plan.md

@@ -0,0 +1,13 @@
+We will implement issue $ARGUMENTS. Please review the issues first to understand what we're doing. You will  
+then spawn multiple concurrent subagents in parallel to do the following:                                 
+
+- one will review the codebase to research the integration points for the new code or code to modify. If  
+the feature has already been implemented they will make note of that.                                     
+- one will review the tastytrade python SDK reference to compare the implementation to fully explain      
+what features we are copying.                                                                             
+- one will review the tastytrade python SDK cli tool reference to fully explain what features we are      
+trying to copy.                                                                                           
+                                                                                                             
+You will then take the output from the subagents to compile an implementation plan and update the todos   
+to fully encapsulate the work down to the smallest possible unit of work. You will not continue until I   
+approve the plan.

data/.claude/commands/release-pr.md

@@ -86,6 +86,18 @@ Create a release PR following Ruby gem best practices.
    After merging this PR:
    1. \`git checkout main && git pull\`
    2. \`bundle exec rake release\`
+   3. Create a GitHub Release:
+      \`\`\`bash
+      gh release create v<VERSION> \\
+        --title "v<VERSION>" \\
+        --generate-notes \\
+        --draft
+      \`\`\`
+   4. Edit the draft release to add a summary section at the top with key highlights
+   5. Publish the release:
+      \`\`\`bash
+      gh release edit v<VERSION> --draft=false
+      \`\`\`
    
    Note: The rake release command will automatically create and push the git tag v<VERSION>"
    ```

data/CHANGELOG.md

@@ -25,6 +25,176 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Security
 - Nothing yet
 
+## [0.3.0] - 2025-08-08
+
+### Added
+- Order time-in-force CLI support (#15)
+  - Added --time-in-force option to `order place` command
+  - Support for DAY and GTC (Good Till Cancelled) order durations
+  - Accepts shorthand aliases: "d" for DAY, "g" or "good_till_cancelled" for GTC
+  - Defaults to DAY order when not specified (backward compatible)
+  - Display time-in-force in order summaries and order history tables
+  - Added TIF column to order list and history displays
+  - Complete test coverage for time-in-force parameter handling
+  - Note: Core Order class already had full DAY/GTC support
+- Comprehensive order validation framework (#14)
+  - OrderValidator class with multi-layer validation checks
+  - Symbol validation via Instruments API
+  - Quantity validation with min/max constraints (1-999,999)
+  - Price validation with tick size rounding
+  - Account permissions validation using TradingStatus
+  - Buying power validation via dry-run API calls
+  - Market hours validation with warnings
+  - Specific error classes (OrderValidationError, InvalidSymbolError, etc.)
+  - Integration into Account#place_order method
+  - Order#validate! and Order#dry_run helper methods
+  - CLI `order place` command with validation support
+  - Dry-run mode for testing orders without submission
+  - Confirmation prompts with buying power impact display
+  - Comprehensive test coverage for all validation scenarios
+- Enhanced order status and history functionality (#13)
+  - Account#get_order_history method for retrieving orders beyond 24 hours
+  - Account#get_order method for fetching individual order details
+  - Date range filtering for order history with from/to parameters
+  - Pagination support for large order history queries
+  - JSON output format for all order CLI commands (--format json)
+  - LiveOrder#to_h method for JSON serialization
+  - `order history` CLI command with comprehensive filtering options
+  - `order get` CLI command for detailed single order information
+  - Enhanced display_order_details method showing fills and timestamps
+  - Complete test coverage for new order history methods
+- Order cancellation and replacement functionality (#12)
+  - LiveOrder model for parsing existing orders from API
+  - OrderStatus module with status constants and validation helpers
+  - Account#get_live_orders method with status/symbol/time filtering
+  - Account#cancel_order method with proper error handling
+  - Account#replace_order method with partial fill support
+  - Custom exceptions for order operations (OrderNotCancellableError, OrderAlreadyFilledError, etc.)
+  - CLI `order` subcommands structure with list/cancel/replace operations
+  - `order list` command with real-time order display and status filtering
+  - `order cancel` command with confirmation prompt and order details
+  - `order replace` command with interactive price/quantity modification
+  - Partial fill tracking with filled/remaining quantity calculations
+  - Order status color coding in CLI output
+  - VCR test configuration with sensitive data filtering
+  - Comprehensive test coverage for all order management features
+  - Integration tests for complete order lifecycle (place, list, modify, cancel)
+  - Renamed existing `order` command to `place` for clarity
+- Account trading status and permissions (#10)
+  - TradingStatus model with 35+ fields matching Python SDK structure
+  - Complete account state tracking (frozen, closed, margin call, PDT status)
+  - Trading permissions for options, futures, cryptocurrency, and short calls
+  - Options trading level parsing and validation
+  - Pattern Day Trader (PDT) status with reset dates and day trade counts
+  - Portfolio margin and risk-reducing mode indicators
+  - Account restrictions detection and listing
+  - Helper methods for permission checking (can_trade_options?, can_trade_futures?, etc.)
+  - CLI `trading_status` command with color-coded warnings
+  - Visual indicators for account restrictions and margin calls
+  - Display of fee schedule and margin calculation type
+  - Full test coverage for all trading status features
+- Claude command for planning multi-issue implementations
+  - `.claude/commands/plan.md` command for structured issue planning
+  - Spawns concurrent subagents to research codebase, Python SDK, and CLI
+  - Compiles comprehensive implementation plans with detailed todos
+  - Requires user approval before proceeding with implementation
+- Transaction history functionality (#8)
+  - Transaction model with comprehensive field support including fees and metadata
+  - Get all transactions with automatic pagination
+  - Filtering by date range, symbol, instrument type, and transaction types
+  - Manual pagination control with page_offset and per_page parameters
+  - Account#get_transactions convenience method
+  - CLI `history` command with table display and filtering options
+  - Grouping transactions by symbol, type, or date
+  - Transaction totals and summaries (credits, debits, fees, net cash flow)
+  - Interactive history menu with date and symbol filtering
+  - Full test coverage for Transaction model and API integration
+- Buying power calculation and monitoring (#9)
+  - Extended AccountBalance model with buying power calculation methods
+  - Buying power usage percentage for equity, derivative, and day trading
+  - Check if sufficient buying power exists for orders
+  - Calculate buying power impact percentage for proposed orders
+  - BuyingPowerEffect model for dry-run order validation
+  - Dry-run orders now return detailed buying power impact information
+  - CLI `buying_power` command to display buying power status
+  - Buying power warnings when placing orders that use >80% of available BP
+  - Interactive confirmation for high buying power usage orders
+  - Integration with order placement workflow (both CLI and interactive)
+  - Comprehensive test coverage for all buying power calculations
+- Order placement functionality for equities (#11)
+  - Order and OrderLeg classes for building orders programmatically
+  - Support for market and limit order types
+  - All four order actions: BUY_TO_OPEN, SELL_TO_CLOSE, SELL_TO_OPEN, BUY_TO_CLOSE
+  - Time in force options: DAY and GTC
+  - Automatic price-effect calculation (Debit for buys, Credit for sells)
+  - Account#place_order method for order submission
+  - OrderResponse model for parsing placement results
+  - Equity instrument class with build_leg helper method
+  - CLI `order` command with options for type, price, action, and dry-run
+  - Interactive order menu with vim navigation for order type and action
+  - Dry-run simulation capability for testing orders
+  - Improved error handling with helpful messages for common scenarios
+  - Comprehensive test coverage for all order functionality
+- CLI positions command (#7)
+  - `positions` command to display account positions in table format
+  - Position filtering options: --symbol, --underlying-symbol, --include-closed
+  - Account selection with --account option
+  - Color-coded P/L display (green for profit, red for loss)
+  - Summary statistics showing total P/L and winners/losers count
+  - Option-specific display formatting (e.g., "AAPL 150C 1/19")
+  - Support for short positions with negative quantity display
+  - Integration with interactive mode and balance submenu
+- Positions formatter for table display
+  - TTY::Table integration for professional formatting
+  - BigDecimal precision for monetary values
+  - Automatic symbol formatting for options
+  - Summary row with position statistics
+- Environment variable authentication support
+  - Session.from_environment class method for creating sessions from env vars
+  - Support for TASTYTRADE_USERNAME, TASTYTRADE_PASSWORD (or TT_ prefixed)
+  - Optional TASTYTRADE_ENVIRONMENT for sandbox/production selection
+  - Optional TASTYTRADE_REMEMBER for automatic session refresh
+  - CLI automatically attempts env var login before prompting
+  - Fallback to interactive login if env var authentication fails
+  - Complete test coverage for all environment variable scenarios
+- Enhanced CLI documentation
+  - Comprehensive login command help with environment variable examples
+  - README documentation for environment variable configuration
+  - Examples for CI/CD and automation use cases
+- CLI login improvements
+  - Added --no-interactive flag to skip interactive mode after login
+  - Useful for scripting and CI/CD environments
+  - Correctly detects environment (sandbox/production) from env vars
+- GitHub Release creation instructions in release workflow
+  - Added `gh release create` command to release-pr.md
+  - Automated release notes generation with --generate-notes flag
+  - Draft release workflow for review before publishing
+
+### Changed
+- Session storage switched from keyring to secure file-based storage
+  - Sessions now stored in ~/.config/tastytrade/credentials/ with 0600 permissions
+  - More reliable across different systems without keyring dependencies
+  - Credentials directory created with 0700 permissions for security
+  - User data (email, username, external_id) now saved with sessions for validation
+
+### Fixed
+- Session persistence issues between command invocations
+  - Fixed session corruption after first command execution
+  - Sessions now properly persist across multiple CLI commands
+  - Removed problematic session validation on load that was causing failures
+- Removed stray error message "Failed to load current account" from positions/balance commands
+  - Error now only displays when DEBUG_SESSION environment variable is set
+- Fixed all test failures related to file-based storage implementation
+  - Updated FileStore tests to properly mock temporary directories
+  - Fixed CLI auth tests to stub environment variable checks
+  - Added missing user attributes to test mocks
+  - Updated session manager tests for new user data saving/loading
+
+### Removed
+- Keyring gem dependency and KeyringStore implementation
+  - Replaced with more reliable file-based credential storage
+  - Eliminates cross-platform keyring compatibility issues
+
 ## [0.2.0] - 2025-08-01
 
 ### Added

data/README.md

@@ -20,9 +20,11 @@ This Ruby gem provides a simple interface to interact with the Tastytrade API, a
 - Secure authentication with Tastytrade API
 - Real-time market data access
 - Account management and portfolio tracking
-- Order placement and management
+- Order placement and management with dry-run support
 - Position monitoring
-- Transaction history
+- Transaction history with filtering and grouping
+- Buying power calculations and monitoring
+- CLI with interactive mode and rich formatting
 
 ## Roadmap
 
@@ -48,6 +50,30 @@ Or install it yourself as:
 gem install tastytrade
 ```
 
+## Configuration
+
+### Environment Variables
+
+The tastytrade gem supports authentication via environment variables, which is recommended for automation and CI/CD environments:
+
+```bash
+# Required for environment variable authentication
+export TASTYTRADE_USERNAME="your_email@example.com"
+export TASTYTRADE_PASSWORD="your_password"
+
+# Optional environment variables
+export TASTYTRADE_ENVIRONMENT="sandbox"  # Use "sandbox" for test environment
+export TASTYTRADE_REMEMBER="true"        # Enable remember token
+
+# Alternative shorter variable names
+export TT_USERNAME="your_email@example.com"
+export TT_PASSWORD="your_password"
+export TT_ENVIRONMENT="sandbox"
+export TT_REMEMBER="true"
+```
+
+When environment variables are set, the CLI will automatically use them for authentication without prompting for credentials.
+
 ## Usage
 
 ### Authentication
@@ -75,19 +101,165 @@ session.authenticated? # => true
 
 The gem includes a command-line interface for common operations:
 
+#### Authentication
+
 ```bash
-# Login to your account
+# Login to your account interactively
 tastytrade login
 
 # Login with remember option for automatic session refresh
 tastytrade login --remember
 
+# Login using environment variables (recommended for automation)
+export TASTYTRADE_USERNAME="your_email@example.com"
+export TASTYTRADE_PASSWORD="your_password"
+tastytrade login
+
+# Or use shorter variable names
+export TT_USERNAME="your_email@example.com"
+export TT_PASSWORD="your_password"
+tastytrade login
+
+# Use sandbox environment for testing
+export TASTYTRADE_ENVIRONMENT="sandbox"
+tastytrade login
+
+# Enable remember token via environment
+export TASTYTRADE_REMEMBER="true"
+tastytrade login
+
+```
+
+#### Account Operations
+
+```bash
 # View account balances
 tastytrade balance
 
 # View balances for all accounts
 tastytrade balance --all
 
+# View account positions
+tastytrade positions
+
+# Filter positions by symbol
+tastytrade positions --symbol AAPL
+
+# Filter positions by underlying symbol (for options)
+tastytrade positions --underlying-symbol SPY
+
+# View trading status and permissions
+tastytrade trading_status
+
+# View status for specific account
+tastytrade trading_status --account 5WT0001
+
+# Include closed positions
+tastytrade positions --include-closed
+```
+
+#### Transaction History
+
+```bash
+# View all transactions
+tastytrade history
+
+# Filter by date range
+tastytrade history --start-date 2024-01-01 --end-date 2024-12-31
+
+# Filter by symbol
+tastytrade history --symbol AAPL
+
+# Group transactions by symbol, type, or date
+tastytrade history --group-by symbol
+tastytrade history --group-by type
+tastytrade history --group-by date
+
+# Limit number of transactions
+tastytrade history --limit 50
+
+# Combine filters
+tastytrade history --symbol AAPL --start-date 2024-01-01 --group-by date
+```
+
+#### Buying Power Status
+
+```bash
+# View buying power status
+tastytrade buying_power
+
+# View buying power for specific account
+tastytrade buying_power --account 5WX12345
+```
+
+#### Order Management
+
+##### Order Placement
+
+```bash
+# Place a limit buy order
+tastytrade order place --symbol AAPL --action buy_to_open --quantity 100 --price 150.50
+
+# Place a market order
+tastytrade order place --symbol SPY --action buy_to_open --quantity 10 --type market
+
+# Sell to close a position
+tastytrade order place --symbol AAPL --action sell_to_close --quantity 100 --price 155.00
+
+# Dry-run validation (validate without placing)
+tastytrade order place --symbol MSFT --action buy_to_open --quantity 50 --price 300 --dry-run
+
+# Skip confirmation prompt
+tastytrade order place --symbol TSLA --action buy_to_open --quantity 10 --price 200 --skip-confirmation
+
+# Supported actions:
+# - buy_to_open (bto)
+# - sell_to_close (stc) 
+# - sell_to_open (sto)
+# - buy_to_close (btc)
+
+# Note: Orders that would use >80% of buying power will prompt for confirmation
+```
+
+##### Order Status and History
+
+```bash
+# List all live orders (open + last 24 hours)
+tastytrade order list
+
+# List orders with filters
+tastytrade order list --status Live
+tastytrade order list --symbol AAPL
+tastytrade order list --all  # Show for all accounts
+
+# Output orders in JSON format
+tastytrade order list --format json
+
+# Get historical orders (beyond 24 hours)
+tastytrade order history
+tastytrade order history --status Filled
+tastytrade order history --symbol AAPL
+tastytrade order history --from 2024-01-01 --to 2024-12-31
+tastytrade order history --limit 100
+tastytrade order history --format json
+
+# Get details for a specific order
+tastytrade order get ORDER_ID
+tastytrade order get ORDER_ID --format json
+
+# Cancel an order
+tastytrade order cancel ORDER_ID
+tastytrade order cancel ORDER_ID --account 5WX12345
+
+# Replace/modify an order
+tastytrade order replace ORDER_ID  # Interactive prompts for new price/quantity
+tastytrade order replace ORDER_ID --price 155.00
+tastytrade order replace ORDER_ID --quantity 50
+```
+
+#### Account Management
+
+```bash
 # List all accounts
 tastytrade accounts
 
@@ -129,11 +301,21 @@ balance.cash_balance # => BigDecimal("10000.50")
 balance.net_liquidating_value # => BigDecimal("42001.00")
 balance.equity_buying_power # => BigDecimal("20000.00")
 balance.available_trading_funds # => BigDecimal("12000.00")
+balance.day_trading_buying_power # => BigDecimal("40000.00")
+balance.derivative_buying_power # => BigDecimal("20000.00")
 
 # Check buying power usage
 balance.buying_power_usage_percentage # => BigDecimal("40.00")
+balance.derivative_buying_power_usage_percentage # => BigDecimal("25.00")
 balance.high_buying_power_usage? # => false (checks if > 80%)
 
+# Check if sufficient buying power for order
+balance.sufficient_buying_power?(15000) # => true
+balance.sufficient_buying_power?(15000, buying_power_type: :derivative) # => true
+
+# Calculate buying power impact
+balance.buying_power_impact_percentage(15000) # => BigDecimal("75.00")
+
 # Calculate totals
 balance.total_equity_value # => BigDecimal("30001.00")
 balance.total_derivative_value # => BigDecimal("4500.00")
@@ -168,6 +350,245 @@ positions.each do |position|
 end
 ```
 
+### Order Placement
+
+```ruby
+# Create an order leg for buying stock
+leg = Tastytrade::OrderLeg.new(
+  action: Tastytrade::OrderAction::BUY_TO_OPEN,
+  symbol: 'AAPL',
+  quantity: 100
+)
+
+# Create a market order
+market_order = Tastytrade::Order.new(
+  type: Tastytrade::OrderType::MARKET,
+  legs: leg
+)
+
+# Create a limit order
+limit_order = Tastytrade::Order.new(
+  type: Tastytrade::OrderType::LIMIT,
+  legs: leg,
+  price: 150.50  # Will be converted to BigDecimal
+)
+
+# Place the order
+response = account.place_order(session, market_order)
+
+# Dry run (simulate order without placing)
+response = account.place_order(session, limit_order, dry_run: true)
+
+# Check order response
+puts response.order_id           # => "123456"
+puts response.status             # => "Filled"
+
+# Dry run orders return a BuyingPowerEffect object
+if response.buying_power_effect.is_a?(Tastytrade::Models::BuyingPowerEffect)
+  bp_effect = response.buying_power_effect
+  puts bp_effect.buying_power_change_amount # => BigDecimal("15050.00")
+  puts bp_effect.buying_power_usage_percentage # => BigDecimal("75.25")
+  puts bp_effect.exceeds_threshold?(80) # => false
+  puts bp_effect.debit? # => true
+else
+  puts response.buying_power_effect # => BigDecimal("-15050.00")
+end
+
+puts response.warnings           # => [] or warning messages
+```
+
+### Order Management
+
+```ruby
+# Get live orders (open orders + orders from last 24 hours)
+orders = account.get_live_orders(session)
+
+# Filter orders by status
+live_orders = account.get_live_orders(session, status: "Live")
+filled_orders = account.get_live_orders(session, status: "Filled")
+
+# Filter orders by symbol
+aapl_orders = account.get_live_orders(session, underlying_symbol: "AAPL")
+
+# Filter by time range
+recent_orders = account.get_live_orders(session,
+  from_time: Time.now - 86400,  # Last 24 hours
+  to_time: Time.now
+)
+
+# Work with order details
+orders.each do |order|
+  puts order.id                  # => "12345"
+  puts order.status              # => "Live"
+  puts order.underlying_symbol   # => "AAPL"
+  puts order.order_type          # => "Limit"
+  puts order.price               # => BigDecimal("150.50")
+  
+  # Check order capabilities
+  puts order.cancellable?        # => true
+  puts order.editable?           # => true
+  puts order.terminal?           # => false
+  puts order.working?            # => true
+  
+  # Check fill status
+  puts order.remaining_quantity  # => 100
+  puts order.filled_quantity     # => 0
+  
+  # Work with order legs
+  order.legs.each do |leg|
+    puts leg.symbol              # => "AAPL"
+    puts leg.action              # => "Buy"
+    puts leg.quantity            # => 100
+    puts leg.remaining_quantity  # => 100
+    puts leg.partially_filled?   # => false
+  end
+end
+
+# Cancel an order
+account.cancel_order(session, "12345")
+
+# Replace an order with new parameters
+new_order = Tastytrade::Order.new(
+  type: Tastytrade::OrderType::LIMIT,
+  legs: leg,
+  price: 155.00  # New price
+)
+response = account.replace_order(session, "12345", new_order)
+```
+
+### Order Validation
+
+The SDK includes comprehensive order validation to prevent submission errors and ensure orders meet all requirements before reaching the API.
+
+#### Validation Features
+
+```ruby
+# Orders are automatically validated before submission
+order = Tastytrade::Order.new(
+  type: Tastytrade::OrderType::LIMIT,
+  legs: leg,
+  price: 150.00
+)
+
+# Validation happens automatically when placing orders
+begin
+  response = account.place_order(session, order)
+rescue Tastytrade::OrderValidationError => e
+  puts "Validation failed:"
+  e.errors.each { |error| puts "  - #{error}" }
+end
+
+# You can also validate manually
+order.validate!(session, account)  # Raises if invalid
+
+# Or perform a dry-run validation
+dry_run_response = order.dry_run(session, account)
+puts dry_run_response.buying_power_effect
+puts dry_run_response.warnings
+```
+
+#### Validation Rules
+
+The following validations are performed:
+
+1. **Symbol Validation**
+   - Verifies symbol exists and is tradeable
+   - Checks instrument type compatibility
+
+2. **Quantity Validation**
+   - Minimum quantity: 1
+   - Maximum quantity: 999,999
+   - No fractional shares (whole numbers only)
+
+3. **Price Validation**
+   - Price must be positive for limit orders
+   - Price is rounded to appropriate tick size
+   - Price reasonableness checks
+
+4. **Account Permissions**
+   - Validates trading permissions for instrument type
+   - Checks for account restrictions (frozen, closing-only, etc.)
+   - Verifies options/futures permissions if applicable
+
+5. **Buying Power Validation**
+   - Ensures sufficient buying power via dry-run
+   - Warns if order uses >50% of available buying power
+   - Checks margin requirements
+
+6. **Market Hours Validation**
+   - Warns about market orders outside regular hours
+   - Alerts for weekend submissions
+
+#### Validation Errors
+
+```ruby
+# Specific validation error types
+Tastytrade::OrderValidationError     # General validation failure
+Tastytrade::InvalidSymbolError       # Symbol doesn't exist
+Tastytrade::InsufficientBuyingPowerError  # Not enough buying power
+Tastytrade::AccountRestrictedError   # Account has restrictions
+Tastytrade::InvalidQuantityError     # Quantity out of range
+Tastytrade::InvalidPriceError        # Price validation failure
+Tastytrade::MarketClosedError        # Market is closed
+```
+
+#### Using the OrderValidator
+
+```ruby
+# Direct use of OrderValidator for custom validation
+validator = Tastytrade::OrderValidator.new(session, account, order)
+
+# Perform full validation
+validator.validate!  # Raises if invalid
+
+# Or just dry-run validation
+dry_run_response = validator.dry_run_validate!
+
+# Check warnings and errors
+puts validator.warnings  # Array of warning messages
+puts validator.errors    # Array of error messages
+```
+
+#### Skip Validation (Use with Caution)
+
+```ruby
+# Skip validation when you're certain the order is valid
+response = account.place_order(session, order, skip_validation: true)
+```
+
+### Transaction History
+
+```ruby
+# Get all transactions
+transactions = account.get_transactions(session)
+
+# Filter transactions
+transactions = account.get_transactions(session,
+  start_date: Date.new(2024, 1, 1),
+  end_date: Date.new(2024, 12, 31),
+  symbol: 'AAPL',
+  transaction_types: ['Trade'],
+  per_page: 100
+)
+
+# Work with transactions
+transactions.each do |transaction|
+  puts transaction.symbol               # => "AAPL"
+  puts transaction.transaction_type     # => "Trade"
+  puts transaction.transaction_sub_type # => "Buy"
+  puts transaction.quantity             # => BigDecimal("100")
+  puts transaction.price                # => BigDecimal("150.00")
+  puts transaction.value                # => BigDecimal("-15000.00")
+  puts transaction.net_value            # => BigDecimal("-15007.00")
+  puts transaction.executed_at          # => Time object
+  
+  # Fee breakdown
+  puts transaction.commission           # => BigDecimal("5.00")
+  puts transaction.clearing_fees        # => BigDecimal("1.00")
+  puts transaction.regulatory_fees      # => BigDecimal("0.50")
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies and verify your environment is configured correctly.