> ## Documentation Index
> Fetch the complete documentation index at: https://ckbfans.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Client

> Connect to a CKB node, query blockchain data, and send transactions.

A `Client` is your connection to the CKB network. It wraps the CKB JSON-RPC, handles request caching, and exposes higher-level helpers for finding cells and transactions. Every other CCC abstraction — signers, transactions, addresses — depends on a client to talk to the chain.

## Instantiate a client

CCC ships two ready-to-use implementations that connect to the public RPC endpoints:

<CodeGroup>
  ```ts Mainnet theme={null}
  import { ccc } from "@ckb-ccc/ccc";

  const client = new ccc.ClientPublicMainnet();
  ```

  ```ts Testnet theme={null}
  import { ccc } from "@ckb-ccc/ccc";

  const client = new ccc.ClientPublicTestnet();
  ```
</CodeGroup>

Both classes automatically prefer a WebSocket transport when the environment supports it, and fall back to HTTPS otherwise. Pass a `url` option to point at your own node:

```ts theme={null}
const client = new ccc.ClientPublicMainnet({ url: "https://my-node.example.com/" });
```

`ClientPublicMainnet` uses the address prefix `ckb`; `ClientPublicTestnet` uses `ckt`.

## Query chain state

### Tip block

```ts theme={null}
const tipBlockNumber = await client.getTip();
console.log(tipBlockNumber); // e.g. 14000000n
```

### Blocks and headers

```ts theme={null}
const block = await client.getBlockByNumber(14000000n);
const alsoBlock = await client.getBlockByHash("0xabc...");

const header = await client.getHeaderByNumber(14000000n);
```

Both methods return `undefined` when the block does not exist, and cache confirmed results automatically.

### Fee rate

```ts theme={null}
// Median fee rate over the last N blocks (defaults to a recent window)
const feeRate = await client.getFeeRate();

// With a custom block range
const feeRate24h = await client.getFeeRate(100n);

// Cap the fee rate so you never overpay
const cappedFeeRate = await client.getFeeRate(undefined, { maxFeeRate: 2000n });
```

## Find cells

Use `findCells` to iterate over live cells that match a search key. It merges cached cells with on-chain results so you never miss a freshly sent cell:

```ts theme={null}
const lock = { codeHash: "0x...", hashType: "type", args: "0x..." };

for await (const cell of client.findCells({ script: lock, scriptType: "lock", scriptSearchMode: "exact", withData: true })) {
  console.log(cell.cellOutput.capacity);
}
```

Two convenience wrappers cover the most common cases:

```ts theme={null}
// All cells locked by a specific lock script
for await (const cell of client.findCellsByLock(lock)) { ... }

// All cells with a specific type script
for await (const cell of client.findCellsByType(typeScript)) { ... }
```

## Find transactions

`findTransactions` returns an async generator of transaction records for any lock or type script:

```ts theme={null}
for await (const tx of client.findTransactionsByLock(lock)) {
  console.log(tx.txHash, tx.blockNumber);
}
```

Pass `groupByTransaction: true` to receive one record per transaction instead of one record per input/output:

```ts theme={null}
for await (const grouped of client.findTransactionsByLock(lock, undefined, true)) {
  console.log(grouped.txHash);
}
```

## Send a transaction

After you build and sign a transaction, submit it with `sendTransaction`:

```ts theme={null}
const txHash = await client.sendTransaction(signedTx);
console.log("sent:", txHash);
```

`sendTransaction` validates the fee rate against a configurable maximum before broadcasting.

### Wait for confirmation

```ts theme={null}
// Wait up to 60 s with at least 1 confirmation
const response = await client.waitTransaction(txHash, 1, 60_000);
```

## KnownScript

The `KnownScript` enum lets you reference well-known on-chain scripts by name instead of hard-coding code hashes. Call `client.getKnownScript()` to retrieve the deployment info (code hash, hash type, and cell deps) for any entry:

```ts theme={null}
const info = await client.getKnownScript(ccc.KnownScript.Secp256k1Blake160);
console.log(info.codeHash);
```

Available entries:

| Enum value          | Description                        |
| ------------------- | ---------------------------------- |
| `NervosDao`         | Nervos DAO deposit/withdraw script |
| `Secp256k1Blake160` | Standard single-sig lock           |
| `Secp256k1Multisig` | Standard multisig lock             |
| `AnyoneCanPay`      | Anyone-can-pay lock                |
| `TypeId`            | Type ID script                     |
| `XUdt`              | xUDT fungible token type           |
| `JoyId`             | JoyID passkey lock                 |
| `OmniLock`          | OmniLock (EVM / BTC compatible)    |
| `NostrLock`         | Nostr event lock                   |
| `COTA`              | CoTA NFT type                      |
| `UniqueType`        | Unique cell type                   |
| `TimeLock`          | Time-locked cells                  |

<Note>
  Script availability varies by network. Calling `getKnownScript` for a script that is not deployed on the current network throws an error.
</Note>