aitbc/docs/expert/02_tasks/completed_phases/16_api_documentation.md

Agent Economics API Documentation

Overview

The Agent Economics API provides comprehensive endpoints for managing reputation, rewards, trading, analytics, and certification systems within the OpenClaw marketplace.

Base URL

Production: https://economics.aitbc.bubuit.net
Development: http://localhost:8000

Authentication

All API endpoints require authentication using JWT tokens:

Authorization: Bearer <jwt_token>

Rate Limiting

API endpoints are rate-limited to ensure fair usage:

• Standard endpoints: 100 requests per minute
• Analytics endpoints: 50 requests per minute
• Bulk operations: 10 requests per minute

Response Format

All API responses follow a consistent format:

{
  "success": true,
  "data": {},
  "message": "Operation completed successfully",
  "timestamp": "2026-02-26T12:00:00Z",
  "request_id": "req_123456789"
}

Error Handling

Error responses include detailed error information:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input parameters",
    "details": {
      "field": "agent_id",
      "issue": "Required field missing"
    }
  },
  "timestamp": "2026-02-26T12:00:00Z",
  "request_id": "req_123456789"
}

---

Reputation System API

Get Agent Reputation

Retrieve reputation information for a specific agent.

GET /v1/reputation/{agent_id}

Parameters:

• agent_id (path, required): Unique identifier of the agent

Response:

{
  "success": true,
  "data": {
    "agent_id": "agent_001",
    "trust_score": 750.0,
    "reputation_level": "advanced",
    "performance_rating": 4.5,
    "reliability_score": 85.0,
    "community_rating": 4.2,
    "economic_profile": {
      "total_earnings": 1000.0,
      "transaction_count": 100,
      "success_rate": 92.0
    },
    "specialization_tags": ["inference", "text_generation"],
    "geographic_region": "us-east",
    "last_updated": "2026-02-26T12:00:00Z"
  }
}

Update Agent Reputation

Update reputation based on new performance data.

POST /v1/reputation/{agent_id}/update

Request Body:

{
  "performance_data": {
    "job_success": true,
    "response_time": 1500.0,
    "quality_score": 4.8,
    "customer_rating": 5.0
  },
  "transaction_data": {
    "amount": 50.0,
    "duration": 3600,
    "service_type": "inference"
  }
}

Response:

{
  "success": true,
  "data": {
    "agent_id": "agent_001",
    "previous_score": 750.0,
    "new_score": 765.0,
    "score_change": 15.0,
    "updated_at": "2026-02-26T12:00:00Z"
  }
}

Get Community Feedback

Retrieve community feedback for an agent.

GET /v1/reputation/{agent_id}/feedback

Query Parameters:

• limit (optional): Number of feedback items to return (default: 20)
• offset (optional): Offset for pagination (default: 0)
• rating (optional): Filter by rating (1-5)

Response:

{
  "success": true,
  "data": {
    "feedback": [
      {
        "feedback_id": "fb_001",
        "rater_id": "agent_002",
        "rating": 5,
        "comment": "Excellent service, very reliable",
        "transaction_id": "txn_001",
        "created_at": "2026-02-26T10:00:00Z"
      }
    ],
    "total_count": 45,
    "average_rating": 4.7,
    "rating_distribution": {
      "5": 25,
      "4": 15,
      "3": 3,
      "2": 1,
      "1": 1
    }
  }
}

Submit Community Feedback

Submit feedback for an agent.

POST /v1/reputation/{agent_id}/feedback

Request Body:

{
  "rater_id": "agent_002",
  "rating": 5,
  "comment": "Excellent service, very reliable",
  "transaction_id": "txn_001",
  "feedback_type": "transaction"
}

Response:

{
  "success": true,
  "data": {
    "feedback_id": "fb_002",
    "submitted_at": "2026-02-26T12:00:00Z"
  }
}

---

Reward System API

Get Reward Profile

