qtcl-mcp-server

Create a new QTCL post-quantum wallet backed by a real HypΓ keypair (Schnorr-Γ over SL(3,p), 512-step random walk, SHA3-256² address). Returns private_key, public_key, address, and created_at. Store private_key securely — the server never retains it.

{
  "type": "object",
  "properties": {
    "label": {
      "type": "string",
      "description": "Optional human-readable wallet label"
    }
  },
  "additionalProperties": false
}

Sign a 32-byte message hash with a HypΓ private key using Schnorr-Γ. To sign a transaction, compute: SHA3-256(JSON.dumps({"sender": from_addr, "recipient": to_addr, "amount": amount_float, "nonce": nonce_int}, sort_keys=True)) → pass the 64-char hex as message_hex. The nonce MUST match the nonce you will use in qtcl_send_transaction. Returns the full signature dict (with canonical R/Z matrix fields) — pass the entire JSON output as the signature field to qtcl_send_transaction. CRITICAL: use the 'signature_for_tx' field from the response as the 'signature' argument to qtcl_send_transaction — do not extract sub-fields.

{
  "type": "object",
  "properties": {
    "message_hex": {
      "type": "string",
      "description": "64 hex chars (32-byte SHA3-256 hash of tx signing payload)"
    },
    "private_key": {
      "type": "string",
      "description": "HypΓ private key from qtcl_create_wallet (512-char base-4 walk)"
    }
  },
  "required": [
    "message_hex",
    "private_key"
  ],
  "additionalProperties": false
}

Check QTCL balance for any address. Returns balance in base units (qsat), UTXO count, and UTXO list. 1 QTCL = 100 qsat.

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "64-char hex QTCL address"
    }
  },
  "required": [
    "address"
  ],
  "additionalProperties": false
}

List unspent transaction outputs (UTXOs) for an address. Returns tx_hash, output_index, amount_base per coin.

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "64-char hex QTCL address"
    },
    "limit": {
      "type": "integer",
      "description": "Max UTXOs to return (default 1000)",
      "default": 1000
    }
  },
  "required": [
    "address"
  ],
  "additionalProperties": false
}

Submit a signed UTXO transaction to the QTCL network. Flat fee: 1 qsat. Finality: ~18 seconds. WORKFLOW: (1) pick nonce = int(time.time()*1000) [ms epoch]. (2) build payload = JSON.dumps({sender,recipient,amount,nonce}, sort_keys=True). (3) hash = SHA3-256(payload) as 64-char hex. (4) call qtcl_sign_message(message_hex=hash, private_key=key). (5) pass the 'signature_for_tx' field from step 4 as the 'signature' arg here, with the SAME nonce used in steps 1-4. CRITICAL: nonce must be a millisecond timestamp (>1700000000000) to avoid nonce_replay rejection. Never use sequential integers.

{
  "type": "object",
  "properties": {
    "from_address": {
      "type": "string",
      "description": "Sender's 64-char hex QTCL address"
    },
    "to_address": {
      "type": "string",
      "description": "Recipient's 64-char hex QTCL address"
    },
    "amount": {
      "type": "number",
      "description": "Amount in QTCL (not qsat). 1 QTCL = 100 qsat."
    },
    "memo": {
      "type": "string",
      "description": "Optional transaction memo (max 256 chars)"
    },
    "signature": {
      "type": "string",
      "description": "Use the 'signature_for_tx' value from qtcl_sign_message output — it is the full canonical sig JSON string with R, Z, c_full, challenge fields. Do NOT extract sub-fields. Pass signature_for_tx verbatim."
    },
    "public_key": {
      "type": "string",
      "description": "HypΓ public key hex from qtcl_create_wallet"
    },
    "nonce": {
      "type": "integer",
      "description": "Replay-prevention nonce — MUST be a millisecond epoch timestamp (int(time.time()*1000), e.g. ~1779000000000). Must match the nonce used in the signing payload. Auto-generated as ms timestamp if omitted."
    }
  },
  "required": [
    "from_address",
    "to_address",
    "amount"
  ],
  "additionalProperties": false
}

Look up a QTCL transaction by its SHA3-256 hash. Returns full tx details, status, and block height.

{
  "type": "object",
  "properties": {
    "tx_hash": {
      "type": "string",
      "description": "64-char hex transaction hash"
    }
  },
  "required": [
    "tx_hash"
  ],
  "additionalProperties": false
}

Current blockchain state: height, latest block hash, mempool depth, oracle status, and system health vector.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Retrieve a block by height (integer) or hash (hex string). Omit both for the latest block.

