### CLI: create-circles-dev-kit usage

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Scaffolds a full copy of the dev-kit repo into a new folder, installs dependencies, and initializes a fresh git repository. Various flags allow for non-interactive or skipped setup steps.

```bash
# Interactive (prompts for folder name)
npx create-circles-dev-kit@latest

# Non-interactive with a specific folder
npx create-circles-dev-kit@latest my-circles-app

# Scaffold into the current directory
npx create-circles-dev-kit@latest .

# Skip prompts, dependency install, and git init
npx create-circles-dev-kit@latest my-app --yes --no-install --no-git
```

--------------------------------

### Build Circles Dev Kit from Repository

Source: https://github.com/aboutcircles/circles-dev-kit/blob/master/README.md

Clone the repository, install dependencies, and run the development server to build the Circles Dev Kit locally.

```bash
git clone https://github.com/aboutcircles/circles-dev-kit
npm install
npm run dev
# open http://localhost:3000
```

--------------------------------

### Adding a New SDK Example

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Demonstrates how to integrate a new SDK method into a lab page using the `AsyncState` pattern and `run` helper.

```typescript
// 1. Add a new SDK example to any lab page
const [myOp, setMyOp] = useState<AsyncState>({});

// 2. Wire a button
<button onClick={() => run(() => sdk.myMethod(args), setMyOp)}>
  Call myMethod
</button>

// 3. Display result
<Result state={myOp} title="My Operation" onOpen={openModal} />
```

--------------------------------

### Get Total Balance (JSON-RPC)

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Retrieves the total balance for a given address. The `circlesV2_getTotalBalance` method is an updated version.

```bash
curl -X POST https://rpc.aboutcircles.com/circles_getTotalBalance \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"circles_getTotalBalance","params":["0x42cedde51198d1773590311e2a340dc06b24cb37",true]}'
# { "jsonrpc": "2.0", "id": 1, "result": "12345000000000000000000" }

```

```bash
curl -X POST https://rpc.aboutcircles.com/circlesV2_getTotalBalance \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"circlesV2_getTotalBalance","params":["0x42cedde51198d1773590311e2a340dc06b24cb37",true]}'

```

--------------------------------

### Get Balance Breakdown (JSON-RPC)

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Provides a fast indexed breakdown of balances per CRC token for a given address.

```bash
curl -X POST https://rpc.aboutcircles.com/circles_getBalanceBreakdown \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"circles_getBalanceBreakdown","params":["0x42cedde51198d1773590311e2a340dc06b24cb37"]}'
# Fast indexed breakdown of balances per CRC token

```

--------------------------------

### Providers Component Setup

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

The `Providers` component bootstraps essential libraries like Wagmi, HeroUI, TanStack Query, and `next-themes`. It supports various wallet connectors and is configured for Gnosis Chain.

```tsx
// app/providers.tsx — already wraps the entire app in layout.tsx
import { Providers } from "./providers";

// Wagmi is locked to Gnosis Chain (Chain ID 100)
// Supported connectors: injected(), metaMask(), coinbaseWallet(), walletConnect() (optional)
// TanStack Query: staleTime 5 min, gcTime 10 min, no retry on 4xx

<Providers themeProps={{ attribute: "class", defaultTheme: "dark" }}>
  {children}
</Providers>
```

--------------------------------

### Get Trust Relations (JSON-RPC)

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Retrieves trust relations for a given address, including who the address trusts and who trusts the address.

```bash
curl -X POST https://rpc.aboutcircles.com/circles_getTrustRelations \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"circles_getTrustRelations","params":["0x42cedde51198d1773590311e2a340dc06b24cb37"]}'
# { result: { trusts: [...], trustedBy: [...] } }

```

--------------------------------

### Get Token Balances (JSON-RPC)

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Retrieves on-chain raw CRC token balances per token address for a given address.

```bash
curl -X POST https://rpc.aboutcircles.com/circles_getTokenBalances \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"circles_getTokenBalances","params":["0x42cedde51198d1773590311e2a340dc06b24cb37"]}'
# Returns on-chain raw CRC token balances per token address

```

--------------------------------

### Get Common Trust (JSON-RPC)

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Checks for common trust relationships between two specified addresses.

```bash
curl -X POST https://rpc.aboutcircles.com/circles_getCommonTrust \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"circles_getCommonTrust","params":["0xaddress_a","0xaddress_b"]}'

```

--------------------------------

### Get Total and Token Balances for Group/Avatar

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Fetches both the aggregated total balance and the per-token balance breakdown for a specified group or avatar. Use `getTotalBalanceV2` with `includeZero = true` to see all token balances, including zero balances.

```typescript
const { sdk } = useCircles();

const addr = "0xgroup_address" as `0x${string}`;
const [totalBalance, tokenBalances] = await Promise.all([
  sdk.data.getTotalBalanceV2(addr, true),  // includeZero = true
  sdk.data.getTokenBalances(addr),
]);
// totalBalance: "123456789000000000000" (wei string)
// tokenBalances: [{ tokenAddress, balance, ... }, ...]
```

