oib/aitbc
1
0
Fork 0
Code Issues Pull Requests Actions 6 Packages Projects Releases Wiki Activity
Files
ccedbace5368445bec643edd73f35cee18ceaf35
aitbc/docs/13_tasks/completed_phases/16_api_documentation.md

19 KiB
Raw Blame History

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