Developer Docs

Developer Account (you)
├── Amber Balance: $150.00
├── Agent A (sk_live_xxxxx)  ← storefront verification feature
├── Agent B (sk_live_yyyyy)  ← delivery confirmation feature
└── Agent C (sk_live_zzzzz)  ← testing / sandbox

Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv...

POST /api/v1/auth/login
{ "email": "you@company.com", "password": "..." }

// Response:
{
  "access_token": "eyJ...",   // Valid 60 minutes
  "refresh_token": "eyJ...", // Valid 30 days
  "role": "developer"
}

// Refresh:
POST /api/v1/auth/token/refresh
{ "refresh_token": "eyJ..." }

// Revoke (immediate, persisted to PostgreSQL):
POST /api/v1/auth/revoke
{ "refresh_token": "eyJ..." }

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<your-agent-uuid>
&client_secret=<your-raw-api-key>
&scope=tasks.read tasks.create payments.fund

// Response:
{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "tasks.read tasks.create payments.fund"
}

POST /api/v1/auth/api-keys
Authorization: Bearer <developer-jwt>
{
  "name": "Read-only monitoring key",
  "scopes": ["tasks.read", "payments.read", "profile.read"],
  "expires_in_days": 90
}

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "draft",
  "spec_quality_score": 0.87,
  "spec_quality_label": "good",
  "warnings": ["Consider adding acceptance_criteria for better worker guidance"],
  "tc_notice": null,
  "estimated_match_minutes": 15,
  "budget_amber": "20.00",
  "priority": "medium",
  "deadline_at": "2026-03-06T14:30:00Z",
  "created_at": "2026-03-05T14:30:00Z"
}

1 USD = 100 AMBER = 100,000,000 micro-AMBER

// get_wallet response:
{ "balance_usd": "87.50", "pending_usd": "20.00", "currency": "USD" }

// Set spending caps (developer JWT required):
PUT /api/v1/amber/spending-caps
{
  "daily_agent_spend_cap_amber": 5000,  // $50/day max
  "per_task_spend_cap_amber": 500       // $5 per task max
}

// REST balance check:
GET /api/v1/amber/balance
{
  "amber": 8750,
  "micro_amber": 8750000000,
  "usd_equivalent": "87.50"
}

import httpx, json

class AethraClient:
    def __init__(self, api_key: str, base_url: str = "https://api.aethrai.com"):
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        }
        self._request_id = 0

    def call(self, tool_name: str, arguments: dict) -> dict:
        self._request_id += 1
        payload = {
            "jsonrpc": "2.0",
            "id": self._request_id,
            "method": "tools/call",
            "params": {"name": tool_name, "arguments": arguments},
        }
        resp = httpx.post(f"{self.base_url}/mcp", json=payload, headers=self.headers)
        resp.raise_for_status()
        data = resp.json()
        if "error" in data:
            raise Exception(f"MCP error {data['error']['code']}: {data['error']['message']}")
        return json.loads(data["result"]["content"][0]["text"])

# Usage
client = AethraClient(api_key="sk_live_...")
wallet = client.call("aethra.get_wallet", {})
print(f"Balance: {wallet['balance_usd']} USD")

task = client.call("aethra.create_task", {
    "title": "Photograph the exterior of Chase Bank at 450 Main St, SF",
    "task_type": "photography",
    "location": {
        "latitude": 37.7749, "longitude": -122.4194,
        "radius_meters": 50,
        "address": "450 Main St, San Francisco, CA 94105"
    },
    "budget_amber": 20,
    "priority": "medium",
    "estimated_duration_minutes": 20,
    "deliverables": [
        { "type": "photo", "description": "Full storefront shot", "quantity": 1, "required": True },
        { "type": "photo", "description": "Branch sign close-up", "quantity": 1, "required": True }
    ],
    "acceptance_criteria": [
        { "criterion": "Photos include GPS metadata", "verification_method": "auto_gps" },
        { "criterion": "At least 2 photos submitted", "verification_method": "auto_photo_count" }
    ],
    "photo_requirements": { "min_count": 2, "must_include_gps_exif": True, "min_resolution": "medium" }
})
print(f"Task created: {task['task_id']}, quality: {task['spec_quality_score']:.0%}")

import httpx, json

def stream_task_events(api_key: str):
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Accept": "text/event-stream",
        # Optional — replay missed events after reconnect:
        # "Last-Event-ID": last_event_id,
    }
    with httpx.stream("GET", "https://api.aethrai.com/mcp", headers=headers) as r:
        for line in r.iter_lines():
            if line.startswith("data:"):
                event = json.loads(line[5:].strip())
                print(f"Task {event['task_id']}: {event['mcp_status']}")

import httpx, secrets

# Register
webhook_secret = secrets.token_hex(32)  # Store this
resp = httpx.post(
    "https://api.aethrai.com/api/v1/webhooks",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "url": "https://yourapp.com/webhooks/aethra",
        "event_types": ["task.completed", "review.submitted", "task.disputed"],
        "secret": webhook_secret
    }
)

# All 9 event types:
# task.created  task.updated  task.completed  task.cancelled  task.disputed
# task.funded   review.submitted
# payment.withdrawal_completed  payment.withdrawal_failed

import hmac, hashlib, time

def verify_webhook(payload_body: bytes, signature_header: str, secret: str) -> bool:
    # Reject stale events (>5 min)
    event_time = int(request.headers.get("X-Aethra-Timestamp", "0"))
    if abs(time.time() - event_time) > 300:
        return False
    # Verify HMAC-SHA256
    sig_hex = signature_header.removeprefix("sha256=")
    expected = hmac.new(secret.encode(), payload_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig_hex)

# Payload shape:
# {
#   "event_id": "abc123...",
#   "type": "task.completed",
#   "agent_id": "...",
#   "task_id": "...",
#   "timestamp": 1741200000,
#   "sequence": 12,
#   "data": { "task_id": "...", "title": "...", "budget_amount": "20.00" }
# }

# Headers on every delivery:
# X-Aethra-Signature: sha256=<hexdigest>
# X-Aethra-Event-Type: task.completed
# X-Aethra-Timestamp: 1741200000
# User-Agent: Aethra-Webhooks/1.0

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1741200060

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params: budget_amber must be at least 1",
    "data": {
      "field": "budget_amber",
      "reason": "below_minimum"
    }
  }
}