--------------------------------

### Get Group Memberships for an Avatar

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Retrieves all groups an avatar is a member of, with pagination support. Use `queryNextPage()` to fetch subsequent pages.

```typescript
const { sdk } = useCircles();

const query = sdk.data.getGroupMemberships(
  "0xavatar_address" as `0x${string}`,
  20 // page size
);

await query.queryNextPage();
const memberships = query.currentPage?.results ?? [];
// memberships: Array of group membership records
```

--------------------------------

### Get Token Information

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Fetches metadata for a specific Circles token, including its type, owner, and decimals. Requires a valid token address.

```typescript
const { sdk } = useCircles();

const tokenInfo = await sdk.data.getTokenInfo(
  "0xtoken_address" as `0x${string}`
);
// { tokenAddress, tokenType, owner, ... }
```

--------------------------------

### Get Gnosis Chain Config

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Reads the canonical CirclesConfig for Gnosis Chain (chain ID 100) from the SDK's built-in registry. Throws at startup if the chain config is missing.

```typescript
// config/circles.ts
import { appCirclesConfig } from "@/config/circles";
// appCirclesConfig === circlesConfig[100]
// Contains: hub address, RPC endpoints, subgraph URLs, etc.
console.log(appCirclesConfig);
```

--------------------------------

### Get Avatar Info

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Returns a lightweight row describing whether an address is a Circles avatar, its type, and protocol version. Returns undefined if the address is not a Circles avatar.

```typescript
const { sdk } = useCircles();
const { address } = useAccount(); // from wagmi

const info = await sdk.data.getAvatarInfo(address.toLowerCase() as `0x${string}`);
// Expected output:
// {
//   address: "0xabc...",
//   type: "human",          // or "organization" | "group"
//   version: 2              // 1 = V1, 2 = V2
// }
// Returns undefined if address is not a Circles avatar
```

--------------------------------

### Get Avatar Info

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Returns a lightweight row describing whether an address is a Circles avatar, its type (`human` | `organization` | `group`), and protocol version (1 or 2).

```APIDOC
## Avatar Lab — `sdk.data.getAvatarInfo`

Returns a lightweight row describing whether an address is a Circles avatar, its type (`human` | `organization` | `group`), and protocol version (1 or 2).

```ts
const { sdk } = useCircles();
const { address } = useAccount(); // from wagmi

const info = await sdk.data.getAvatarInfo(address.toLowerCase() as `0x${string}`);
// Expected output:
// {
//   address: "0xabc...",
//   type: "human",          // or "organization" | "group"
//   version: 2              // 1 = V1, 2 = V2
// }
// Returns undefined if address is not a Circles avatar
```
```

--------------------------------

### Get Avatar

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Returns a full `AvatarInterface` object with methods for trust operations, balance queries, profile updates, transfers, group minting, and admin actions.

```APIDOC
## Avatar Lab — `sdk.getAvatar`

Returns a full `AvatarInterface` object with methods for trust operations, balance queries, profile updates, transfers, group minting, and admin actions.

```ts
const avatar = await sdk.getAvatar(address.toLowerCase() as `0x${string}`);

// Inspect available methods
console.log(Object.keys(avatar));
// ["trust", "untrust", "groupMint", "groupRedeem", "groupRedeemAuto",
//  "owner", "service", "mintHandler", "getMembershipConditions",
//  "setOwner", "setService", "setMembershipCondition", ...]
```
```

--------------------------------

### sdk.v2Hub.treasuries + sdk.data.getTokenBalances

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Retrieves a group's treasury address and then queries its token balances. This involves two steps: first getting the treasury address, then fetching the balances held by that address.

```APIDOC
## Groups Lab — Treasury: `sdk.v2Hub.treasuries` + `sdk.data.getTokenBalances`

### Description
Retrieves a group's treasury address and then queries its token balances.

### Method
```ts
const groupAddress = "0xgroup_address" as `0x${string}`;

// Step 1: get treasury address
const treasuryAddr = await sdk.v2Hub?.treasuries(groupAddress);
if (!treasuryAddr) throw new Error("No treasury found");

// Step 2: get balances held by the treasury
const balances = await sdk.data.getTokenBalances(treasuryAddr as `0x${string}`);
```

### Parameters
#### Query Parameters (for `sdk.v2Hub.treasuries`)
- **groupAddress** (`0x${string}`) - Required - The address of the group.

#### Query Parameters (for `sdk.data.getTokenBalances`)
- **treasuryAddress** (`0x${string}`) - Required - The address of the treasury.

### Response
- **treasuryAddr** (`0x${string}`) - The address of the group's treasury.
- **balances** (object) - An object containing the treasury address and an array of token balances.
```

--------------------------------

### Get Aggregated Trust Relations

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Returns the full aggregated trust graph for an address up to a specified depth. Useful for analyzing trust networks.

