shell

The headless CCC bundle for Node.js scripts, CLI tools, and backend services.

@ckb-ccc/shell is the CCC package for server-side and scripting use cases. It re-exports the full @ckb-ccc/core API — clients, signers, transaction helpers, and type utilities — along with the spore, ssri, and udt namespaces. It has no dependency on the DOM, React, or any browser API.

Use @ckb-ccc/shell when:

• You are writing a Node.js script or CLI tool.
• You are building a backend service that interacts with CKB.
• You need programmatic key management (e.g., a private-key signer).

Use @ckb-ccc/connector-react instead when you are building a browser-based React app where users connect their own wallets.

Installation

npm

npm install @ckb-ccc/shell

yarn

yarn add @ckb-ccc/shell

pnpm

pnpm add @ckb-ccc/shell

Imports

import { ccc } from "@ckb-ccc/shell";

The ccc object contains everything from @ckb-ccc/core. The spore, ssri, and udt namespaces are also exported at the top level:

import { ccc, spore, udt } from "@ckb-ccc/shell";

Sending a transaction

The example below creates a private-key signer, builds a CKB transfer transaction, and broadcasts it to testnet.

import { ccc } from "@ckb-ccc/shell";

async function main() {
  // Connect to testnet
  const client = new ccc.ClientPublicTestnet();

  // Create a signer from a private key
  const signer = new ccc.SignerCkbPrivateKey(
    client,
    "0x<your-private-key-hex>",
  );

  // Resolve the recipient address
  const { script: toLock } = await ccc.Address.fromString(
    "ckt1qzda0cr08m85hc8jlnfp3gp88t7re8he4qkd3he97k2tfe4ckb...",
    client,
  );

  // Build the transaction
  const tx = ccc.Transaction.from({
    outputs: [{ lock: toLock, capacity: ccc.fixedPointFrom("100") }],
  });

  // Complete inputs and fees automatically
  await tx.completeInputsByCapacity(signer);
  await tx.completeFeeBy(signer);

  // Broadcast
  const txHash = await signer.sendTransaction(tx);
  console.log("Transaction sent:", txHash);
}

main().catch(console.error);

Querying cells

Use the client directly to fetch cells from the chain without a signer:

import { ccc } from "@ckb-ccc/shell";

const client = new ccc.ClientPublicMainnet();

for await (const cell of client.findCells({
  script: {
    codeHash: "0x...",
    hashType: "type",
    args: "0x...",
  },
  scriptType: "lock",
})) {
  console.log(cell.outPoint.txHash, cell.cellOutput.capacity);
}

@ckb-ccc/shell also re-exports the spore and udt namespaces. You can use Spore and UDT operations in Node.js without installing those packages separately.