/docs/quickstart-cip · CIP client / consumer

CIP consumer guide — dispatch a cooperative inference task

Cooperative Inference Profile (CIP) lets a proxy node distribute inference tasks across multiple worker nodes on the mesh — for redundancy, quality comparison, or load spreading. This guide is the client/consumer side: the four API calls needed to dispatch and settle a CIP task.

Setting up your own node as a CIP worker (provider side)? See CIP worker setup.

# CIP consumer-gate parameters — spec §2.2, evaluated by the coordinator
# (illustrative — these are protocol parameters, not an SDK config file):
enabled                = true          # opt in to consumer dispatch (off by default)
strategy               = "local-first" # "local-first" | "remote-first" | "balanced"
max_credits_per_task   = 10.0          # per-sub-task credit ceiling
session_credit_budget  = 50.0          # session total ceiling; omit for unlimited
min_reputation         = 0.5           # exclude workers below this score (0.0–1.0)
trusted_peers          = []            # restrict to these node IDs; empty = open mesh
send_sensitive_prompts = false         # §10.2: MUST stay false for high-sensitivity tasks
coordinator_timeout_ms = 30000         # §6: total task budget; worker_timeout = 60% (18 s)

The steps below show the raw HTTP calls the proxy makes internally — useful if you are building a custom coordinator or want to understand what happens under the hood.

Before dispatching a CIP task, check whether your credit balance covers the estimated cost. The directory returns both the estimate and your current balance in one call.

curl -s "https://iicp.network/api/v1/credits/quote?intent=urn:iicp:intent:llm:chat:v1&max_tokens=2000" \
  -H "Authorization: Bearer <your_node_token>"

{
  "quote_id": "q_01HWXYZ...",
  "intent": "urn:iicp:intent:llm:chat:v1",
  "max_tokens": 2000,
  "estimated_credits": 2.0,
  "min_credits": 1.0,
  "max_credits": 3.0,
  "price_per_1000_tokens": 1,
  "currency": "iicp_credits",
  "nodes_quoted": 3,
  "consumer_balance": 15.40,
  "effective_balance": 42.00,
  "balance_scope": "operator_wallet",
  "operator_wallet_balance": 42.00,
  "balance_sufficient": true,
  "quote_expires_at": "2026-05-20T00:05:00Z"
}

Find nodes that have opted in to cooperative inference and meet your quality bar. Filter by min_reputation to exclude low-trust nodes.

curl -s "https://iicp.network/api/v1/discover?view=public&intent=urn:iicp:intent:llm:chat:v1&min_reputation=0.5" \
  -H "Authorization: Bearer <your_node_token>"

{
  "nodes": [
    {
      "node_id": "550e8400-...",
      "endpoint": "https://node.example.com",
      "region": "eu-central",
      "reputation_score": 0.72,
      "reputation_tier": "gold",
      "cip_conformance_level": "CIP-Provider",
      "cip_policy": {
        "allow_remote_inference": true
      },
      "available": true
    }
  ],
  "count": 1
}

Send the CALL directly to the worker adapter. The cip envelope carries cip_role: "worker" so the adapter enforces its CIP policy gate (S.12 §2.1). The trace object carries cip_role: "coordinator" (S.12 §4.2 MUST) so the worker knows the request originates from a CIP coordinator. Supply cip_parent_task_id and cip_session_key for audit traceability and session binding (§10.4).

curl -s -X POST "https://node.example.com/v1/task" \
  -H "Authorization: Bearer <worker_node_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "t_01HWXYZ...",
    "intent": "urn:iicp:intent:llm:chat:v1",
    "payload": {
      "messages": [{"role": "user", "content": "Summarise the IICP protocol in one paragraph."}]
    },
    "constraints": { "timeout_ms": 30000 },
    "auth": { "node_token": "<worker_node_token>" },
    "trace": {
      "trace_id": "trace_XYZ...",
      "cip_role": "coordinator"
    },
    "cip": {
      "cip_role": "worker",
      "cip_parent_task_id": "t_PARENT...",
      "cip_session_key": "sess_ABC123"
    }
  }'

{
  "task_id": "t_01HWXYZ...",
  "status": "success",
  "result": {
    "content": "IICP is an open protocol for intent-based routing..."
  },
  "metrics": { "latency_ms": 1240, "tokens_used": 312 },
  "trace": {
    "cip_role": "worker",
    "cip_session_key": "sess_ABC123"
  },
  "cip_receipt": {
    "task_id": "t_01HWXYZ...",
    "worker_node_id": "550e8400-...",
    "tokens_used": 312,
    "cip_parent_task_id": "t_PARENT...",
    "cip_session_key": "sess_ABC123",
    "nonce": "a3f8c2d1-...",
    "issued_at": "2026-05-22T00:00:00Z",
    "expires_at": "2026-05-22T00:05:00Z",
    "signature": "<HMAC-SHA256 hex, 64 chars>"
  }
}

The worker RESPONSE contains a signed cip_receipt. The coordinator(your proxy) extracts this receipt and forwards it to the directory to credit the worker. The worker itself never contacts the directory — it only includes the receipt in its RESPONSE. The proxy's submit_award() function handles this automatically.

# Forwarded by the coordinator proxy after receiving the worker RESPONSE
curl -s -X POST "https://iicp.network/api/v1/credits/award" \
  -H "Authorization: Bearer <worker_node_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "550e8400-...",
    "task_id": "t_01HWXYZ...",
    "tokens_used": 312,
    "amount": 0.312,
    "cip_parent_task_id": "t_PARENT...",
    "cip_session_key": "sess_ABC123",
    "nonce": "a3f8c2d1-...",
    "expires_at": "2026-05-22T00:05:00Z",
    "response_hash": "<64-char hex SHA-256 of the worker response>",
    "signature": "<HMAC-SHA256 of canonical message>"
  }'

{
  "node_id": "550e8400-...",
  "awarded": 0.312,
  "balance": 0.312,
  "spent": 0.312,
  "spend_reason": null
}

export IICP_CIP_ALLOW_WORKER=true   # opt in to CIP Provider mode
export IICP_MAX_CONCURRENT=4         # cap simultaneous tasks (default 4)

iicp-node serve