```typescript
const { sdk } = useCircles();

const trustRelations = await sdk.data.getAggregatedTrustRelations(
  "0xgroup_address" as `0x${string}`,
  2 // depth: how many hops to traverse
);
// { trustedBy: [...], trusts: [...] }
```

--------------------------------

### Get Full Avatar Object

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Returns a full AvatarInterface object with methods for trust operations, balance queries, profile updates, transfers, group minting, and admin actions.

```typescript
const avatar = await sdk.getAvatar(address.toLowerCase() as `0x${string}`);

// Inspect available methods
console.log(Object.keys(avatar));
// ["trust", "untrust", "groupMint", "groupRedeem", "groupRedeemAuto",
//  "owner", "service", "mintHandler", "getMembershipConditions",
//  "setOwner", "setService", "setMembershipCondition", ...]
```

--------------------------------

### Get Indexed On-Chain Events

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Queries indexed on-chain events for a given address. Supports filtering by block range and event type. Use `undefined` for `toBlock` to query up to the latest block.

```typescript
const { sdk } = useCircles();

const events = await sdk.data.getEvents(
  "0xgroup_address" as `0x${string}`,
  38000000,          // fromBlock (optional)
  undefined,         // toBlock (optional, null = latest)
  ["CrcV2_Trust"]    // eventTypes (optional)
);
// Array of event objects: { blockNumber, transactionHash, event, ... }
```

--------------------------------

### Create Circles Dev Kit Project

Source: https://github.com/aboutcircles/circles-dev-kit/blob/master/README.md

Use this command to quickly set up a new project with the Circles Dev Kit.

```bash
npx create-circles-dev-kit@latest
```

--------------------------------

### Enable WalletConnect Support

Source: https://github.com/aboutcircles/circles-dev-kit/blob/master/README.md

To enable WalletConnect, create a .env.local file and add your WalletConnect project ID. This is optional as the app supports other wallets like MetaMask.

```bash
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_project_id_here
```

--------------------------------

### Scaffold a new Circles Dev Kit project

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Use this command to create a new Next.js project pre-configured with the Circles Dev Kit. You can clone the repository directly or use the `create-circles-dev-kit` CLI.

```bash
npx create-circles-dev-kit@latest

git clone https://github.com/aboutcircles/circles-dev-kit
npm install
npm run dev        # http://localhost:3000

# Optional: enable WalletConnect
echo "NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_id" >> .env.local
```

--------------------------------

### List Tables using circles_tables

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Lists all available namespaces and queryable tables in the Circles index.

```bash
curl -X POST https://rpc.aboutcircles.com/circles_tables \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"circles_tables","params":[]}'
```

--------------------------------

### AsyncState Pattern and run() Helper

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Manages asynchronous operation state uniformly. The `run` helper wraps async SDK calls and updates the state via a setter function.

```typescript
type AsyncState<T = unknown> = {
  loading?: boolean;
  error?: string;
  result?: T;
};

// Generic run helper — wraps any async SDK call
const run = async <T>(
  fn: () => Promise<T>,
  setter: (s: AsyncState<T>) => void
) => {
  setter({ loading: true });
  try {
    const result = await fn();
    setter({ loading: false, result });
  } catch (e: unknown) {
    const errorMessage = e instanceof Error ? e.message : String(e);
    setter({ loading: false, error: errorMessage });
  }
};

// Usage example
const [avatarInfo, setAvatarInfo] = useState<AsyncState>({});

run(
  () => sdk.data.getAvatarInfo(address as `0x${string}`),
  setAvatarInfo
);

// Render
if (avatarInfo.loading) return <p>Loading…</p>;
if (avatarInfo.error)   return <p>Error: {avatarInfo.error}</p>;
if (avatarInfo.result)  return <pre>{JSON.stringify(avatarInfo.result, null, 2)}</pre>;
```

--------------------------------

### Accept Invitation (Human V2)

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Registers the connected wallet as a **Human V2** avatar using an invitation from an existing V2 avatar. Requires a valid `inviter` address that has already registered on V2.

```APIDOC
## Avatar Lab — `sdk.acceptInvitation` (Human V2)

Registers the connected wallet as a **Human V2** avatar using an invitation from an existing V2 avatar. Requires a valid `inviter` address that has already registered on V2.

```ts
const { sdk } = useCircles();

const result = await sdk.acceptInvitation(
  "0xinviter_address" as `0x${string}`,
  { name: "Alice", description: "New Circles member" }
);
// On-chain transaction — requires xDAI for gas
// inviter must be a valid V2 human or group that trusts the invitee
```
```

--------------------------------

### Accept Invitation (Human V2)

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Registers the connected wallet as a Human V2 avatar using an invitation from an existing V2 avatar. Requires a valid inviter address and xDAI for gas.