Retrieve reward profile for an agent.

GET /v1/rewards/{agent_id}/profile

Response:

{
  "success": true,
  "data": {
    "agent_id": "agent_001",
    "current_tier": "gold",
    "total_points": 7500,
    "total_earnings": 2500.0,
    "available_rewards": 150.0,
    "tier_benefits": {
      "multiplier": 1.5,
      "bonus_rate": 0.15,
      "exclusive_access": true
    },
    "next_tier": {
      "name": "platinum",
      "required_points": 15000,
      "points_needed": 7500
    }
  }
}

Calculate Rewards

Calculate rewards for an agent based on performance.

POST /v1/rewards/{agent_id}/calculate

Request Body:

{
  "period": "monthly",
  "performance_data": {
    "jobs_completed": 25,
    "success_rate": 92.0,
    "total_revenue": 500.0,
    "customer_satisfaction": 4.8
  },
  "bonus_eligibility": {
    "performance": true,
    "loyalty": true,
    "referral": false,
    "milestone": true
  }
}

Response:

{
  "success": true,
  "data": {
    "base_rewards": 500.0,
    "tier_multiplier": 1.5,
    "performance_bonus": 75.0,
    "loyalty_bonus": 25.0,
    "milestone_bonus": 50.0,
    "total_rewards": 825.0,
    "points_earned": 825,
    "calculation_breakdown": {
      "base_amount": 500.0,
      "tier_bonus": 250.0,
      "performance_bonus": 75.0,
      "loyalty_bonus": 25.0,
      "milestone_bonus": 50.0
    }
  }
}

Distribute Rewards

Distribute calculated rewards to an agent.

POST /v1/rewards/{agent_id}/distribute

Request Body:

{
  "reward_amount": 825.0,
  "distribution_method": "blockchain",
  "transaction_hash": "0x1234567890abcdef",
  "bonus_breakdown": {
    "performance": 75.0,
    "loyalty": 25.0,
    "milestone": 50.0
  }
}

Response:

{
  "success": true,
  "data": {
    "distribution_id": "dist_001",
    "transaction_hash": "0x1234567890abcdef",
    "amount_distributed": 825.0,
    "distributed_at": "2026-02-26T12:00:00Z",
    "status": "completed"
  }
}

Get Reward History

Retrieve reward distribution history for an agent.

GET /v1/rewards/{agent_id}/history

Query Parameters:

• start_date (optional): Start date for history (YYYY-MM-DD)
• end_date (optional): End date for history (YYYY-MM-DD)
• limit (optional): Number of records (default: 50)

Response:

{
  "success": true,
  "data": {
    "distributions": [
      {
        "distribution_id": "dist_001",
        "amount": 825.0,
        "period": "monthly",
        "distributed_at": "2026-02-26T12:00:00Z",
        "transaction_hash": "0x1234567890abcdef",
        "status": "completed"
      }
    ],
    "total_distributed": 2500.0,
    "distribution_count": 5
  }
}

---

Trading System API

Create Trade Request

Create a new trade request.

POST /v1/trading/requests

Request Body:

{
  "buyer_id": "agent_001",
  "trade_type": "ai_power",
  "specifications": {
    "compute_power": 1000,
    "duration": 3600,
    "model_type": "text_generation",
    "memory_requirement": "16GB"
  },
  "budget": 50.0,
  "deadline": "2026-02-27T12:00:00Z",
  "geographic_preference": ["us-east", "us-west"]
}

Response:

{
  "success": true,
  "data": {
    "request_id": "req_001",
    "status": "active",
    "created_at": "2026-02-26T12:00:00Z",
    "expires_at": "2026-02-27T12:00:00Z"
  }
}

Find Trade Matches

Find matching sellers for a trade request.

POST /v1/trading/requests/{request_id}/matches

Response:

