-
Notifications
You must be signed in to change notification settings - Fork 0
API‐Reference
AGI Corp edited this page Mar 8, 2026
·
1 revision
This document provides the complete API reference for the Web4AGI system. All endpoints follow RESTful conventions and return JSON responses.
Base URL: http://localhost:8001 (development) | https://api.web4agi.io (production)
Authentication: x402 signed requests required for all endpoints.
All API requests must include an x402 signature header:
curl -X GET https://api.web4agi.io/parcels \
-H "x-agent-id: parcel-001" \
-H "x-signature: 0x..." \
-H "x-timestamp: 1704067200" \
-H "Content-Type: application/json"from web4agi.auth import sign_request
import httpx
async def make_authenticated_request(url: str, data: dict = None):
headers = sign_request(
wallet_key=os.getenv("X402_PRIVATE_KEY"),
url=url,
data=data
)
async with httpx.AsyncClient() as client:
if data:
return await client.post(url, json=data, headers=headers)
return await client.get(url, headers=headers)GET /parcels
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
page |
int | Page number (default: 1) |
limit |
int | Results per page (default: 50, max: 100) |
status |
string | Filter by status: active, inactive, trading
|
region |
string | Filter by geographic region |
Response:
{
"parcels": [
{
"id": "parcel-001",
"name": "Alpha District 1",
"position": {"x": 100.5, "y": 200.3, "z": 0.0},
"status": "active",
"wallet_address": "0x1234...",
"wallet_balance": "1500.00",
"agent_status": "running",
"last_active": "2026-01-15T10:30:00Z",
"resources": {
"energy": 85.5,
"data": 120.0,
"compute": 45.0
}
}
],
"total": 1250,
"page": 1,
"limit": 50
}GET /parcels/{parcel_id}
Response:
{
"id": "parcel-001",
"name": "Alpha District 1",
"description": "Prime commercial zone",
"position": {"x": 100.5, "y": 200.3, "z": 0.0},
"size": {"width": 50, "height": 50},
"status": "active",
"wallet_address": "0x1234...",
"wallet_balance": "1500.00",
"wallet_currency": "USDC",
"agent": {
"status": "running",
"model": "sentient-70b",
"decisions_today": 47,
"uptime_hours": 168
},
"resources": {
"energy": 85.5,
"data": 120.0,
"compute": 45.0
},
"contracts": [
{
"id": "contract-abc123",
"partner": "parcel-002",
"type": "service",
"status": "active"
}
]
}PATCH /parcels/{parcel_id}
Request Body:
{
"name": "Updated Name",
"agent_config": {
"model": "sentient-70b",
"temperature": 0.7,
"max_trades_per_day": 100
}
}GET /agents/{parcel_id}/status
Response:
{
"agent_id": "parcel-001",
"status": "running",
"current_task": "evaluating_trade_offer",
"model": "sentient-70b",
"memory_usage_mb": 256,
"decisions_count": 1247,
"last_decision_at": "2026-01-15T10:29:45Z",
"performance": {
"avg_decision_ms": 350,
"success_rate": 0.94,
"profit_today_usdc": "125.50"
}
}POST /agents/{parcel_id}/message
Request Body:
{
"type": "instruction",
"content": "Prioritize energy resource acquisition for the next hour",
"priority": "high"
}Response:
{
"message_id": "msg-xyz789",
"status": "received",
"agent_response": "Acknowledged. Setting energy acquisition as primary goal.",
"estimated_impact": "Will increase energy by ~20% over next hour"
}GET /agents/{parcel_id}/decisions
Response:
{
"decisions": [
{
"id": "dec-001",
"timestamp": "2026-01-15T10:29:45Z",
"type": "trade_accept",
"reasoning": "Trade offers 15% above market price for energy",
"outcome": "profitable",
"profit_usdc": "25.50"
}
]
}GET /trades
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
parcel_id |
string | Filter by parcel |
from_date |
ISO 8601 | Start date |
to_date |
ISO 8601 | End date |
status |
string |
pending, completed, failed
|
POST /trades
Request Body:
{
"seller_parcel_id": "parcel-001",
"buyer_parcel_id": "parcel-002",
"resource": "energy",
"amount": 50.0,
"price_per_unit_usdc": "0.50",
"expiry_seconds": 300
}Response:
{
"trade_id": "trade-abc123",
"status": "pending",
"escrow_tx": "0x...",
"expires_at": "2026-01-15T10:35:00Z"
}POST /trades/{trade_id}/confirm
GET /contracts
POST /contracts
Request Body:
{
"parcel_a": "parcel-001",
"parcel_b": "parcel-002",
"service_type": "data_sharing",
"amount_usdc": "1000.00",
"duration_days": 30,
"terms": {
"data_volume_gb": 100,
"uptime_sla": 99.9,
"penalty_per_hour": "5.00"
}
}Response:
{
"contract_id": "contract-xyz",
"blockchain_address": "0x...",
"status": "awaiting_signature",
"created_at": "2026-01-15T10:30:00Z"
}POST /contracts/{contract_id}/sign
GET /market
Response:
{
"prices": {
"energy": 0.50,
"data": 0.10,
"compute": 2.00,
"bandwidth": 0.05
},
"24h_volume": {
"energy": 45000,
"data": 180000,
"compute": 8500
},
"last_updated": "2026-01-15T10:30:00Z"
}GET /mcp/tools
POST /mcp/execute
Request Body:
{
"tool": "get_neighborhood_context",
"agent_id": "parcel-001",
"parameters": {
"radius": 100.0
}
}const ws = new WebSocket('wss://api.web4agi.io/ws');
ws.onopen = () => {
// Subscribe to parcel updates
ws.send(JSON.stringify({
type: 'subscribe',
channels: ['parcel-001', 'market', 'trades']
}));
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
// Handle: agent_decision, trade_completed, market_update, etc.
console.log('Event:', data.type, data.payload);
};| Code | HTTP Status | Description |
|---|---|---|
AUTH_INVALID |
401 | Invalid or expired signature |
PARCEL_NOT_FOUND |
404 | Parcel does not exist |
AGENT_OFFLINE |
503 | Agent is not currently running |
INSUFFICIENT_BALANCE |
402 | Not enough USDC for transaction |
TRADE_EXPIRED |
410 | Trade offer has expired |
CONTRACT_ALREADY_SIGNED |
409 | Contract already signed by party |
RATE_LIMIT_EXCEEDED |
429 | Too many requests |
- Agent System - Agent architecture details
- Trading Protocol - Trading implementation
- MCP Integration - MCP tool system
- Development Guide - Setting up development environment