HTTP mode — implement IICP without binary framing

5-command quickstart

These five curl calls walk through the full HTTP mode lifecycle. Replace MY_ENDPOINT with your node's public URL.

curl -s -X POST https://iicp.network/api/v1/register \
  -H "Content-Type: application/json" \
  -H "X-IICP-Version: 1.9" \
  -d '{
    "endpoint": "https://MY_ENDPOINT",
    "region": "eu-central",
    "capabilities": [{
      "intent": "urn:iicp:intent:llm:chat:v1",
      "models": ["llama-3-8b"],
      "max_tokens": 4096
    }],
    "limits": { "max_concurrent": 4, "tokens_per_min": 10000 }
  }'

Save the returned node_id and node_token — both are required for subsequent calls. The directory verifies your endpoint is reachable before accepting the registration.

# Run this on a 30-second cron or in a loop
curl -s -X POST https://iicp.network/api/v1/heartbeat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <node_token>" \
  -H "X-IICP-Version: 1.9" \
  -d '{
    "node_id": "<node_id>",
    "load": 0.4,
    "queue_depth": 2,
    "error_rate_1m": 0.0
  }'

Nodes not seen for 90 seconds are marked unavailable and disappear from discovery results. A 30-second heartbeat interval gives three missed-heartbeat tolerance before being dropped.

# Your node must respond to GET /iicp/health with 200 OK
# Minimal implementation (Python):
from http.server import BaseHTTPRequestHandler, HTTPServer
import json

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path == '/iicp/health':
            body = json.dumps({"status":"ok","load":0.4}).encode()
            self.send_response(200)
            self.send_header('Content-Type','application/json')
            self.send_header('X-IICP-Version','1.9')
            self.end_headers()
            self.wfile.write(body)

HTTPServer(('0.0.0.0', 9484), Handler).serve_forever()

The directory probes GET /iicp/health during registration and periodically after. Return HTTP 200 — any body is accepted. The X-IICP-Version: 1.9 header advertises your conformance level.

# The IICP proxy routes tasks to your node as:
POST /v1/task
Authorization: Bearer <node_token>
Content-Type: application/json

{
  "task_id": "t-abc123",
  "intent": "urn:iicp:intent:llm:chat:v1",
  "payload": {
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 512
  }
}

# Your node responds:
HTTP 200 OK
Content-Type: application/json

{
  "task_id": "t-abc123",
  "output": { "choices": [{"message": {"role":"assistant","content":"Hi!"}}] },
  "usage": { "prompt_tokens": 10, "completion_tokens": 5 }
}

Authenticate the incoming node_token on every request. Return 401 if the token is missing or invalid. The adapter handles this automatically; if you are implementing a custom node, verify using constant-time comparison (bcrypt or HMAC).

# Check that your node appears in discovery results
curl -s 'https://iicp.network/api/v1/discover?view=public&intent=urn:iicp:intent:llm:chat:v1' \
  | python3 -m json.tool

HTTP ↔ native message mapping

Each native binary frame type (defined in the binary framing specification) has an HTTP counterpart for the base operations. Transport-specific behavior and negotiated profiles, including task-result streaming, require their own contracts.

CLOSE (0x07) is implicit: any 4xx/5xx response or connection close. CONTROL (0x0B) and ADVERTISE (0x0C) map to /v1/control and /api/v1/node/{node_id} respectively — not required for Phase 1–3.

Required headers

FAQ