docs: add WalletConnect AI Agent SDK section

agents/overview.mdx

@@ -0,0 +1,333 @@
+---
+title: "WalletConnect Agents SDK"
+sidebarTitle: "Overview"
+
+metatags:
+  description: "WalletConnect Agent SDK — CLI tools and libraries for wallet connection, signing, cross-chain bridging, and WCT staking from the terminal or any AI agent environment."
+---
+
+The **WalletConnect Agents SDK** is a monorepo of CLI tools and libraries that bring WalletConnect capabilities to the terminal and AI agent environments. It enables wallet connection, message signing, cross-chain bridging, and WCT staking without a browser UI.
+
+<Note>
+  **Beta (v0.1.x)** — This project is under active development. APIs and CLI interfaces may change between releases. Not yet recommended for production use.
+</Note>
+
+## Packages
+
+<table>
+  <thead>
+    <tr>
+      <th>Package</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td style={{ whiteSpace: "nowrap" }}>
+        <a href="https://www.npmjs.com/package/@walletconnect/pay-cli"><code>@walletconnect/pay-cli</code></a>
+      </td>
+      <td>Create and complete WalletConnect Pay payments from the terminal</td>
+    </tr>
+    <tr>
+      <td style={{ whiteSpace: "nowrap" }}>
+        <a href="https://www.npmjs.com/package/@walletconnect/cli-sdk"><code>@walletconnect/cli-sdk</code></a>
+      </td>
+      <td>Wallet connection, signing, and cross-chain swidge for terminal apps</td>
+    </tr>
+    <tr>
+      <td style={{ whiteSpace: "nowrap" }}>
+        <a href="https://www.npmjs.com/package/@walletconnect/staking-cli"><code>@walletconnect/staking-cli</code></a>
+      </td>
+      <td>WCT staking on Optimism — stake, unstake, claim rewards</td>
+    </tr>
+  </tbody>
+</table>
+
+## Install
+
+```bash
+npm install -g @walletconnect/cli-sdk @walletconnect/staking-cli
+```
+
+Get a Project ID from [WalletConnect Cloud](https://cloud.walletconnect.com), then configure it:
+
+```bash
+walletconnect config set project-id <your-project-id>
+# or
+export WALLETCONNECT_PROJECT_ID=<your-project-id>
+```
+
+---
+
+## WalletConnect Pay CLI
+
+<Warning>
+  **Experimental** — This package is under active development. APIs, commands, and behavior may change significantly between releases.
+</Warning>
+
+Create and complete WalletConnect Pay payments from the terminal. Supports proxy mode (no API keys needed) and direct API mode.
+
+### Commands
+
+```
+Usage: walletconnect-pay <command> [options]
+
+Commands:
+  status <paymentId>     Check the status of a payment
+  create <amount>        Create a new payment (merchant credentials required)
+  checkout <paymentId>   Complete a payment using a connected wallet
+
+Options:
+  --staging              Use the staging API
+  --proxy                Proxy through frontend (no API keys needed)
+  --help                 Show this help message
+```
+
+### Authentication
+
+By default, the CLI proxies through the WalletConnect Pay frontend — no API keys needed. For direct API access:
+
+```bash
+export WC_PAY_WALLET_API_KEY=<wallet-api-key>
+
+# Required for merchant operations
+export WC_PAY_PARTNER_API_KEY=<partner-api-key>
+export WC_PAY_MERCHANT_ID=<merchant-id>
+```
+
+### Travel Rule compliance
+
+Some payments require Information Capture data. Provide via CLI flags or environment variables:
+
+```bash
+walletconnect-pay checkout <id> \
+  --name "John Doe" \
+  --dob "1990-01-15" \
+  --pob-country "US" \
+  --pob-address "New York, NY"
+```
+
+Or via environment variables:
+
+```bash
+export WC_PAY_NAME="John Doe"
+export WC_PAY_DOB="1990-01-15"
+export WC_PAY_POB_COUNTRY="US"
+export WC_PAY_POB_ADDRESS="New York, NY"
+```
+
+### Examples
+
+```bash
+# Check a payment's status
+walletconnect-pay status pay_abc123 --staging
+
+# Create a $10 payment (1000 = minor units / cents)
+walletconnect-pay create 1000 --staging
+
+# Complete a payment with a connected wallet
+walletconnect-pay checkout pay_abc123 --staging
+```
+
+### Programmatic usage
+
+```typescript
+import { createPayClient, createFrontendPayClient } from "@walletconnect/pay-cli";
+
+// Direct API client
+const client = createPayClient({
+  walletApiKey: "your-wallet-api-key",
+  sdkVersion: "0.5.0",
+  staging: true,
+});
+
+// Proxy through the frontend (no API keys needed)
+const proxyClient = createFrontendPayClient({
+  frontendUrl: "https://staging.pay.walletconnect.com",
+});
+
+const payment = await client.getPayment("pay_abc123");
+```
+
+---
+
+## WalletConnect CLI
+
+Connect a wallet, sign messages, send transactions, and bridge tokens across chains from the terminal.
+
+### Commands
+
+```
+Usage: walletconnect <command> [options]
+
+Commands:
+  connect                       Connect to a wallet via QR code
+  whoami                        Show current session info
+  sign <message>                Sign a message with the connected wallet
+  sign-typed-data <json>        Sign EIP-712 typed data (JSON string)
+  send-transaction <json>       Send a transaction (EVM or Solana)
+  swidge                        Bridge/swap tokens across chains via LI.FI
+  disconnect                    Disconnect the current session
+  config set <k> <v>            Set a config value (e.g. project-id)
+  config get <k>                Get a config value
+
+Options:
+  --browser            Use browser UI instead of terminal QR code
+  --json               Output as JSON (for whoami)
+  --chain <id>         Specify chain (e.g. evm, solana, eip155:10) for connect
+  --version            Show version number
+  --help               Show this help message
+```
+
+### Examples
+
+```bash
+# Connect a wallet (shows QR code in terminal)
+walletconnect connect
+
+# Connect using a browser-based QR code
+walletconnect connect --browser
+
+# Sign a message
+walletconnect sign "Hello from the terminal"
+
+# Check connected wallet
+walletconnect whoami
+
+# Send a transaction on Optimism
+walletconnect send-transaction '{"to":"0x...","value":"0x0","chainId":"eip155:10"}'
+
+# Disconnect
+walletconnect disconnect
+```
+
+### Swidge (Cross-Chain Bridge/Swap)
+
+Bridge or swap tokens across EVM chains, powered by [LI.FI](https://li.fi). The connected wallet approves and executes each transaction.
+
+```bash
+# Bridge 5 WCT from Optimism to Ethereum mainnet
+walletconnect swidge --from-chain eip155:10 --to-chain eip155:1 \
+  --from-token WCT --to-token WCT --amount 5
+
+# Swap USDC on Base to ETH on Optimism
+walletconnect swidge --from-chain eip155:8453 --to-chain eip155:10 \
+  --from-token USDC --to-token ETH --amount 10
+
+# Bridge ETH from Ethereum to Base
+walletconnect swidge --from-chain eip155:1 --to-chain eip155:8453 \
+  --amount 0.01
+```
+
+When sending a transaction, the CLI automatically checks if the connected wallet has sufficient ETH on the target chain. If funds are insufficient:
+
+- **Interactive (TTY):** Prompts you to bridge from another chain
+- **Pipe / agent mode:** Auto-bridges from the chain with the most funds
+
+### Programmatic usage
+
+```typescript
+import { WalletConnectCLI, withWallet } from "@walletconnect/cli-sdk";
+
+// High-level helper — connect → use → cleanup
+await withWallet(
+  {
+    projectId: "your-project-id",
+    metadata: { name: "My App", description: "...", url: "...", icons: [] },
+  },
+  async (wallet, { accounts }) => {
+    const txHash = await wallet.request({
+      chainId: "eip155:1",
+      request: {
+        method: "eth_sendTransaction",
+        params: [{ from: accounts[0].split(":").pop(), to: "0x...", value: "0x0" }],
+      },
+    });
+  },
+);
+
+// Direct client usage
+const wallet = new WalletConnectCLI({
+  projectId: "your-project-id",
+  metadata: { name: "My App", description: "...", url: "...", icons: [] },
+  chains: ["eip155:1", "eip155:10"],
+  ui: "browser", // or "terminal" (default)
+});
+
+const { accounts } = await wallet.connect();
+const signature = await wallet.request({
+  chainId: "eip155:1",
+  request: { method: "personal_sign", params: ["0x48656c6c6f", accounts[0]] },
+});
+await wallet.disconnect();
+await wallet.destroy();
+```
+
+---
+
+## WalletConnect Staking CLI
+
+Stake WCT tokens on Optimism, check staking positions, and claim rewards.
+
+### Commands
+
+```
+Usage: walletconnect-staking <command> [options]
+
+Commands:
+  stake <amount> <weeks>   Stake WCT (approve + createLock/updateLock)
+  unstake                  Withdraw all staked WCT (after lock expires)
+  claim                    Claim staking rewards
+  status                   Show staking position, rewards, and APY
+  balance                  Show WCT token balance
+
+Options:
+  --address=0x...          Use address directly (for read-only commands)
+  --browser                Use browser UI for wallet connection
+  --help                   Show this help message
+```
+
+### Examples
+
+```bash
+# Stake 1000 WCT for 52 weeks
+walletconnect-staking stake 1000 52
+
+# Check staking position and rewards (read-only, no wallet needed)
+walletconnect-staking status --address=0x...
+
+# Check WCT balance
+walletconnect-staking balance --address=0x...
+
+# Claim staking rewards (requires wallet)
+walletconnect-staking claim
+
+# Withdraw all staked WCT (after lock expires)
+walletconnect-staking unstake
+```
+
+### Programmatic usage
+
+```typescript
+import { stake, status, balance, fetchStaking, formatWCT } from "@walletconnect/staking-cli";
+```
+
+The staking package exports transaction builders, formatting utilities, and API helpers for building custom staking integrations.
+
+---
+
+## Agent Skills
+
+Install the accompanying Claude Code / agent skills:
+
+```bash
+npx skills add WalletConnect/agent-sdk
+```
+
+This adds the `walletconnect-pay`, `walletconnect`, and `walletconnect-staking` skills to your Claude Code environment, enabling AI agents to interact with wallets and payments directly from the terminal.
+
+## Source
+
+<Card title="WalletConnect Agent SDK" icon="github" href="https://github.com/walletconnect/agent-sdk">
+  View the source, file issues, and contribute on GitHub.
+</Card>

docs.json

@@ -76,6 +76,12 @@
                 "pages": [
                   "payments/ecommerce/overview"
                 ]
+              },
+              {
+                "group": "WalletConnect AI Agent SDK",
+                "pages": [
+                  "agents/overview"
+                ]
               }
             ]
           },
@@ -193,6 +199,12 @@
                 "pages": [
                   "payments/ecommerce/overview"
                 ]
+              },
+              {
+                "group": "WalletConnect AI Agent SDK",
+                "pages": [
+                  "agents/overview"
+                ]
               }
             ]
           },