```typescript
const { sdk } = useCircles();

const result = await sdk.acceptInvitation(
  "0xinviter_address" as `0x${string}`,
  { name: "Alice", description: "New Circles member" }
);
// On-chain transaction — requires xDAI for gas
// inviter must be a valid V2 human or group that trusts the invitee
```

--------------------------------

### sdk.baseGroupFactory.deployBaseGroup

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Deploys a Base Group using the Base Group Factory with a standard mint policy. This is an on-chain transaction that returns the group address upon confirmation.

```APIDOC
## Groups Lab — `sdk.baseGroupFactory.deployBaseGroup`

### Description
Deploys a **Base Group** using the Base Group Factory with a standard mint policy.

### Method
```ts
await sdk.baseGroupFactory.deployBaseGroup(
  "0xmint_policy_address" as `0x${string}`,
  {
    name: "My Base Group",
    symbol: "MBG",
    description: "A Base Group on Circles V2",
  }
);
```

### Parameters
#### Path Parameters
- **mintPolicyAddress** (`0x${string}`) - Required - The address of the mint policy.

#### Request Body
- **name** (string) - Required - The name of the group.
- **symbol** (string) - Required - The symbol for the group.
- **description** (string) - Optional - A description for the group.

### Response
On-chain transaction — returns group address on confirmation.
```

--------------------------------

### CirclesProvider and useCircles Hook

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

The `CirclesProvider` context initializes the Circles SDK against Gnosis Chain and provides it to child components. Use the `useCircles` hook to access the SDK instance and its connection status in client components.

```tsx
// contexts/CirclesContext.tsx
import { CirclesProvider, useCircles } from "./contexts/CirclesContext";

// Wrap your app (already done in app/layout.tsx)
export default function RootLayout({ children }) {
  return (
    <Providers>
      <CirclesProvider>
        {children}
      </CirclesProvider>
    </Providers>
  );
}

// Consume in any client component
function MyComponent() {
  const { sdk, isLoading, error, isConnected, reconnect, retryCount } = useCircles();

  if (!isConnected) return <p>Connect your wallet</p>;
  if (isLoading)    return <p>Initializing SDK… (attempt {retryCount})</p>;
  if (error)        return <p>Error: {error.message} <button onClick={reconnect}>Retry</button></p>;

  // sdk is ready
  return <p>SDK connected ✅</p>;
}
```

--------------------------------

### Deploy Base Group

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Deploys a Base Group using the Base Group Factory with a standard mint policy. Requires a valid mint policy address. This is an on-chain transaction.

```typescript
const { sdk } = useCircles();

if (!sdk.baseGroupFactory) throw new Error("Base group factory not available");

const result = await sdk.baseGroupFactory.deployBaseGroup(
  "0xmint_policy_address" as `0x${string}`,
  {
    name: "My Base Group",
    symbol: "MBG",
    description: "A Base Group on Circles V2",
  }
);
// On-chain transaction — returns group address on confirmation
```

--------------------------------

### Create or Update Profile

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Upserts an avatar's on-chain profile (name, description, and additional fields depending on SDK version). Requires the wallet to be the avatar owner.

```APIDOC
## Avatar Lab — `sdk.createOrUpdateProfile`

Upserts an avatar's on-chain profile (name, description, and additional fields depending on SDK version). Requires the wallet to be the avatar owner.

```ts
const { sdk } = useCircles();

const result = await sdk.createOrUpdateProfile({
  name: "Alice",
  description: "Building on Circles since 2024",
});
// Sends an on-chain transaction; resolves when confirmed
// Requires xDAI for gas on Gnosis Chain
```
```

--------------------------------

### Register Organization V2

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Registers the connected wallet as a **Circles V2 Organization** avatar.

```APIDOC
## Avatar Lab — `sdk.registerOrganizationV2`

Registers the connected wallet as a **Circles V2 Organization** avatar.

```ts
const { sdk } = useCircles();

const result = await sdk.registerOrganizationV2({
  name: "My Org",
  description: "A cooperative on Circles",
});
// On-chain transaction — requires xDAI for gas
```
```

--------------------------------

### Register Organization V2

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Registers the connected wallet as a Circles V2 Organization avatar. Requires xDAI for gas.

```typescript
const { sdk } = useCircles();

const result = await sdk.registerOrganizationV2({
  name: "My Org",
  description: "A cooperative on Circles",
});
// On-chain transaction — requires xDAI for gas
```

--------------------------------

### Find Path using circlesV2_findPath

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Finds a payment path between two avatars. TargetFlow specifies the maximum amount to transfer.

```bash
curl -X POST https://rpc.aboutcircles.com/circlesV2_findPath \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "circlesV2_findPath",
    "params": [{
      "Source": "0xsender_address",
      "Sink": "0xreceiver_address",
      "TargetFlow": "99999999999999999999999999999999999"
    }]
  }'
```

--------------------------------

### JSON-RPC Explorer - `circlesV2_getTotalBalance`

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Retrieves the total balance for a given address using the V2 endpoint.

