aitbc/docs/scenarios/08_marketplace_bidding.md

Marketplace Bidding for hermes Agents

Level: Beginner
Prerequisites: Wallet Basics (Scenario 01), AITBC CLI installed
Estimated Time: 20 minutes
Last Updated: 2026-05-02
Version: 1.0

🧭 Navigation Path:

🏠 Documentation Home → 🎭 Agent Scenarios → You are here

breadcrumb: Home → Scenarios → Marketplace Bidding

---

🎯 See Also:

• 📖 Previous Scenario: 07 AI Job Submission
• 📖 Next Scenario: 09 GPU Listing
• 🤖 Agent SDK: Agent SDK Documentation
• 🏪 Marketplace: Marketplace Documentation

---

📚 Scenario Overview

This scenario demonstrates how hermes agents place bids on the AITBC marketplace to acquire compute resources, storage, and other services.

Use Case

An hermes agent needs marketplace bidding to:

• Acquire GPU compute resources
• Purchase storage space
• Bid on network bandwidth
• Participate in service auctions
• Optimize resource costs

What You'll Learn

• Place bids on marketplace listings
• Monitor bid status
• Win and accept marketplace offers
• Manage bid strategies
• Handle bid failures

Features Combined

• Wallet Operations (Scenario 01)
• Marketplace Operations: Bidding and resource acquisition
• Auction Mechanics: Competitive bidding strategies

---

📋 Prerequisites

Knowledge Required

• Completed Scenario 01 (Wallet Basics)
• Understanding of auction mechanics
• Market pricing concepts

Tools Required

• AITBC CLI installed
• Python 3.13+
• Access to AITBC marketplace
• Wallet with AIT tokens

Setup Required

• Marketplace service running
• Wallet with sufficient balance
• Network connectivity

---

🔧 Step-by-Step Workflow

Step 1: Browse Marketplace Listings

View available resources on the marketplace.

aitbc marketplace list --type gpu

Output:

GPU Marketplace Listings:
ID    Provider        Model         Memory    Price/hr    Status
--------------------------------------------------------------------
1     ait1gpu1...     RTX 4090      24GB      $0.50      open
2     ait1gpu2...     A100          40GB      $1.00      open
3     ait1gpu3...     RTX 3090      24GB      $0.40      open

Step 2: Place a Bid

Submit a bid for a marketplace listing.

aitbc marketplace bid \
  --wallet my-agent-wallet \
  --listing-id 1 \
  --price 0.45 \
  --duration 4

Output:

Bid placed successfully
Bid ID: bid_abc123...
Listing: GPU #1 (RTX 4090)
Your Price: $0.45/hr
Duration: 4 hours
Status: pending

Step 3: Check Bid Status

Monitor the status of your bid.

aitbc marketplace bid-status --bid-id bid_abc123...

Output:

Bid ID: bid_abc123...
Status: accepted
Listing: GPU #1 (RTX 4090)
Provider: ait1gpu1...
Duration: 4 hours
Total Cost: $1.80

Step 4: View Your Bids

List all your active bids.

aitbc marketplace my-bids --wallet my-agent-wallet

Step 5: Cancel a Bid

Cancel a pending bid if needed.

aitbc marketplace cancel-bid \
  --bid-id bid_abc123... \
  --wallet my-agent-wallet

---

💻 Code Examples Using Agent SDK

Example 1: Place Simple Bid

from aitbc_agent_sdk import Agent, AgentConfig

config = AgentConfig(
    name="bidding-agent",
    blockchain_network="mainnet",
    wallet_name="bidding-wallet"
)

agent = Agent(config)
agent.start()

# Place bid on GPU listing
bid = agent.place_marketplace_bid(
    listing_id="1",
    price=0.45,
    duration=4
)

print(f"Bid placed: {bid['bid_id']}")
print(f"Status: {bid['status']}")

Example 2: Automated Bidding Strategy

from aitbc_agent_sdk import Agent, AgentConfig
import asyncio

async def auto_bid_strategy():
    config = AgentConfig(
        name="auto-bidder",
        blockchain_network="mainnet",
        wallet_name="auto-wallet"
    )
    
    agent = Agent(config)
    await agent.start()
    
    # Get marketplace listings
    listings = await agent.get_marketplace_listings(resource_type="gpu")
    
    for listing in listings:
        # Calculate optimal bid price (10% below asking)
        optimal_price = listing['price'] * 0.9
        
        # Place bid if price is acceptable
        if optimal_price >= 0.30:  # Minimum price threshold
            bid = await agent.place_marketplace_bid(
                listing_id=listing['id'],
                price=optimal_price,
                duration=8
            )
            print(f"Bid placed on listing {listing['id']}: ${optimal_price}/hr")

asyncio.run(auto_bid_strategy())

Example 3: Bid Monitoring and Acceptance

from aitbc_agent_sdk import Agent, AgentConfig
import asyncio

async def monitor_and_accept():
    config = AgentConfig(
        name="monitor-agent",
        blockchain_network="mainnet",
        wallet_name="monitor-wallet"
    )
    
    agent = Agent(config)
    await agent.start()
    
    # Place initial bid
    bid = await agent.place_marketplace_bid(
        listing_id="1",
        price=0.45,
        duration=4
    )
    
    # Monitor bid status
    while True:
        status = await agent.get_bid_status(bid['bid_id'])
        print(f"Bid status: {status['status']}")
        
        if status['status'] == 'accepted':
            print(f"Bid accepted! Access credentials: {status['access_credentials']}")
            # Start using the resource
            await agent.use_marketplace_resource(
                bid['bid_id'],
                status['access_credentials']
            )
            break
        elif status['status'] == 'rejected':
            print("Bid rejected, trying higher price...")
            # Place new bid with higher price
            new_bid = await agent.place_marketplace_bid(
                listing_id="1",
                price=0.50,
                duration=4
            )
            bid = new_bid
        elif status['status'] == 'expired':
            print("Bid expired")
            break
        
        await asyncio.sleep(30)

asyncio.run(monitor_and_accept())

---

🎯 Expected Outcomes

After completing this scenario, you should be able to:

• Place bids on marketplace listings
• Monitor bid status
• Implement automated bidding strategies
• Handle bid acceptance and rejection
• Use marketplace resources after winning bids

---

🧪 Validation

Validate this scenario with the shared 3-node harness:

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

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

• Marketplace Service
• GPU Marketplace
• Marketplace Domain

External Resources

• Auction Theory
• Market Mechanisms

Next Scenarios

• 09 GPU Listing - List your own GPU resources
• 21 Compute Provider Agent - Complete compute provider workflow
• 25 Marketplace Arbitrage - Advanced marketplace strategies

---

📊 Quality Metrics

• Structure: 10/10 - Clear bidding workflow
• Content: 10/10 - Comprehensive bidding operations
• Code Examples: 10/10 - Working Agent SDK examples
• Status: Active scenario

---

Last updated: 2026-05-02
Version: 1.0
Status: Active scenario document