{
  "type": "object",
  "properties": {
    "height": {
      "type": "integer",
      "description": "Block height (0 = genesis; omit for latest)"
    },
    "hash": {
      "type": "string",
      "description": "Block hash hex (takes priority over height)"
    }
  },
  "additionalProperties": false
}

List recent transactions, optionally filtered by address. Returns newest first. Max 50 per call.

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "Optional: filter by sender or receiver address"
    },
    "per_page": {
      "type": "integer",
      "description": "Results per page (default 20, max 50)",
      "default": 20
    }
  },
  "additionalProperties": false
}

Live quantum coherence metrics: W-state fidelity (≥0.75 healthy), entanglement witness (NPT criterion), oracle consensus round, Mermin inequality test, and kappa=0.11 non-Markovian coherence score.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

List registered quantum oracle nodes participating in 5-oracle Byzantine consensus (3-of-5 majority).

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "description": "Max oracles to return (default 10, max 100)",
      "default": 10
    }
  },
  "additionalProperties": false
}

List active P2P peers in the QTCL Kademlia DHT network.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "description": "Max peers to return (default 20)",
      "default": 20
    }
  },
  "additionalProperties": false
}

QTCL network quantum coherence metrics and valuation signals. Note: QTCL has no public USD exchange. Returns W-state fidelity, entanglement witness, and oracle coherence as network health proxy.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Retroactively settle all blocks whose UTXOs are missing from address_utxos. Safe to call repeatedly — idempotent. Returns counts of settled/skipped/error blocks. Use this when miner balance is lower than expected after mining blocks.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Nuclear UTXO repair: bypasses settlement machinery and directly inserts missing UTXOs from the transactions table. Use when qtcl_retro_settle reports success but UTXOs are still missing. Commits per-UTXO for maximum isolation. Returns repaired_blocks, repaired_utxos, recomputed_wallets counts.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Submit a fully PoW-solved and HypΓ-signed block to the chain. This is the unified miner submission path. The miner client performs PoW locally, signs the block header, then calls this with the complete payload. Required: height, block_hash, parent_hash, merkle_root, timestamp, nonce, miner_address, difficulty_bits, w_entropy_hash, hyp_signature, miner_public_key_hex. Optional: transactions (JSON array), w_state_fidelity, pq0, pq_curr, pq_last, mermin_value, mermin_violated, quantum_field_16x16x16. Returns: {status, height, block_hash, next_height, miner_reward_qtcl}.

{
  "type": "object",
  "properties": {
    "height": {
      "type": "integer",
      "description": "Block height"
    },
    "block_hash": {
      "type": "string",
      "description": "Block hash hex"
    },
    "parent_hash": {
      "type": "string",
      "description": "Parent block hash hex"
    },
    "merkle_root": {
      "type": "string",
      "description": "Merkle root hex"
    },
    "timestamp": {
      "type": "integer",
      "description": "Block timestamp (epoch seconds)"
    },
    "nonce": {
      "type": "integer",
      "description": "PoW nonce"
    },
    "miner_address": {
      "type": "string",
      "description": "Miner's QTCL address"
    },
    "difficulty_bits": {
      "type": "integer",
      "description": "Difficulty bits"
    },
    "w_entropy_hash": {
      "type": "string",
      "description": "W-state entropy hash"
    },
    "hyp_signature": {
      "type": "string",
      "description": "HypΓ block signature"
    },
    "miner_public_key_hex": {
      "type": "string",
      "description": "Miner's public key hex"
    },
    "transactions": {
      "type": "string",
      "description": "JSON array string of transactions (default [])"
    },
    "w_state_fidelity": {
      "type": "number",
      "description": "W-state fidelity (default 0.75)"
    },
    "pq0": {
      "type": "integer",
      "description": "Initial oracle PQ counter (default 0)"
    },
    "pq_curr": {
      "type": "integer",
      "description": "Current oracle PQ counter (default 0)"
    },
    "pq_last": {
      "type": "integer",
      "description": "Last oracle PQ counter (default 0)"
    },
    "mermin_value": {
      "type": "number",
      "description": "Mermin inequality value (default 0.0)"
    },
    "mermin_violated": {
      "type": "boolean",
      "description": "Mermin violation flag (default false)"
    },
    "quantum_field_16x16x16": {
      "type": "string",
      "description": "Quantum field data (default empty)"
    }
  },
  "required": [
    "height",
    "block_hash",
    "parent_hash",
    "merkle_root",
    "timestamp",
    "nonce",
    "miner_address",
    "difficulty_bits",
    "w_entropy_hash",
    "hyp_signature",
    "miner_public_key_hex"
  ],
  "additionalProperties": false
}