```APIDOC
## circlesV2_getTotalBalance

### Description
Gets the total balance for a given address using the V2 RPC endpoint.

### Method
POST

### Endpoint
/circlesV2_getTotalBalance

### Parameters
- **address** (string) - Required - The address to query.
- **includeAll** (boolean) - Optional - Whether to include balances for all token types.

### Request Example
```bash
curl -X POST https://rpc.aboutcircles.com/circlesV2_getTotalBalance \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"circlesV2_getTotalBalance","params":["0x42cedde51198d1773590311e2a340dc06b24cb37",true]}'
```
```

--------------------------------

### circles_tables

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Lists all available namespaces and queryable tables in the Circles index.

```APIDOC
## POST /circles_tables

### Description
Lists all available namespaces and queryable tables in the Circles index.

### Method
POST

### Endpoint
https://rpc.aboutcircles.com/circles_tables

### Request Body
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "circles_tables",
  "params": []
}
```

### Response
#### Success Response (200)
Lists available namespaces and tables.
```

--------------------------------

### Migrate Avatar (V1 → V2)

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Migrates a V1 avatar to V2, preserving the trust graph. Requires an inviter, the avatar address to migrate, a profile, and an array of trust addresses to carry over.

```APIDOC
## Avatar Lab — `sdk.migrateAvatar` (V1 → V2)

Migrates a V1 avatar to V2, preserving the trust graph. Requires an inviter, the avatar address to migrate, a profile, and an array of trust addresses to carry over.

```ts
const { sdk } = useCircles();

const result = await sdk.migrateAvatar(
  "0xinviter" as `0x${string}`,
  "0xavatar_to_migrate" as `0x${string}`,
  { name: "Alice", description: "Migrated from V1" },
  ["0xtrust1", "0xtrust2"]
);
// On-chain transaction — requires xDAI for gas
```
```

--------------------------------

### Adding a New JSON-RPC Card

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Shows how to add a new JSON-RPC method to the API explorer by extending the `rpcMethods` array.

```typescript
// ——— Add a new JSON-RPC card to /api ———
const rpcMethods: RpcMethod[] = [
  // ...existing methods
  {
    key: "myNewMethod",
    title: "My New RPC Method",
    description: "Description of what this method does.",
    url: "https://rpc.aboutcircles.com/my_method",
    method: "my_method",
    getParams: (addr) => [addr, /* additional params */],
  },
];
```

--------------------------------

### Register Group V2

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Registers a new **Circles V2 Group** avatar with a specified mint policy address.

```APIDOC
## Avatar Lab — `sdk.registerGroupV2`

Registers a new **Circles V2 Group** avatar with a specified mint policy address.

```ts
const { sdk } = useCircles();

const result = await sdk.registerGroupV2(
  "0xmint_policy_address" as `0x${string}`,
  { name: "My Group", description: "A circles group", symbol: "MG" }
);
// On-chain transaction — requires xDAI for gas
```
```

--------------------------------

### Migrate Avatar V1 to V2

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Migrates a V1 avatar to V2, preserving the trust graph. Requires an inviter, the avatar address to migrate, a profile, and an array of trust addresses to carry over. Requires xDAI for gas.

```typescript
const { sdk } = useCircles();

const result = await sdk.migrateAvatar(
  "0xinviter" as `0x${string}`,
  "0xavatar_to_migrate" as `0x${string}`,
  { name: "Alice", description: "Migrated from V1" },
  ["0xtrust1", "0xtrust2"]
);
// On-chain transaction — requires xDAI for gas
```

--------------------------------

### JSON-RPC Explorer - `circles_getTotalBalance`

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Retrieves the total balance for a given address, optionally including all token balances.

```APIDOC
## circles_getTotalBalance

### Description
Gets the total balance for a given address. If `includeAll` is true, it returns the balance for all token types.

### Method
POST

### Endpoint
/circles_getTotalBalance

### Parameters
- **address** (string) - Required - The address to query.
- **includeAll** (boolean) - Optional - Whether to include balances for all token types.

### Request Example
```bash
curl -X POST https://rpc.aboutcircles.com/circles_getTotalBalance \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"circles_getTotalBalance","params":["0x42cedde51198d1773590311e2a340dc06b24cb37",true]}'
```

### Response
#### Success Response (200)
- **result** (string) - The total balance in atto-CRC.
```

--------------------------------

### Gnosis Chain Config

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Reads the canonical `CirclesConfig` for Gnosis Chain (chain ID 100) from the SDK's built-in registry. Throws at startup if the chain config is missing.

```APIDOC
## `appCirclesConfig` — Gnosis Chain Config

Reads the canonical `CirclesConfig` for Gnosis Chain (chain ID 100) from the SDK's built-in registry. Throws at startup if the chain config is missing.

