Credits API reference

GET/api/v1/credits/balance

Returns the credit balance for the authenticated node. The quickest way is the CLI: iicp-node credits (auto-selects your node; v0.7.40+). The API endpoint below is useful for scripts and custom dashboards.

Auth

Authorization: Bearer <node_token>

Request

curl -sf https://iicp.network/api/v1/credits/balance \
  -H "Authorization: Bearer <node_token>"

Response 200

{
  "node_id": "550e8400-...",
  "balance": 38.5,
  "unit": "credit",
  "tokens_per_credit": 1000
}

GET/api/v1/credits/summary

Lifetime income / spending / balance for the authenticated node — earned, spent, and what's left, in one call. reconciles is an integrity check: it is true only when balance == total_earned − total_spent. A tampered or inconsistent ledger surfaces as false — so the numbers are self-checking, not taken on trust.

Operator wallet. When the node is delegation-bound to an operator identity, the response also carries an operator_wallet object that rolls up balance, earned, spent, transaction count and reconcile status across allof the operator's non-archived nodes — one wallet keyed by your identity, backed by per-node audit rows. It is nullwhen the node is not yet operator-bound; the operator's raw public key is never returned.

Auth

Authorization: Bearer <node_token>

Request

curl -sf https://iicp.network/api/v1/credits/summary \
  -H "Authorization: Bearer <node_token>"

Response 200

{
  "node_id": "550e8400-...",
  "total_earned": 142.5,
  "total_spent": 38.25,
  "balance": 104.25,
  "tx_count": 27,
  "reconciles": true,
  "unit": "credit",
  "tokens_per_credit": 1000,
  "operator_wallet": {        // null when the node is not operator-bound
    "total_balance": 263.75,  // SUM across all the operator's non-archived nodes
    "total_earned": 302.0,
    "total_spent": 38.25,
    "tx_count": 82,
    "node_count": 3,
    "reconciles": true,
    "operator_fingerprint": "4f93aa10b2c7"
  }
}

GET/api/v1/credits/quote

CIP pre-flight — estimates the credit cost for a task before dispatch (S.12 §8). The coordinator calls this before dispatching to check if the consumer has sufficient balance. Quote is valid for 60 seconds.

Auth

Authorization: Bearer <node_token> (coordinator node token)

Query parameters

Request

curl -sf 'https://iicp.network/api/v1/credits/quote?intent=urn:iicp:intent:llm:chat:v1&max_tokens=500' \
  -H "Authorization: Bearer <node_token>"

Response 200

{
  "quote_id": "q_AbC123xyz789",
  "estimated_credits": 0.5,
  "min_credits": 0.5,
  "max_credits": 0.5,
  "price_per_1000_tokens": 1.0,
  "nodes_quoted": 7,
  "quote_expires_at": "2026-05-22T15:01:00Z",
  "currency": "iicp_credits",
  "consumer_balance": 38.5,
  "effective_balance": 263.75,
  "balance_scope": "operator_wallet",
  "operator_wallet_balance": 263.75,
  "balance_sufficient": true
}

If balance_sufficient: false, the consumer identity does not have enough effective credits to cover the estimated cost. Operator-bound nodes use operator_wallet; unbound nodes use their node-local balance. The coordinator should not dispatch. min_credits and max_credits bracket the per-node price spread (they collapse to one value when a single rate applies).

POST/api/v1/credits/award

Submits a signed CIPWorkerReceipt to credit tokens to a worker node. The coordinator calls this after receiving a CIP RESPONSE from a worker. The receipt HMAC signature is verified before crediting.

Auth

Authorization: Bearer <coordinator_node_token>

Request body

Response 200

{
  "node_id": "550e8400-...",
  "awarded": 0.5,
  "balance": 39.0,
  "spent": 0.5,
  "spend_scope": "operator_wallet",
  "debit_count": 1,
  "spend_reason": null
}

balance is the new post-award balance. spent is the amount debited from the querying identity. Operator-bound consumers spend from their pooled wallet; unbound consumers spend from the node-local balance.spend_reason is null on success or an insufficient-balance reason if the debit failed (award still succeeds — debit is SHOULD, not MUST per S.12 v0.6.11). All receipt-validation failures return HTTP 422 with error code IICP-E027.

Nonce lifecycle

1. Worker generates a 32+ char random hex nonce when building the receipt.
2. Nonce is included in the HMAC canonical message and in the receipt body.
3. Directory rejects any nonce already seen within a 24-hour window (atomic set-if-not-exists) — this prevents replay attacks where a receipt is submitted twice.
4. Receipt must be submitted before expires_at (5 minutes from issue time).

HMAC canonical message

The signature covers this deterministically-ordered string, encoded as UTF-8:

"{task_id}:{tokens_used}:{cip_parent_task_id}:{cip_session_key}:{nonce}:{response_hash}"
# Extended form (CIP v0.6.11+): append querying_node_id when present:
# "{task_id}:...:{response_hash}:{querying_node_id}"
# Use empty string for optional fields (cip_parent_task_id, cip_session_key) when absent:
# e.g. "550e8400-...:142:::a3f2b8c9...:e3b0c44298fc1c149afbf4c8996fb924..."

Signed with HMAC-SHA256 using the worker's node HMAC key — provisioned by the directory at registration, distinct from the bearer token.

GET/api/v1/credits/transactions

Returns the ledger transaction history for the authenticated node.

curl -sf https://iicp.network/api/v1/credits/transactions \
  -H "Authorization: Bearer <node_token>"

Error codes

Rate limits