Quantum-bound encryption via IBM QLDPC hardware (ibm_marrakesh/ibm_kingston). Two modes: quantum_bound (async=false, default): XOR-masks the encapsulated key with a hardware-derived quantum key. Runs synchronously with 8192 shots for deterministic results. Recipient MUST use qtcl_quantum_decrypt to recover the key. attestation (async=true): Leaves encapsulated key unchanged, runs hardware in background. Attaches quantum_commitment as metadata. Classical decrypt still works. Returns: Ciphertext dict with quantum_commitment, quantum_status, quantum_mode, quantum_hardened, and all standard encryption fields.

{
  "type": "object",
  "properties": {
    "plaintext_hex": {
      "type": "string",
      "description": "Hex-encoded plaintext bytes to encrypt"
    },
    "public_key": {
      "type": "string",
      "description": "Recipient's public key (hex)"
    },
    "ibm_token": {
      "type": "string",
      "description": "Per-request IBM Quantum API token (optional — uses server env var if blank)"
    },
    "async": {
      "type": "boolean",
      "description": "True for attestation mode, false for quantum-bound (default false)",
      "default": false
    }
  },
  "required": [
    "plaintext_hex",
    "public_key"
  ],
  "additionalProperties": false
}

Decrypt quantum-bound or quantum-assisted ciphertext. Auto-detects mode from the ciphertext dict: quantum_bound → runs QLDPC pipeline on masked key, XOR-unmasks, decrypts attestation → tries classical first, falls back to quantum-assisted recovery classical → pure classical decrypt Returns: Plaintext (hex), plaintext_length, quantum_assisted flag, quantum_mode.

{
  "type": "object",
  "properties": {
    "ciphertext": {
      "type": "string",
      "description": "JSON string of the ciphertext dict from qtcl_quantum_encrypt (must include quantum_commitment, quantum_mode, etc.)"
    },
    "private_key": {
      "type": "string",
      "description": "Recipient's private key (hex)"
    },
    "ibm_token": {
      "type": "string",
      "description": "Per-request IBM Quantum API token (optional)"
    }
  },
  "required": [
    "ciphertext",
    "private_key"
  ],
  "additionalProperties": false
}

Run the full QLDPC pipeline directly on IBM quantum hardware. Encodes ciphertext bytes into a hyperbolic QLDPC code, runs on real IBM hardware (8192 shots), decodes syndromes via BP+OSD, and returns the recovered key fragment. Returns: Pipeline result with recovered_key_hex, residual, status, job_id, backend.

{
  "type": "object",
  "properties": {
    "ciphertext_hex": {
      "type": "string",
      "description": "Hex-encoded bytes to use as key fragment input"
    },
    "genus": {
      "type": "integer",
      "description": "Hyperbolic surface genus (default 1)",
      "default": 1
    },
    "shots": {
      "type": "integer",
      "description": "Measurement shots (default 8192)",
      "default": 8192
    },
    "ibm_token": {
      "type": "string",
      "description": "Per-request IBM Quantum API token (optional)"
    }
  },
  "required": [
    "ciphertext_hex"
  ],
  "additionalProperties": false
}

Create a new QTCL wallet with HYBRID post-quantum keys: Falcon-512 (NIST FIPS 206, 128-bit PQ security) + SL(3,p) (~70-bit classical). Returns full keypair dict with both Falcon and SL(3,p) components. Server does NOT retain secret keys. This is the v3 recommended wallet type — quantum-safe by default.

{
  "type": "object",
  "properties": {
    "label": {
      "type": "string",
      "description": "Optional human-readable wallet label"
    }
  },
  "additionalProperties": false
}

Sign a 32-byte message hash with HYBRID PQC (Falcon-512 + SL(3,p)). Both Falcon and SL(3,p) signatures are computed independently — verification requires BOTH to be valid. message_hex must be 64 hex chars (SHA3-256 of signing payload). private_key_json must be the full JSON output from qtcl_create_hybrid_wallet. Returns hybrid signature dict — pass verbatim as 'signature' to qtcl_send_transaction.

{
  "type": "object",
  "properties": {
    "message_hex": {
      "type": "string",
      "description": "64 hex chars (32-byte SHA3-256 hash of tx signing payload)"
    },
    "private_key_json": {
      "type": "string",
      "description": "Full JSON string from qtcl_create_hybrid_wallet (contains both Falcon and SL(3,p) secret keys)"
    }
  },
  "required": [
    "message_hex",
    "private_key_json"
  ],
  "additionalProperties": false
}

Return PQC module status — shows whether Falcon-512 is available, key/signature sizes, security level, and hybrid signature overhead. Use to check if the server supports full hybrid PQ signatures.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}