```ts
// config/circles.ts
import { appCirclesConfig } from "@/config/circles";
// appCirclesConfig === circlesConfig[100]
// Contains: hub address, RPC endpoints, subgraph URLs, etc.
console.log(appCirclesConfig);
```
```

--------------------------------

### Create or Update Avatar Profile

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Upserts an avatar's on-chain profile (name, description, and additional fields). Requires the wallet to be the avatar owner and xDAI for gas on Gnosis Chain.

```typescript
const { sdk } = useCircles();

const result = await sdk.createOrUpdateProfile({
  name: "Alice",
  description: "Building on Circles since 2024",
});
// Sends an on-chain transaction; resolves when confirmed
// Requires xDAI for gas on Gnosis Chain
```

--------------------------------

### sdk.coreMembersGroupDeployer.deployGroup

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Deploys a Core Members Group (CMG) with advanced governance and customizable features. This is an on-chain transaction that returns the group address upon confirmation.

```APIDOC
## Groups Lab — `sdk.coreMembersGroupDeployer.deployGroup`

### Description
Deploys a **Core Members Group** (CMG) — a group with advanced governance, customizable mint/redemption handlers, and fine-grained member management.

### Method
```ts
await sdk.coreMembersGroupDeployer.deployGroup({
  name: "My Core Group",
  symbol: "MCG",
  description: "A Core Members Group on Circles V2",
});
```

### Parameters
#### Request Body
- **name** (string) - Required - The name of the group.
- **symbol** (string) - Required - The symbol for the group.
- **description** (string) - Optional - A description for the group.

### Response
On-chain transaction — returns group address on confirmation.
```

--------------------------------

### Stream Events using circles_events

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Streams on-chain events. Requires an address, block range, event types, and optional cursor/direction.

```bash
curl -X POST https://rpc.aboutcircles.com/circles_events \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "circles_events",
    "params": [
      "0x42cedde51198d1773590311e2a340dc06b24cb37",
      38000000,
      null,
      ["CrcV1_Trust"],
      null,
      false
    ]
  }'
```

--------------------------------

### JSON-RPC Explorer - `circles_getCommonTrust`

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Finds common trust relationships between two given addresses.

```APIDOC
## circles_getCommonTrust

### Description
Finds common trust relationships between two given addresses.

### Method
POST

### Endpoint
/circles_getCommonTrust

### Parameters
- **addressA** (string) - Required - The first address.
- **addressB** (string) - Required - The second address.

### Request Example
```bash
curl -X POST https://rpc.aboutcircles.com/circles_getCommonTrust \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"circles_getCommonTrust","params":["0xaddress_a","0xaddress_b"]}'
```
```

--------------------------------

### sdk.data.getTotalBalanceV2 + sdk.data.getTokenBalances

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Fetches both the aggregated total balance and the per-token balance breakdown for a specified group or avatar address.

```APIDOC
## Groups Lab — `sdk.data.getTotalBalanceV2` + `sdk.data.getTokenBalances`

### Description
Fetches both the aggregated total balance and the per-token balance breakdown for a group or avatar.

### Method
```ts
const addr = "0xgroup_address" as `0x${string}`;
const [totalBalance, tokenBalances] = await Promise.all([
  sdk.data.getTotalBalanceV2(addr, true),  // includeZero = true
  sdk.data.getTokenBalances(addr),
]);
```

### Parameters
#### Query Parameters (for `sdk.data.getTotalBalanceV2`)
- **address** (`0x${string}`) - Required - The address to query the total balance for.
- **includeZero** (boolean) - Optional - Whether to include tokens with zero balance.

#### Query Parameters (for `sdk.data.getTokenBalances`)
- **address** (`0x${string}`) - Required - The address to query token balances for.

### Response
- **totalBalance** (string) - The aggregated total balance in wei.
- **tokenBalances** (Array<object>) - An array of objects, each containing `tokenAddress`, `balance`, etc., for each token.
```

--------------------------------

### sdk.data.getTokenInfo

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Fetches metadata for a specific Circles token, including its type, owner, and decimals.

```APIDOC
## Groups Lab — `sdk.data.getTokenInfo`

### Description
Fetches metadata for a specific Circles token (type, owner, decimals, etc.).

### Method
```ts
const tokenInfo = await sdk.data.getTokenInfo(
  "0xtoken_address" as `0x${string}`
);
```

### Parameters
#### Query Parameters
- **tokenAddress** (`0x${string}`) - Required - The address of the token.

### Response
- **tokenInfo** (object) - An object containing token metadata, including `tokenAddress`, `tokenType`, `owner`, etc.
```

--------------------------------

### sdk.data.getEvents

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Queries indexed on-chain events for a given address, with options for block range and event type filtering.

```APIDOC
## Groups Lab — `sdk.data.getEvents`

### Description
Queries indexed on-chain events for an address within an optional block range, with optional event-type filtering.

### Method
```ts
const events = await sdk.data.getEvents(
  "0xgroup_address" as `0x${string}`,
  38000000,          // fromBlock (optional)
  undefined,         // toBlock (optional, null = latest)
  ["CrcV2_Trust"]    // eventTypes (optional)
);
```

