feat: add new examples and housekeeping tasks

README.md

@@ -33,6 +33,32 @@ adapter. Connects to any EIP-6963 browser wallet (e.g., MetaMask).
 
 Run with `npm install && npm run dev`.
 
+### [`app-kit-swap`](./app-kit-swap)
+
+Browser app that estimates and swaps USDC for EURC on Arc Testnet using
+[App Kit](https://www.npmjs.com/package/@circle-fin/app-kit) with the viem
+adapter. Connects to any EIP-6963 browser wallet (e.g., MetaMask).
+
+Run with `npm install && npm run dev`.
+
+### [`app-kit-transfer-widget`](./app-kit-transfer-widget)
+
+React app that embeds a USDC transfer widget with
+[App Kit](https://www.npmjs.com/package/@circle-fin/app-kit). Supports same-chain
+`send()` and crosschain `bridge()` flows for EVM and Solana browser wallets,
+including estimate, review, and retry.
+
+Run with `npm install && npm run dev`.
+
+### [`app-kit-unified-balance`](./app-kit-unified-balance)
+
+Browser app that deposits USDC into a unified balance from Base Sepolia and
+Solana Devnet, reads the balance, and spends it on Arc Testnet using
+[App Kit](https://www.npmjs.com/package/@circle-fin/app-kit) with the viem and
+Solana adapters. Connects an EVM wallet and a Solana wallet.
+
+Run with `npm install && npm run dev`.
+
 ### [`entity-secret-setup`](./entity-secret-setup)
 
 Node.js script that generates a new entity secret, registers it with Circle,

app-kit-bridge-evm/README.md

@@ -0,0 +1,45 @@
+# Bridge USDC between EVM chains
+
+Use [`@circle-fin/app-kit`](https://www.npmjs.com/package/@circle-fin/app-kit)
+to bridge USDC from Ethereum Sepolia to Arc Testnet with a browser wallet and
+the viem adapter.
+
+This Vite + TypeScript page connects an EIP-6963 wallet (for example MetaMask),
+creates a Circle adapter from the provider, then calls `bridge()` and
+`retryBridge()` when needed.
+
+## Prerequisites
+
+- [Node.js 22 or later](https://nodejs.org/)
+- An EIP-6963 browser wallet such as MetaMask
+- Testnet USDC on Ethereum Sepolia
+- Native gas token on Ethereum Sepolia for the wallet transaction
+
+This project does not require environment variables or API keys.
+
+## Install and run
+
+```bash
+npm install
+npm run dev
+```
+
+Open the local Vite URL in a browser with your wallet installed.
+
+```bash
+npm run build
+```
+
+## What this example does
+
+1. Discovers an EIP-6963 browser wallet and requests account access.
+2. Creates a viem adapter with `createViemAdapterFromProvider()`.
+3. Bridges 1 USDC from `Ethereum_Sepolia` to `Arc_Testnet` with `kit.bridge()`.
+4. Retries with `kit.retryBridge()` if the result state is `"error"`.
+5. Streams App Kit action events into the on-page output panel.
+
+## Key file
+
+- `src/main.ts` — wallet connect, adapter creation, bridge, and retry.
+  Change `from` / `to` `chain` and `amount` in the bridge call for different
+  chains or amounts.

app-kit-bridge-evm/package.json

@@ -9,11 +9,11 @@
   },
   "devDependencies": {
     "typescript": "~7.0.2",
-    "vite": "^8.2.0"
+    "vite": "^8.2.1"
   },
   "dependencies": {
-    "@circle-fin/app-kit": "^1.11.0",
-    "@circle-fin/adapter-viem-v2": "^1.14.1",
-    "viem": "^2.55.11"
+    "@circle-fin/app-kit": "^1.12.0",
+    "@circle-fin/adapter-viem-v2": "^1.15.1",
+    "viem": "^2.55.17"
   }
 }

app-kit-bridge-solana/README.md

@@ -0,0 +1,47 @@
+# Bridge USDC from Solana to EVM
+
+Use [`@circle-fin/app-kit`](https://www.npmjs.com/package/@circle-fin/app-kit)
+to bridge USDC from Solana Devnet to Arc Testnet with Solana and EVM browser
+wallets.
+
+This Vite + TypeScript page connects a Solana wallet for the source and an
+EIP-6963 EVM wallet for the destination, creates Circle adapters for both, then
+calls `bridge()` and `retryBridge()` when needed.
+
+## Prerequisites
+
+- [Node.js 22 or later](https://nodejs.org/)
+- An EIP-6963 EVM browser wallet such as MetaMask
+- A Solana browser wallet on `window.solana` such as Phantom
+- Testnet USDC on Solana Devnet
+- Native gas tokens for both wallets
+
+This project does not require environment variables or API keys.
+
+## Install and run
+
+```bash
+npm install
+npm run dev
+```
+
+Open the local Vite URL in a browser with both wallets installed.
+
+```bash
+npm run build
+```
+
+## What this example does
+
+1. Connects an EIP-6963 EVM wallet for the Arc Testnet destination.
+2. Connects a Solana browser wallet for the Solana Devnet source.
+3. Creates viem and Solana adapters from the connected providers.
+4. Bridges 1 USDC from `Solana_Devnet` to `Arc_Testnet` with `kit.bridge()`.
+5. Retries with `kit.retryBridge()` if the result state is `"error"`.
+6. Streams App Kit action events into the on-page output panel.
+
+## Key file
+
+- `src/main.ts` — wallet connect, adapter creation, bridge, and retry.
+  Change `from` / `to` `chain` and `amount` in the bridge call for different
+  chains or amounts.

app-kit-bridge-solana/package.json

@@ -9,12 +9,12 @@
   },
   "devDependencies": {
     "typescript": "~7.0.2",
-    "vite": "^8.2.0"
+    "vite": "^8.2.1"
   },
   "dependencies": {
-    "@circle-fin/adapter-solana": "^1.6.4",
-    "@circle-fin/adapter-viem-v2": "^1.14.1",
-    "@circle-fin/app-kit": "^1.11.0",
-    "viem": "^2.55.11"
+    "@circle-fin/adapter-solana": "^1.6.5",
+    "@circle-fin/adapter-viem-v2": "^1.15.1",
+    "@circle-fin/app-kit": "^1.12.0",
+    "viem": "^2.55.17"
   }
 }

app-kit-send/README.md

@@ -0,0 +1,44 @@
+# Send USDC on an EVM chain
+
+Use [`@circle-fin/app-kit`](https://www.npmjs.com/package/@circle-fin/app-kit)
+to estimate and send USDC on Arc Testnet with a browser wallet and the viem
+adapter.
+
+This Vite + TypeScript page connects an EIP-6963 wallet (for example MetaMask),
+creates a Circle adapter from the provider, then calls `estimateSend()` and
+`send()`.
+
+## Prerequisites
+
+- [Node.js 22 or later](https://nodejs.org/)
+- An EIP-6963 browser wallet such as MetaMask
+- Testnet USDC on Arc Testnet
+- Native gas token on Arc Testnet for the wallet transaction
+
+This project does not require environment variables or API keys.
+
+## Install and run
+
+```bash
+npm install
+npm run dev
+```
+
+Open the local Vite URL in a browser with your wallet installed.
+
+```bash
+npm run build
+```
+
+## What this example does
+
+1. Discovers an EIP-6963 browser wallet and requests account access.
+2. Creates a viem adapter with `createViemAdapterFromProvider()`.
+3. Estimates the transfer with `kit.estimateSend()`.
+4. Sends 1 USDC on `Arc_Testnet` to the entered recipient with `kit.send()`.
+
+## Key file
+
+- `src/main.ts` — wallet connect, adapter creation, estimate, and send.
+  Change `chain`, `amount`, and `token` in the send params for a different
+  chain, amount, or token.

app-kit-send/package.json

@@ -9,11 +9,11 @@
   },
   "devDependencies": {
     "typescript": "~7.0.2",
-    "vite": "^8.2.0"
+    "vite": "^8.2.1"
   },
   "dependencies": {
-    "@circle-fin/adapter-viem-v2": "^1.14.1",
-    "@circle-fin/app-kit": "^1.11.0",
-    "viem": "^2.55.11"
+    "@circle-fin/adapter-viem-v2": "^1.15.1",
+    "@circle-fin/app-kit": "^1.12.0",
+    "viem": "^2.55.17"
   }
 }

app-kit-swap/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

app-kit-swap/README.md

@@ -0,0 +1,68 @@
+# Swap USDC on Arc Testnet
+
+Use [`@circle-fin/app-kit`](https://www.npmjs.com/package/@circle-fin/app-kit)
+to estimate and swap USDC for EURC on Arc Testnet with a browser wallet and the
+viem adapter.
+
+This Vite + TypeScript page connects an EIP-6963 wallet (for example MetaMask),
+creates a Circle adapter from the provider, then calls `estimateSwap()` and
+`swap()`.
+
+## Prerequisites
+
+- [Node.js 22 or later](https://nodejs.org/)
+- An EIP-6963 browser wallet such as MetaMask
+- Testnet USDC on Arc Testnet
+- Native gas token on Arc Testnet for the wallet transaction
+
+This project does not require environment variables or API keys.
+
+## Install and run
+
+```bash
+npm install
+npm run dev
+```
+
+Open the local Vite URL in a browser with your wallet installed.
+
+```bash
+npm run build
+```
+
+## What this example does
+
+1. Discovers an EIP-6963 browser wallet and requests account access.
+2. Creates a viem adapter with `createViemAdapterFromProvider()`.
+3. Estimates the swap with `kit.estimateSwap()`.
+4. Swaps 1 USDC for EURC on `Arc_Testnet` with `kit.swap()`.
+
+## Thin liquidity on Arc Testnet
+
+Arc Testnet swap pools are often thin or imbalanced. Quotes and swaps can fail
+even when your code and wallet setup are correct. This is an environment
+limitation on testnet, not a bug in your integration.
+
+Common errors:
+
+- **No route available** — the swap router could not find a quote for that pair
+  or amount (liquidity path missing or temporarily unavailable).
+- **On-chain simulation failed** — a quote existed, but the pool could not meet
+  the minimum output under the configured slippage.
+
+If you hit either error:
+
+1. Retry with a smaller `amountIn` (for example `0.1` or `1` USDC).
+2. Prefer `EURC → USDC` when probing for available depth — Arc Testnet pools
+   are often USDC-heavy, so that direction usually has less price impact.
+3. Optionally raise `config.slippageBps` above the default `300` (3%) for
+   testnet experiments.
+4. Retry later — testnet liquidity and routing availability change over time.
+
+Use mainnet liquidity expectations only after you move off Arc Testnet.
+
+## Key file
+
+- `src/main.ts` — wallet connect, adapter creation, estimate, and swap.
+  Change `chain`, `tokenIn` / `tokenOut`, and `amountIn` in the swap params
+  for a different chain, pair, or amount.

app-kit-swap/index.html

@@ -0,0 +1,60 @@
+<!doctype html>
+<!--
+ Copyright 2026 Circle Internet Group, Inc. All rights reserved.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ SPDX-License-Identifier: Apache-2.0
+-->
+
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Swap USDC on Arc Testnet</title>
+    <style>
+      header > div {
+        display: flex;
+        align-items: center;
+        gap: 0.5em;
+        margin-block-end: 1em;
+      }
+      p {
+        margin: 0;
+      }
+      pre:not(:empty) {
+        background-color: ghostwhite;
+        padding: 1em;
+        max-width: 100%;
+        overflow: auto;
+        border-radius: 0.5em;
+        max-height: calc(100vh - 9em);
+        word-break: break-all;
+        white-space: pre-wrap;
+      }
+    </style>
+  </head>
+  <body>
+    <header>
+      <div>
+        <button id="connectWallet">Connect wallet</button>
+        <p id="walletInfo"></p>
+      </div>
+    </header>
+    <main>
+      <button id="swap" disabled>Swap USDC</button>
+      <pre id="output"></pre>
+    </main>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

app-kit-swap/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "app-kit-swap",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview"
+  },
+  "devDependencies": {
+    "typescript": "~7.0.2",
+    "vite": "^8.2.1"
+  },
+  "dependencies": {
+    "@circle-fin/adapter-viem-v2": "^1.15.1",
+    "@circle-fin/app-kit": "^1.12.0",
+    "viem": "^2.55.17"
+  }
+}