← Back to Home

Node Setup Guide for ICP

Version 1.0.0 — February 14, 2026

Prepare your Nano node to handle requests from the Internet Computer.

Key Requirements

• Handle Idempotency-Key header - ICP subnets have 13-40 replicas sending identical requests simultaneously. The current subnet uses 13 replicas, and for now this is unlikely to change. Cache responses by this key. All replicas send the same key.
• Respond as fast as possible - but no longer than a few seconds. ICP has a hard timeout of ~30s — leave buffer.
• Return deterministic JSON - More than 2/3 of replicas must receive identical data. Avoid timestamps or random values in response body.
• Use HTTPS - ICP only makes HTTPS outcalls.
• Only return requested data - No extra fields, metadata, or wrapper objects. Return clean Nano RPC responses.

Idempotency-Key Format

Every request includes this header:

Idempotency-Key: icmware-{timestamp_ns}-{counter}-{hash12}

Example: icmware-1699876543210987654-42-a1b2c3d4e5f6

Implementation with Redis

For example, use Redis to deduplicate requests from all replicas:

• Check cache first: redis.get(f"cache:{idempotency_key}")
• Acquire lock with SET NX: redis.set(pending_key, "1", nx=True, ex=60)
• Use BLPOP for efficient waiting (no polling): redis.blpop(notify_key, timeout=25)

Step 1 is an optimization — if all replicas arrive simultaneously, the cache will always be empty on first check. The critical path is SET NX → BLPOP.

Critical order when storing result:

redis.setex(cache_key, 60, result)  # 1. Cache FIRST
# 2. Notify ALL waiting replicas (one LPUSH per potential waiter)
for _ in range(num_replicas + buffer):
    redis.lpush(notify_key, "ready")
redis.delete(pending_key)           # 3. Release lock LAST

Wrong order causes race conditions. For state-modifying operations like process, reject requests if Redis is unavailable (return 503).

On node failure, push "error" to notify_key and delete pending_key — otherwise waiters hang until timeout.

Set expire on notify_key (e.g. 60s) to auto-cleanup stale lists in Redis.

In practice, ~91% of duplicates are served from cache (step 1). Only ~1% need BLPOP. The cache check handles the bulk of deduplication.

Register Your Node

Input Limits

Field	Min	Max	Notes
url	8	130	Must start with https://
api_key	20	130	Optional
auth_header_name	1	50	Optional (default: X-API-Key)
auth_header_prefix	—	20	Optional (e.g. Bearer )

# Register as private node (url, opt api_key, opt auth_header_name, opt auth_header_prefix)
dfx canister call 7jsss-6qaaa-aaaad-aegpq-cai register_private_node \
  '("https://your-node.com/rpc", opt "your-api-key")' --network ic

# With custom auth header (e.g. Bearer token instead of X-API-Key)
# register_private_node '("https://your-node.com/rpc", opt "your-token", opt "Authorization", opt "Bearer ")'

# Enable force mode: ALL your requests go through your private node
dfx canister call 7jsss-6qaaa-aaaad-aegpq-cai set_force_node '(true)' --network ic

# Enable force PoW: PoW requests also go through your private node
dfx canister call 7jsss-6qaaa-aaaad-aegpq-cai set_force_pow '(true)' --network ic

# Test it
dfx canister call 7jsss-6qaaa-aaaad-aegpq-cai get_account_info_for_signing \
  '("nano_1ipx847tk8o46pwxt5qjdbncjqcbwcc1rrmqnkztrfjy5k7z4imsrata9est")' --network ic

Allowed RPC Commands

Public nodes must support these Nano RPC actions:

Accounts:

Receivable:

Blocks:

Network:

Transactions:

Become a Public Node

Once your node is stable, contact us at info@nanogate.run to register it as a public node. Public nodes serve all NANOGATE users and earn credits instantly for every request they handle.

Note: The same URL cannot be used for both private and public nodes. Use different endpoints if you want to run both.

← Back to Home