### Parameters
#### Query Parameters
- **address** (`0x${string}`) - Required - The address to query events for.
- **fromBlock** (number) - Optional - The starting block number.
- **toBlock** (number | null) - Optional - The ending block number (null for latest).
- **eventTypes** (Array<string>) - Optional - An array of event types to filter by.

### Response
- **events** (Array<object>) - An array of event objects, each containing `blockNumber`, `transactionHash`, `event`, etc.
```

--------------------------------

### Register Group V2

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Registers a new Circles V2 Group avatar with a specified mint policy address. Requires xDAI for gas.

```typescript
const { sdk } = useCircles();

const result = await sdk.registerGroupV2(
  "0xmint_policy_address" as `0x${string}`,
  { name: "My Group", description: "A circles group", symbol: "MG" }
);
// On-chain transaction — requires xDAI for gas
```

--------------------------------

### JSON-RPC Explorer - `circles_getBalanceBreakdown`

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Provides a fast, indexed breakdown of balances per CRC token for a given address.

```APIDOC
## circles_getBalanceBreakdown

### Description
Provides a fast indexed breakdown of balances per CRC token for a given address.

### Method
POST

### Endpoint
/circles_getBalanceBreakdown

### Parameters
- **address** (string) - Required - The address to query.

### Request Example
```bash
curl -X POST https://rpc.aboutcircles.com/circles_getBalanceBreakdown \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"circles_getBalanceBreakdown","params":["0x42cedde51198d1773590311e2a340dc06b24cb37"]}'
```
```

--------------------------------

### Retrieve Group Treasury Address and Token Balances

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

First retrieves the treasury address for a given group, then queries the token balances held by that treasury. Requires a valid group address.

```typescript
const { sdk } = useCircles();

const groupAddress = "0xgroup_address" as `0x${string}`;

// Step 1: get treasury address
const treasuryAddr = await sdk.v2Hub?.treasuries(groupAddress);
if (!treasuryAddr) throw new Error("No treasury found");

// Step 2: get balances held by the treasury
const balances = await sdk.data.getTokenBalances(treasuryAddr as `0x${string}`);
// { treasuryAddress: "0x...", balances: [...] }
```

--------------------------------

### Deploy Core Members Group (CMG)

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Deploys a Core Members Group (CMG) with advanced governance features. Ensure the CMG deployer is available before use. This operation is an on-chain transaction.

```typescript
const { sdk } = useCircles();

// sdk.coreMembersGroupDeployer must be non-null
if (!sdk.coreMembersGroupDeployer) throw new Error("CMG deployer not available");

const result = await sdk.coreMembersGroupDeployer.deployGroup({
  name: "My Core Group",
  symbol: "MCG",
  description: "A Core Members Group on Circles V2",
});
// On-chain transaction — returns group address on confirmation
```

--------------------------------

### circlesV2_findPath

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Finds a multi-hop path for token transfers between two avatars, returning the allocation and maximum flow.

```APIDOC
## POST /circlesV2_findPath

### Description
Finds a multi-hop path for token transfers between two avatars, returning the allocation and maximum flow.

### Method
POST

### Endpoint
https://rpc.aboutcircles.com/circlesV2_findPath

### Request Body
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "circlesV2_findPath",
  "params": [
    {
      "Source": "0xsender_address",
      "Sink": "0xreceiver_address",
      "TargetFlow": "99999999999999999999999999999999999"
    }
  ]
}
```

### Response
#### Success Response (200)
Returns multi-hop path allocation: `{ transfers: [...], maxFlow: "..." }`
```

--------------------------------

### JSON-RPC Explorer - `circles_getTokenBalances`

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Retrieves the raw on-chain CRC token balances for a given address.

```APIDOC
## circles_getTokenBalances

### Description
Returns on-chain raw CRC token balances per token address for a given address.

### Method
POST

### Endpoint
/circles_getTokenBalances

### Parameters
- **address** (string) - Required - The address to query.

### Request Example
```bash
curl -X POST https://rpc.aboutcircles.com/circles_getTokenBalances \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"circles_getTokenBalances","params":["0x42cedde51198d1773590311e2a340dc06b24cb37"]}'
```
```

--------------------------------

### Group Administration: Ownership, Service, and Membership

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Administrative operations for group owners: transfer ownership, update the service address, or enable/disable membership conditions. The `setMembershipCondition` method is specific to Base Groups.

```typescript
const { sdk } = useCircles();

// Load the group avatar using the group's address (not the connected wallet)
const groupAvatar = await sdk.getAvatar("0xgroup_address" as `0x${string}`);

// Transfer ownership
await groupAvatar.setOwner("0xnew_owner" as `0x${string}`);

// Update service address
await groupAvatar.setService("0xnew_service" as `0x${string}`);

// Enable a membership condition contract (Base Groups only)
await groupAvatar.setMembershipCondition(
  "0xcondition_contract" as `0x${string}`,
  true // true = enable, false = disable
);

```

