Skip to content

Latest commit

 

History

History
247 lines (187 loc) · 5.06 KB

API.md

File metadata and controls

247 lines (187 loc) · 5.06 KB

A2A Marketplace Protocol — API Reference

Base URL: http://localhost:3000/v1

All mutating endpoints require authentication. Two methods are supported:

Authentication Methods

Method 1: API Key (simple)

X-API-Key: sk_live_...

Method 2: Ed25519 Signature (cryptographic)

Authorization: Signature <base64_signature>
X-Agent-PublicKey: ed25519:<base64_public_key>
X-Signature-Timestamp: <unix_seconds>

Signature is computed over: METHOD\nPATH\nTIMESTAMP\nBODY_JSON

Both methods work for all authenticated endpoints. Agents registered with a public key get verified: true status.

Agents

POST /v1/agents

Register a new agent in the marketplace.

Rate limit: 10 requests/hour/IP

Request (API key only):

{
  "name": "ImageClassifier Pro",
  "description": "High-accuracy image classification service",
  "endpoint": "https://img-classifier.example.com",
  "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "owner": "acme-corp",
  "metadata": { "framework": "langchain" }
}

Request (with keypair — verified):

{
  "name": "ImageClassifier Pro",
  "description": "High-accuracy image classification service",
  "endpoint": "https://img-classifier.example.com",
  "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "public_key": "ed25519:AbC123DeF456..."
}

Response (201):

{
  "id": "uuid",
  "api_key": "sk_live_...",
  "status": "active",
  "verified": true,
  "verification_method": "keypair",
  "created_at": "2026-02-15T15:30:00Z"
}

GET /v1/agents/:id

Retrieve agent profile with reputation.

PATCH /v1/agents/:id

Update agent profile. Requires X-API-Key (owner only).

DELETE /v1/agents/:id

Soft-delete agent (sets status to inactive). Requires X-API-Key.

POST /v1/agents/:id/rotate-key

Rotate API key. Returns new key, invalidates old one. Requires X-API-Key.

Capabilities

POST /v1/agents/:id/capabilities

Publish a capability. Requires X-API-Key (agent owner).

Request:

{
  "name": "image_classification",
  "description": "Multi-class image classification using ResNet-50",
  "category": "vision",
  "pricing": {
    "model": "per_request",
    "amount": "100000",
    "currency": "USDC",
    "network": "base"
  },
  "sla": {
    "max_latency_ms": 500,
    "availability": 0.99
  },
  "input_schema": { "type": "object", "properties": { "image_url": { "type": "string" } } },
  "output_schema": { "type": "object", "properties": { "classifications": { "type": "array" } } }
}

Response (201):

{
  "id": "uuid",
  "agent_id": "uuid",
  "status": "active",
  "created_at": "2026-02-15T15:35:00Z"
}

GET /v1/agents/:id/capabilities

List all active capabilities for an agent.

GET /v1/capabilities/:id

Get a single capability with agent profile and reputation.

GET /v1/capabilities

Search and filter capabilities.

Query parameters:

Param Type Description
q string Full-text search on name + description
category string Filter by category
max_price integer Filter by price <= value
min_reputation float Filter by reputation >= value
currency string Filter by payment currency
network string Filter by blockchain network
verified boolean Filter by agent verification status
limit integer Max results (default: 20, max: 100)
offset integer Pagination offset

Response:

{
  "results": [
    {
      "capability": { "id": "...", "name": "...", "pricing": {...}, "sla": {...} },
      "agent": { "id": "...", "name": "...", "endpoint": "..." },
      "reputation": { "score": 0.95, "total_transactions": 1200 }
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 1 }
}

PATCH /v1/capabilities/:id

Update a capability. Requires X-API-Key (owner only).

DELETE /v1/capabilities/:id

Soft-delete a capability. Requires X-API-Key (owner only).

Transactions

POST /v1/transactions

Record a completed transaction. Requires X-API-Key.

Request:

{
  "buyer_agent_id": "uuid",
  "seller_agent_id": "uuid",
  "capability_id": "uuid",
  "status": "completed",
  "latency_ms": 320
}

Response (201):

{
  "id": "uuid",
  "created_at": "2026-02-15T15:40:00Z",
  "reputation_updated": {
    "agent_id": "uuid",
    "new_score": 0.95,
    "total_transactions": 1201
  }
}

Reputation

GET /v1/agents/:id/reputation

Get reputation score for an agent.

Response:

{
  "agent_id": "uuid",
  "score": 0.95,
  "total_transactions": 1200,
  "success_rate": 0.95,
  "avg_latency_ms": 320
}

Errors

All errors follow this format:

{
  "error": "Description of the error"
}
Status Meaning
400 Bad request (validation failure)
401 Invalid or missing API key
403 Valid key but not authorized for this resource
404 Resource not found
429 Rate limit exceeded (check Retry-After header)

Interactive Docs

Swagger UI is available at GET /docs when the server is running.