Herald Tools API¶

The Herald Network provides a comprehensive API for registering, discovering, and invoking MCP tools with integrated x402 micropayment support.

Base URL¶

http://127.0.0.1:8014/api/

Authentication¶

Most endpoints require a valid Herald token:

Authorization: Bearer $HERALD_TOKEN

Tool Registration¶

POST /api/tools/register¶

Register a new MCP tool in the Herald Network catalog.

Request Body¶

{
  "realm": "image-analyzer",
  "name": "f3l1x/analyze-image",
  "description": "Analyze image content, extract text via OCR",
  "input_schema": {
    "type": "object",
    "properties": {
      "image_url": {"type": "string"},
      "mode": {"type": "string", "enum": ["quick", "detailed"]}
    },
    "required": ["image_url"]
  },
  "internal_action": "analyze_image",
  "price": "0.01",
  "currency": "USDC",
  "price_unit": "per_call",
  "rate_limit": 100
}

Required Fields¶

Optional Fields¶

Response (Success)¶

{
  "success": true,
  "tool_id": "550e8400-e29b-41d4-a716-446655440000",
  "created": true,
  "name": "f3l1x/analyze-image",
  "realm": "image-analyzer",
  "price": "0.01"
}

Example¶

curl -X POST http://127.0.0.1:8014/api/tools/register \
  -H "Authorization: Bearer $HERALD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "realm": "code-review",
    "name": "f3l1x/review-code",
    "description": "AI-powered code review with security analysis",
    "input_schema": {
      "type": "object",
      "properties": {
        "code": {"type": "string"},
        "language": {"type": "string"}
      },
      "required": ["code"]
    },
    "internal_action": "review_code",
    "price": "0.05",
    "currency": "USDC"
  }'

Tool Discovery¶

GET /api/tools¶

List all available tools with optional filtering.

Query Parameters¶

Response¶

{
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "f3l1x/analyze-image",
      "description": "Analyze image content...",
      "input_schema": {...},
      "realm": "image-analyzer",
      "price": "0.01",
      "currency": "USDC",
      "price_unit": "per_call",
      "total_calls": 145,
      "avg_latency_ms": 320
    }
  ],
  "count": 1
}

GET /api/tools/<tool_name>¶

Get detailed tool information including x402 payment requirements.

Response¶

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "f3l1x/analyze-image",
  "description": "Analyze image content...",
  "input_schema": {...},
  "realm": {
    "name": "image-analyzer",
    "port": 8045,
    "status": "online"
  },
  "pricing": {
    "price": "0.01",
    "currency": "USDC",
    "price_unit": "per_call",
    "payment_required_header": "eyJzNDAyVmVyc2lvbiI6IDEsIC4uLn0="
  },
  "stats": {
    "total_calls": 145,
    "total_revenue": "1.45",
    "avg_latency_ms": 320
  }
}

Tool Invocation¶

POST /api/tools/<tool_name>/invoke¶

Invoke a tool with automatic payment handling.

Request Body¶

{
  "arguments": {
    "image_url": "https://example.com/image.png",
    "mode": "quick"
  },
  "caller_realm": "dashboard",
  "payment_signature": "base64_encoded_signature_for_paid_tools"
}

Response (Free Tool)¶

{
  "invocation_id": "550e8400-e29b-41d4-a716-446655440000",
  "message_id": "msg_abc123def456",
  "status": "executing",
  "tool": "f3l1x/analyze-image",
  "realm": "image-analyzer"
}

Response (Payment Required)¶

Status: 402 Payment Required

{
  "error": "PAYMENT_REQUIRED",
  "invocation_id": "550e8400-e29b-41d4-a716-446655440000",
  "payment_required": {
    "amount": "0.01",
    "currency": "USDC",
    "payee_address": "0x...",
    "network": "eip155:8453"
  },
  "payment_required_header": "eyJzNDAyVmVyc2lvbiI6IDEsIC4uLn0="
}

Invocation Status¶

GET /api/invocations/<invocation_id>¶

Get status and results of a tool invocation.

Response (Completed)¶

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tool": "f3l1x/analyze-image",
  "status": "completed",
  "input_data": {...},
  "output_data": {"text": "...", "objects": [...]},
  "started_at": "2026-02-12T18:45:30.123456Z",
  "completed_at": "2026-02-12T18:45:32.456789Z",
  "latency_ms": 2333,
  "payment": {
    "tx_hash": "0x...",
    "amount": "0.01"
  }
}

Status Values¶

Wallet Management¶

POST /api/wallets/register¶

Register a crypto wallet for a realm to receive payments.

{
  "realm": "image-analyzer",
  "address": "0x742d35Cc6634C0532925a3b844Bc8e7595f42263",
  "network": "eip155:8453"
}

GET /api/wallets¶

List all registered wallets for the current realm.

Statistics¶

GET /api/tools/<tool_name>/stats¶

Get detailed statistics for a specific tool.

GET /api/realms/<realm_name>/earnings¶

Get earnings summary for a realm's tools.

GET /api/network/stats¶

Get network-wide statistics.

Error Responses¶

Revenue Split¶

When a tool is invoked with payment:

Next Steps¶

• Creator Guide - Complete guide to creating and monetizing tools
• Validator Guide - How to stake and earn as a validator
• x402 Protocol - Understanding the payment layer