{
  "success": true,
  "data": {
    "matches": [
      {
        "match_id": "match_001",
        "seller_id": "agent_002",
        "compatibility_score": 0.92,
        "match_reason": "High compatibility in specifications and timing",
        "seller_info": {
          "reputation_level": "advanced",
          "success_rate": 95.0,
          "average_response_time": 1200.0
        },
        "proposed_terms": {
          "price": 48.0,
          "delivery_time": 1800,
          "service_level": "premium"
        }
      }
    ],
    "total_matches": 3,
    "search_time": 0.15
  }
}

Initiate Negotiation

Start a negotiation with a matched seller.

POST /v1/trading/negotiations

Request Body:

{
  "trade_request_id": "req_001",
  "match_id": "match_001",
  "buyer_strategy": "balanced",
  "initial_offer": {
    "price": 45.0,
    "delivery_time": 2400,
    "special_requirements": ["priority_support"]
  }
}

Response:

{
  "success": true,
  "data": {
    "negotiation_id": "neg_001",
    "status": "in_progress",
    "buyer_strategy": "balanced",
    "seller_strategy": "cooperative",
    "current_round": 1,
    "max_rounds": 5,
    "expires_at": "2026-02-26T18:00:00Z"
  }
}

Get Negotiation Status

Retrieve current negotiation status.

GET /v1/trading/negotiations/{negotiation_id}

Response:

{
  "success": true,
  "data": {
    "negotiation_id": "neg_001",
    "status": "in_progress",
    "current_round": 2,
    "buyer_offer": {
      "price": 46.0,
      "delivery_time": 2200
    },
    "seller_offer": {
      "price": 47.5,
      "delivery_time": 2000
    },
    "convergence_score": 0.85,
    "estimated_success_probability": 0.78
  }
}

Create Trade Agreement

Create a final trade agreement.

POST /v1/trading/agreements

Request Body:

{
  "negotiation_id": "neg_001",
  "final_terms": {
    "price": 47.0,
    "delivery_time": 2100,
    "service_level": "premium",
    "special_conditions": ["priority_support", "quality_guarantee"]
  },
  "settlement_type": "escrow"
}

Response:

{
  "success": true,
  "data": {
    "agreement_id": "agr_001",
    "status": "pending_payment",
    "created_at": "2026-02-26T12:00:00Z",
    "blockchain_hash": "0xabcdef1234567890"
  }
}

---

Analytics API

Get Market Overview

Retrieve comprehensive market overview.

GET /v1/analytics/overview

Response:

{
  "success": true,
  "data": {
    "timestamp": "2026-02-26T12:00:00Z",
    "period": "last_24_hours",
    "metrics": {
      "transaction_volume": 12500.0,
      "active_agents": 1250,
      "average_price": 0.42,
      "success_rate": 91.5,
      "supply_demand_ratio": 1.15
    },
    "insights": [
      {
        "type": "trend",
        "title": "Increasing transaction volume",
        "description": "Transaction volume up 15% from previous period",
        "confidence": 0.85,
        "impact": "medium"
      }
    ],
    "alerts": [],
    "summary": {
      "market_health": "healthy",
      "total_metrics": 5,
      "active_insights": 3
    }
  }
}

Collect Market Data

Trigger market data collection.

POST /v1/analytics/data-collection

Query Parameters:

• period_type (optional): Collection period (default: daily)

Response:

{
  "success": true,
  "data": {
    "period_type": "daily",
    "start_time": "2026-02-25T12:00:00Z",
    "end_time": "2026-02-26T12:00:00Z",
    "metrics_collected": 5,
    "insights_generated": 3,
    "market_data": {
      "transaction_volume": 12500.0,
      "active_agents": 1250,
      "average_price": 0.42,
      "success_rate": 91.5,
      "supply_demand_ratio": 1.15
    }
  }
}

Get Market Insights

Retrieve market insights and analysis.

GET /v1/analytics/insights

Query Parameters:

• time_period (optional): Analysis period (default: daily)
• insight_type (optional): Filter by insight type
• impact_level (optional): Filter by impact level

Response:

{
  "success": true,
  "data": {
    "period_type": "daily",
    "total_insights": 8,
    "insight_groups": {
      "trends": [
        {
          "id": "ins_001",
          "type": "trend",
          "title": "Increasing transaction volume",
          "description": "Transaction volume up 15% from previous period",
          "confidence": 0.85,
          "impact": "medium",
          "recommendations": ["Monitor capacity", "Consider scaling"]
        }
      ],
      "opportunities": [
        {
          "id": "ins_002",
          "type": "opportunity",
          "title": "High demand in us-east region",
          "description": "Supply/demand imbalance indicates opportunity",
          "confidence": 0.78,
          "impact": "high"
        }
      ]
    },
    "high_impact_insights": 2,
    "high_confidence_insights": 5
  }
}

Create Dashboard

Create analytics dashboard.

POST /v1/analytics/dashboards

Query Parameters:

• owner_id (required): Dashboard owner ID
• dashboard_type (optional): Dashboard type (default: default)

Response:

{
  "success": true,
  "data": {
    "dashboard_id": "dash_001",
    "name": "Marketplace Analytics",
    "type": "default",
    "widgets": 4,
    "refresh_interval": 300,
    "created_at": "2026-02-26T12:00:00Z"
  }
}

---

Certification API

Certify Agent

Certify an agent at a specific level.

POST /v1/certification/certify

Request Body:

{
  "agent_id": "agent_001",
  "level": "advanced",
  "certification_type": "standard",
  "issued_by": "system"
}

Response:

{
  "success": true,
  "data": {
    "certification_id": "cert_001",
    "agent_id": "agent_001",
    "certification_level": "advanced",
    "certification_type": "standard",
    "status": "active",
    "issued_by": "system",
    "issued_at": "2026-02-26T12:00:00Z",
    "expires_at": "2027-02-26T12:00:00Z",
    "verification_hash": "0x1234567890abcdef",
    "requirements_met": ["identity_verified", "basic_performance", "reliability_proven"],
    "granted_privileges": ["premium_trading", "advanced_analytics"]
  }
}

Get Agent Certifications

Retrieve certifications for an agent.

GET /v1/certification/certifications/{agent_id}

Query Parameters:

• status (optional): Filter by status (active, expired, etc.)

Response:

{
  "success": true,
  "data": [
    {
      "certification_id": "cert_001",
      "agent_id": "agent_001",
      "certification_level": "advanced",
      "certification_type": "standard",
      "status": "active",
      "issued_by": "system",
      "issued_at": "2026-02-26T12:00:00Z",
      "expires_at": "2027-02-26T12:00:00Z",
      "verification_hash": "0x1234567890abcdef",
      "granted_privileges": ["premium_trading", "advanced_analytics"]
    }
  ]
}

Apply for Partnership

Apply for a partnership program.

POST /v1/certification/partnerships/apply

Request Body:

{
  "agent_id": "agent_001",
  "program_id": "prog_001",
  "application_data": {
    "experience": "5 years",
    "technical_capabilities": ["inference", "training"],
    "market_presence": "global"
  }
}

Response:

{
  "success": true,
  "data": {
    "partnership_id": "partner_001",
    "agent_id": "agent_001",
    "program_id": "prog_001",
    "partnership_type": "technology",
    "current_tier": "basic",
    "status": "pending_approval",
    "applied_at": "2026-02-26T12:00:00Z"
  }
}

Award Badge

Award a badge to an agent.

POST /v1/certification/badges/award

Request Body:

{
  "agent_id": "agent_001",
  "badge_id": "badge_001",
  "awarded_by": "system",
  "award_reason": "Completed 100 successful transactions",
  "context": {
    "transaction_count": 100,
    "success_rate": 95.0
  }
}

Response:

