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

# cToken SDK

> One SDK, three layers: core client, React hooks, drop-in UI

## Install

```bash theme={null}
npm install @inco/ctoken
```

Built on `viem` and `@inco/lightning-js`. React and the UI kit are optional, the core works anywhere JavaScript runs.

Try everything in the [live playground](https://ctoken-tze4f72wfa-ew.a.run.app/) before writing any code.

## Pick your layer

| Layer       | Import               | Use it when                        |
| ----------- | -------------------- | ---------------------------------- |
| Core        | `@inco/ctoken`       | You want raw APIs and full control |
| React hooks | `@inco/ctoken/react` | You have your own UI               |
| UI kit      | `@inco/ctoken/ui`    | You want working widgets today     |

## Core

The v1 addresses ship with the SDK, so pick a network and go:

```ts theme={null}
import { CTokenClient } from "@inco/ctoken";

const client = CTokenClient.browser({
  network: "base", // or "baseSepolia"
  walletClient,
  indexerUrl: "https://api.ctoken.inco.org/api",
});

await client.deposit({ token: usdc, amount: "100" });          // wrap
await client.confidentialSend({ token: usdc, to, amount: "25" });
await client.withdraw({ token: usdc, amount: "10" });           // unwrap

const balances = await client.balancesSettled({ tokens: [usdc] });
// { value: 65, pending: false }, or pending: true while the
// ciphertext is still being processed. One slow token never
// breaks the rest.

const history = await client.history({ page: 1 });
const prices = await client.prices([usdc]);
```

## Node.js

Same client for scripts and backends. Node signs with the key directly, so reads need no session and no popups.

```ts theme={null}
import { CTokenClient } from "@inco/ctoken";

const ctoken = CTokenClient.node({
  network: "base",
  privateKey: process.env.PRIVATE_KEY,
  indexerUrl: "https://api.ctoken.inco.org/api",
});

await ctoken.deposit({ token: usdc, amount: "1" });
console.log(await ctoken.balanceOf({ token: usdc }));
```

A runnable version lives in the repo at `examples/node/run.ts`.

Running your own deployment? Pass `contracts` and `sessionVerifier` to override the built-in addresses.

## React hooks

Wrap your app once, then every hook just works:

```tsx theme={null}
import { CTokenProvider } from "@inco/ctoken/react";

<CTokenProvider network="base" indexerUrl="https://api.ctoken.inco.org/api">
  <App />
</CTokenProvider>
```

```tsx theme={null}
import { useBalances, useDeposit, useConfidentialSend } from "@inco/ctoken/react";

const { data: balances } = useBalances({ tokens: [usdc] });
const { mutate: deposit, isPending } = useDeposit();
const { mutate: send } = useConfidentialSend();
```

Available hooks: `useCToken`, `useTokens`, `useResolvedTokens`, `useAssets`, `useBalances`, `useBalance`, `usePublicBalance`, `useDeposit`, `useApprove`, `useWithdraw`, `useConfidentialSend`, `useDecrypt`, `useHistory`, `useChainGuard`. They sit on wagmi and react-query, so caching, retries, and wallet state come for free.

## UI kit

Prebuilt widgets, themeable, animations included:

```tsx theme={null}
import { ConfidentialWallet } from "@inco/ctoken/ui";
import "@inco/ctoken/ui/styles.css";

<ConfidentialWallet />
```

`ConfidentialWallet` is the full experience: portfolio, shield, unshield, send, history. Or compose the pieces yourself: `DepositWidget`, `WithdrawWidget`, `SendWidget`, `BalanceCard`, `PortfolioCard`, `HistoryList`.

## Errors and retries

Indexer reads retry transient failures with backoff and honor `Retry-After`. Balance decrypts isolate failures per handle. Everything throws typed `CTokenError`s with stable codes.