# Basic Trading for hermes Agents **Level**: Beginner **Prerequisites**: Transaction Sending (Scenario 02), AITBC CLI installed **Estimated Time**: 25 minutes **Last Updated**: 2026-05-02 **Version**: 1.0 ## ๐Ÿงญ **Navigation Path:** **๐Ÿ  [Documentation Home](../README.md)** โ†’ **๐ŸŽญ [Agent Scenarios](./README.md)** โ†’ *You are here* **breadcrumb**: Home โ†’ Scenarios โ†’ Basic Trading --- ## ๐ŸŽฏ **See Also:** - **๐Ÿ“– Previous Scenario**: [05 Island Creation](./05_island_creation.md) - **๐Ÿ“– Next Scenario**: [07 AI Job Submission](./07_ai_job_submission.md) - **๐Ÿค– Agent SDK**: [Agent SDK Documentation](../agent-sdk/README.md) - **๐Ÿช Exchange**: [Exchange Documentation](../apps/exchange/README.md) --- ## ๐Ÿ“š **Scenario Overview** This scenario demonstrates how hermes agents perform basic trading operations on the AITBC blockchain, including buying and selling AIT tokens. ### **Use Case** An hermes agent needs trading to: - Exchange AIT tokens for other assets - Profit from market movements - Hedge against price volatility - Participate in liquidity provision ### **What You'll Learn** - Place buy orders - Place sell orders - Check market prices - View order book - Execute trades ### **Features Combined** - **Transaction Sending** (Scenario 02) - **Marketplace Operations**: Order placement and execution - **Exchange Integration**: Trading and price discovery --- ## ๐Ÿ“‹ **Prerequisites** ### **Knowledge Required** - Completed Scenario 02 (Transaction Sending) - Understanding of order books - Basic trading concepts ### **Tools Required** - AITBC CLI installed - Python 3.13+ - Access to AITBC exchange - Wallet with AIT tokens ### **Setup Required** - Exchange service running - Wallet with sufficient balance - Network connectivity ### **Wallet Authentication** For trading operations requiring wallet signing, use one of these methods: ```bash # Interactive prompt (default) aitbc trade buy --from my-wallet --pair AIT/BTC --amount 100 # Password file (recommended for scripts) aitbc trade buy --from my-wallet --pair AIT/BTC --amount 100 --password-file /path/to/password.txt # Environment variable export KEYSTORE_PASSWORD=mypassword aitbc trade buy --from my-wallet --pair AIT/BTC --amount 100 ``` **Security Best Practices:** - Use password files with restricted permissions (chmod 600) - Store password files outside the repository - Avoid hardcoding passwords in scripts --- ## ๐Ÿ”ง **Step-by-Step Workflow** ### **Step 1: Check Market Price** Query the current market price of AIT tokens. ```bash aitbc trade price --pair AIT/USDT ``` Output: ``` Current Price: $1.25 24h Change: +5.2% 24h Volume: 1,250,000 AIT ``` ### **Step 2: View Order Book** Check current buy and sell orders. ```bash aitbc trade orderbook --pair AIT/USDT ``` Output: ``` Bids (Buy Orders) Asks (Sell Orders) -------------------------------------------------- 100 AIT @ $1.24 50 AIT @ $1.26 200 AIT @ $1.23 100 AIT @ $1.27 150 AIT @ $1.22 75 AIT @ $1.28 ``` ### **Step 3: Place a Buy Order** Buy AIT tokens at market price. ```bash aitbc trade buy \ --wallet my-agent-wallet \ --pair AIT/USDT \ --amount 100 \ --type market ``` Output: ``` Buy order executed Amount: 100 AIT Price: $1.25 Total: $125.00 Order ID: order_abc123... ``` ### **Step 4: Place a Limit Sell Order** Sell AIT tokens at a specific price. ```bash aitbc trade sell \ --wallet my-agent-wallet \ --pair AIT/USDT \ --amount 50 \ --price 1.30 \ --type limit ``` ### **Step 5: Check Order Status** Monitor your open orders. ```bash aitbc trade orders --wallet my-agent-wallet ``` Output: ``` Open Orders: Order ID Type Amount Price Status ---------------------------------------------------------- order_abc123... sell 50 AIT $1.30 open ``` --- ## ๐Ÿ’ป **Code Examples Using Agent SDK** ### **Example 1: Simple Buy Order** ```python from aitbc_agent_sdk import Agent, AgentConfig config = AgentConfig( name="trading-agent", blockchain_network="mainnet", wallet_name="trading-wallet" ) agent = Agent(config) agent.start() # Place market buy order order = agent.place_buy_order( pair="AIT/USDT", amount=100, order_type="market" ) print(f"Order placed: {order['order_id']}") print(f"Executed at: ${order['price']}") ``` ### **Example 2: Limit Order with Price Target** ```python from aitbc_agent_sdk import Agent, AgentConfig import asyncio async def place_limit_order(): config = AgentConfig( name="limit-trader", blockchain_network="mainnet", wallet_name="limit-wallet" ) agent = Agent(config) await agent.start() # Place limit sell order order = await agent.place_sell_order( pair="AIT/USDT", amount=50, price=1.30, order_type="limit" ) print(f"Limit order placed: {order['order_id']}") # Monitor order status while True: status = await agent.get_order_status(order['order_id']) print(f"Order status: {status['status']}") if status['status'] in ['filled', 'cancelled']: break await asyncio.sleep(10) asyncio.run(place_limit_order()) ``` ### **Example 3: Automated Trading Strategy** ```python from aitbc_agent_sdk import Agent, AgentConfig import asyncio class TradingBot: def __init__(self, config): self.agent = Agent(config) self.running = False async def start(self): await self.agent.start() self.running = True await self.run_strategy() async def run_strategy(self): """Simple moving average crossover strategy""" while self.running: # Get current price price = await self.agent.get_price("AIT/USDT") # Get moving averages ma_short = await self.agent.get_moving_average("AIT/USDT", period=10) ma_long = await self.agent.get_moving_average("AIT/USDT", period=30) # Trading logic if ma_short > ma_long and not self.position: # Buy signal await self.agent.place_buy_order( pair="AIT/USDT", amount=10, order_type="market" ) self.position = True elif ma_short < ma_long and self.position: # Sell signal await self.agent.place_sell_order( pair="AIT/USDT", amount=10, order_type="market" ) self.position = False await asyncio.sleep(60) async def main(): config = AgentConfig( name="trading-bot", blockchain_network="mainnet", wallet_name="bot-wallet" ) bot = TradingBot(config) await bot.start() asyncio.run(main()) ``` --- ## ๐ŸŽฏ **Expected Outcomes** After completing this scenario, you should be able to: - Place buy and sell orders - Check market prices and order books - Monitor order status - Implement basic trading strategies - Use Agent SDK for trading operations --- ## ๐Ÿงช **Validation** Validate this scenario with the shared 3-node harness: ```bash bash scripts/workflow/44_comprehensive_multi_node_scenario.sh ``` **Node coverage**: - `aitbc1`: genesis / primary node checks - `aitbc`: follower / local node checks - `gitea-runner`: automation / CI node checks **Validation guide**: - [Scenario Validation Guide](./VALIDATION.md) **Expected result**: - Scenario-specific commands complete successfully - Cross-node health checks pass - Blockchain heights remain in sync - Any node-specific step is documented in the scenario workflow --- ## ๐Ÿ”— **Related Resources** ### **AITBC Documentation** - [Exchange Service](../apps/exchange/README.md) - [Trading Service](../apps/trading-service/README.md) - [Trading Engine](../apps/trading-engine/README.md) ### **External Resources** - [Order Book Mechanics](https://www.investopedia.com/terms/o/orderbook.asp) - [Trading Strategies](https://www.investopedia.com/articles/active-trading/092014/trading-strategies-beginners.asp) ### **Next Scenarios** - [25 Marketplace Arbitrage](./25_marketplace_arbitrage.md) - Advanced trading strategies - [27 Cross Chain Trader](./27_cross_chain_trader.md) - Cross-chain trading - [38 Cross Chain Market Maker](./38_cross_chain_market_maker.md) - Professional market making --- ## ๐Ÿ“Š **Quality Metrics** - **Structure**: 10/10 - Clear trading workflow - **Content**: 10/10 - Comprehensive trading operations - **Code Examples**: 10/10 - Working Agent SDK examples - **Status**: Active scenario --- *Last updated: 2026-05-02* *Version: 1.0* *Status: Active scenario document*