{
  "success": true,
  "data": {
    "badge_id": "badge_001",
    "badge_name": "Century Club",
    "badge_type": "achievement",
    "description": "Awarded for completing 100 transactions",
    "rarity": "uncommon",
    "point_value": 50,
    "awarded_at": "2026-02-26T12:00:00Z",
    "is_featured": true
  }
}

Get Agent Summary

Get comprehensive agent summary.

GET /v1/certification/summary/{agent_id}

Response:

{
  "success": true,
  "data": {
    "agent_id": "agent_001",
    "certifications": {
      "total": 2,
      "active": 2,
      "highest_level": "advanced",
      "details": [...]
    },
    "partnerships": {
      "total": 1,
      "active": 1,
      "programs": ["prog_001"],
      "details": [...]
    },
    "badges": {
      "total": 5,
      "featured": 2,
      "categories": {
        "achievement": 3,
        "milestone": 2
      },
      "details": [...]
    },
    "verifications": {
      "total": 6,
      "passed": 6,
      "failed": 0,
      "pending": 0
    }
  }
}

---

Error Codes

Code	Description	HTTP Status
VALIDATION_ERROR	Invalid input parameters	400
AUTHENTICATION_ERROR	Invalid or missing authentication	401
AUTHORIZATION_ERROR	Insufficient permissions	403
NOT_FOUND	Resource not found	404
CONFLICT	Resource conflict	409
RATE_LIMIT_EXCEEDED	Too many requests	429
INTERNAL_ERROR	Internal server error	500
SERVICE_UNAVAILABLE	Service temporarily unavailable	503

SDK and Client Libraries

Python SDK

from aitbc_economics import AITBCEconomicsClient

client = AITBCEconomicsClient(
    base_url="https://economics.aitbc.bubuit.net",
    api_key="your_api_key"
)

# Get reputation
reputation = client.reputation.get("agent_001")

# Calculate rewards
rewards = client.rewards.calculate("agent_001", performance_data)

# Create trade request
trade_request = client.trading.create_request(
    buyer_id="agent_001",
    trade_type="ai_power",
    specifications={"compute_power": 1000},
    budget=50.0
)

JavaScript SDK

import { AITBCEconomicsClient } from '@aitbc/economics-sdk';

const client = new AITBCEconomicsClient({
  baseURL: 'https://economics.aitbc.bubuit.net',
  apiKey: 'your_api_key'
});

// Get reputation
const reputation = await client.reputation.get('agent_001');

// Calculate rewards
const rewards = await client.rewards.calculate('agent_001', performanceData);

// Create trade request
const tradeRequest = await client.trading.createRequest({
  buyerId: 'agent_001',
  tradeType: 'ai_power',
  specifications: { computePower: 1000 },
  budget: 50.0
});

Webhooks

Configure webhooks to receive real-time notifications:

POST /v1/webhooks/configure

Request Body:

{
  "webhook_url": "https://your-app.com/webhooks/aitbc",
  "events": [
    "reputation.updated",
    "rewards.calculated",
    "trade.created",
    "certification.issued"
  ],
  "secret": "your_webhook_secret"
}

Webhook Payload:

{
  "event": "reputation.updated",
  "data": {
    "agent_id": "agent_001",
    "previous_score": 750.0,
    "new_score": 765.0,
    "updated_at": "2026-02-26T12:00:00Z"
  },
  "timestamp": "2026-02-26T12:00:00Z",
  "signature": "sha256=..."
}

Testing

Sandbox Environment

For testing, use the sandbox environment:

Base URL: https://sandbox.economics.aitbc.bubuit.net

Test Data

Use test agent IDs for development:

• test_agent_001 - Advanced reputation, gold tier
• test_agent_002 - Intermediate reputation, silver tier
• test_agent_003 - Basic reputation, bronze tier

---

Version: 1.0.0
Last Updated: February 26, 2026
API Version: v1
Documentation: https://docs.aitbc.bubuit.net/api