--------------------------------

### sdk.data.getGroupMemberships

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Retrieves all groups that a given avatar is a member of, with support for pagination.

```APIDOC
## Groups Lab — `sdk.data.getGroupMemberships`

### Description
Returns all groups that a given avatar is a member of, with pagination.

### Method
```ts
const query = sdk.data.getGroupMemberships(
  "0xavatar_address" as `0x${string}`,
  20 // page size
);

await query.queryNextPage();
const memberships = query.currentPage?.results ?? [];
```

### Parameters
#### Query Parameters
- **avatarAddress** (`0x${string}`) - Required - The address of the avatar to query memberships for.
- **pageSize** (number) - Required - The number of results per page.

### Response
- **memberships** (Array<object>) - An array of group membership records.
```

--------------------------------

### Filter V2 Avatars

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Batch-checks a list of addresses and returns only those that are registered as V2 avatars, using parallel `sdk.data.getAvatarInfo` calls.

```APIDOC
## Avatar Lab — Filter V2 Avatars

Batch-checks a list of addresses and returns only those that are registered as V2 avatars, using parallel `sdk.data.getAvatarInfo` calls.

```ts
const { sdk } = useCircles();

const addresses = [
  "0xabc...",
  "0xdef...",
  "0x123...",
];

const infos = await Promise.all(
  addresses.map(async (addr) => {
    const info = await sdk.data.getAvatarInfo(addr as `0x${string}`);
    return { address: addr, type: info?.type, version: info?.version };
  })
);

const v2Avatars = infos.filter((r) => r.version === 2);
// [{ address: "0xabc...", type: "human", version: 2 }, ...]
```
```

--------------------------------

### Mint Group Tokens with Collateral

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Mints group tokens by depositing personal Circles tokens as collateral into the group treasury. This operation requires xDAI for gas fees.

```typescript
const { sdk } = useCircles();
const { address } = useAccount();

const avatar = await sdk.getAvatar(address as `0x${string}`);

await avatar.groupMint(
  "0xgroup_address" as `0x${string}`,
  ["0xcollateral_token1", "0xcollateral_token2"] as `0x${string}`[],
  [BigInt("1000000000000000000"), BigInt("500000000000000000")], // amounts in atto-CRC
  new Uint8Array(0) // empty data payload
);
// Sends on-chain transaction — requires xDAI for gas

```

--------------------------------

### JSON-RPC Explorer - `circles_getTrustRelations`

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Retrieves trust relations for a given address, including who the address trusts and who trusts the address.

```APIDOC
## circles_getTrustRelations

### Description
Retrieves trust relations for a given address, including lists of addresses it trusts and addresses that trust it.

### Method
POST

### Endpoint
/circles_getTrustRelations

### Parameters
- **address** (string) - Required - The address to query.

### Request Example
```bash
curl -X POST https://rpc.aboutcircles.com/circles_getTrustRelations \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"circles_getTrustRelations","params":["0x42cedde51198d1773590311e2a340dc06b24cb37"]}'
```

### Response
#### Success Response (200)
- **result** (object) - An object containing `trusts` and `trustedBy` arrays.
```

--------------------------------

### Filter V2 Avatars

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Batch-checks a list of addresses and returns only those that are registered as V2 avatars, using parallel sdk.data.getAvatarInfo calls.

```typescript
const { sdk } = useCircles();

const addresses = [
  "0xabc...",
  "0xdef...",
  "0x123...",
];

const infos = await Promise.all(
  addresses.map(async (addr) => {
    const info = await sdk.data.getAvatarInfo(addr as `0x${string}`);
    return { address: addr, type: info?.type, version: info?.version };
  })
);

const v2Avatars = infos.filter((r) => r.version === 2);
// [{ address: "0xabc...", type: "human", version: 2 }, ...]
```

--------------------------------

### circles_events

Source: https://context7.com/aboutcircles/circles-dev-kit/llms.txt

Streams on-chain events for a given address, filtering by event types and block range.

```APIDOC
## POST /circles_events

### Description
Streams on-chain events for a given address, filtering by event types and block range.

### Method
POST

### Endpoint
https://rpc.aboutcircles.com/circles_events

### Parameters
#### Path Parameters
- **address** (string) - Required - The address to monitor events for.
- **fromBlock** (number) - Required - The block number to start streaming from.
- **toBlock** (number | null) - Optional - The block number to stop streaming at.
- **eventTypes** (string[]) - Optional - An array of event types to filter by.
- **cursor** (any | null) - Optional - A cursor for pagination.
- **descending** (boolean) - Optional - Whether to stream events in descending order.

### Request Body
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "circles_events",
  "params": [
    "0x42cedde51198d1773590311e2a340dc06b24cb37",
    38000000,
    null,
    ["CrcV1_Trust"],
    null,
    false
  ]
}
```

### Response
#### Success Response (200)
Streams on-chain events.
```