docs: update SDK provider setup for 0.16 wagmi-opt-in 2026-05-26 (#89)

* docs: update SDK provider setup for 0.16 wagmi-opt-in 2026-05-26

Reflect the `0xtrails@0.16.0` change that makes wagmi opt-in via
`@0xtrails/adapter-wagmi`. The hooks reference still showed
`WagmiProvider` as a required wrapper.

- sdk/hooks.mdx: split the provider-setup section into "Apps without
  wagmi" (default in 0.16) and "Apps with wagmi" (use the adapter).
  Drop the stale "future SDK release" note since the bundled
  runtime now exists.
- examples/wallet-compatibility.mdx: add a 0.16 note clarifying
  that wagmi is no longer required and that the existing patterns
  apply when sharing an existing wagmi session.

Source: trails @ production, 0xtrails@0.16.0 release notes; see
the published changelog at sdk/changelog/0xtrails-0.16.0.mdx.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: update resources for 0.16 chain support 2026-05-26

- Remove Xai (660279) and Blast (81457) from mainnet chain tables;
  both were dropped from `0xtrails@0.16.0` SDK chain support.
- Add HyperEVM (999) to the chain tables; added to SDK
  `ALL_CHAINS` and resolver in 0.16.
- Add missing Etherlink and Berachain entries to the fees snippet
  and the composable-actions chain identifier list so the docs
  match `SupportedChainName` in `widget/shared/resolution.ts`.

Source: trails @ production, packages/0xtrails/src/chainRegistry.ts
and packages/0xtrails/src/widget/shared/resolution.ts.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: stop tracking package-lock.json

Picked up accidentally during the docs automation run; the repo uses pnpm
and node_modules is already gitignored. Add package-lock.json to .gitignore
so future automation runs don't re-include it.

* docs: update examples for 0xtrails@0.16.0 wagmi opt-in

In 0.16, Trails no longer requires wagmi by default. Add adapter-wagmi
callouts and update the x402 Providers example to wire wagmiAdapter
through TrailsProvider so the existing wagmi-based snippets work in 0.16+.

- examples/refunds.mdx, examples/tokens-chains-prices.mdx,
  examples/transaction-history.mdx, use-cases/swap.mdx,
  sdk/modes/swap.mdx: add adapter-wagmi callouts on the wagmi-using snippets
- examples/x402.mdx: extend the Providers.tsx example to wrap in TrailsProvider
  with wagmiAdapter, and add the @0xtrails/adapter-wagmi install step
- api-reference/introduction.mdx: clarify the wagmi hooks comment to reference
  the SDK's usePublicClient and the wagmi adapter

* docs: align modes & widget typing with 0xtrails@0.16.0

In 0.16 the widget props were tightened: `from.currency` is reserved for
ISO 4217 fiat codes on the fiat-onramp arm, `from.token` is ERC-20 only,
and the destination prop name is `to.token` / `to.defaultToken` (not
`currency` / `defaultCurrency`).

- sdk/modes/swap.mdx, sdk/modes/earn.mdx, sdk/modes/withdraw.mdx:
  rewrite the Source prop tables to reflect the discriminated union on
  `paymentMethod` (crypto arms expose `from.token`, fiat arm exposes
  `from.currency`). Add new 0.16 destination-support props
  (`supportedChains`, `supportedTokensByChain`, `originSupportedChains`,
  `originSupportedTokensByChain`).
- sdk/modes/fund.mdx, sdk/modes/pay.mdx: rename destination prop rows
  (`to.currency` -> `to.token`, `to.defaultCurrency` -> `to.defaultToken`)
  and add the new destination-support props on fund.
- All widget code samples in sdk/modes/*, sdk/get-started.mdx,
  sdk/quote-providers.mdx, use-cases/swap.mdx: rename
  `currency: "<TOKEN>"` -> `token: "<TOKEN>"` and
  `defaultCurrency:` -> `defaultToken:` except for ISO 4217 fiat codes
  on the credit-card flow examples in fund.mdx, which stay as `currency`.
- sdk/configuration.mdx: drop removed `wagmiConnectors` / `decoupleWagmi`
  props and document the new `adapters` prop for wallet runtime adapters.

* docs: document new 0xtrails@0.16.0 SDK surface

Adds reference docs for the public exports introduced in 0.16 that
weren't covered by the wagmi-migration changelog page.

- Adapters: document `evmAdapter` (built-in EIP-1193 helper) and link to
  `wagmiAdapter` from @0xtrails/adapter-wagmi.
- Public clients: `usePublicClient` and `usePublicClientGetter` for
  getting viem PublicClients via the Sequence node gateway.
- Composable actions: `useResolveActions` for resolving action arrays
  into the concrete Call[] used by useTrailsSendTransaction.
- Fiat: `useFiatCurrencyList` and `useExchangeRate` for fiat-aware UI.
- Onramp: `useMeldPaymentMethods` and `useMeldServiceProviders` for
  building custom on-ramp UI on top of Mesh.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: JamesLawton

.gitignore

@@ -1,4 +1,4 @@
 scripts/node_modules
 node_modules
 .env
-.DS_Store
+.DS_Storepackage-lock.json

api-reference/introduction.mdx

@@ -152,7 +152,8 @@ import { createWalletClient, createPublicClient, http, encodeFunctionData, erc20
 import { privateKeyToAccount } from 'viem/accounts';
 import { base, arbitrum, mainnet } from 'viem/chains';
 
-// Create clients (or use wagmi hooks: useWalletClient, usePublicClient)
+// Create clients (in React, you can also use the SDK's usePublicClient hook, or
+// useWalletClient from wagmi when paired with @0xtrails/adapter-wagmi)
 const walletClient = createWalletClient({
   account: privateKeyToAccount('0x...'),
   chain: arbitrum, // Set to the origin chain
@@ -215,7 +216,8 @@ import { createWalletClient, createPublicClient, http, encodeFunctionData, erc20
 import { privateKeyToAccount } from 'viem/accounts';
 import { base, arbitrum, mainnet } from 'viem/chains';
 
-// Create clients (or use wagmi hooks: useWalletClient, usePublicClient)
+// Create clients (in React, you can also use the SDK's usePublicClient hook, or
+// useWalletClient from wagmi when paired with @0xtrails/adapter-wagmi)
 const walletClient = createWalletClient({
   account: privateKeyToAccount('0x...'),
   chain: arbitrum, // Set to the origin chain

examples/refunds.mdx

@@ -46,6 +46,10 @@ While Trails automatically refunds upon transaction failures, there may be edge
 
 ### Basic Usage
 
+<Note>
+This example uses wagmi hooks (`useWalletClient`, `useAccount`). Since [`0xtrails@0.16.0`](/sdk/changelog/0xtrails-0.16.0), wagmi is opt-in — install `@0xtrails/adapter-wagmi` and pass `wagmiAdapter({ wagmiConfig })` in `adapters` for these hooks to resolve. See [SDK Hooks](/sdk/hooks#apps-with-wagmi).
+</Note>
+
 ```tsx
 import { useIntentRecover } from '0xtrails'
 import { useWalletClient, useAccount } from 'wagmi'

examples/tokens-chains-prices.mdx

@@ -59,6 +59,10 @@ For fetching prices without balances, use the [GetTokenPrices API](/api-referenc
 
 Build a chain/token selector with live prices:
 
+<Note>
+The `useAccount` import below is from wagmi. Since [`0xtrails@0.16.0`](/sdk/changelog/0xtrails-0.16.0), wagmi is opt-in — install `@0xtrails/adapter-wagmi` and configure `wagmiAdapter` to use wagmi hooks alongside Trails. See [SDK Hooks](/sdk/hooks#apps-with-wagmi).
+</Note>
+
 ```tsx
 import { useState } from 'react'
 import { useSupportedChains, useSupportedTokens, useTokenBalances } from '0xtrails'

examples/transaction-history.mdx

@@ -6,6 +6,10 @@ icon: 'clock'
 
 Trails comes with a built in high-performant indexer which you can leverage seamlessly to retrieve information about a user's transaction history.
 
+<Note>
+The examples below import `useAccount` from wagmi. Since [`0xtrails@0.16.0`](/sdk/changelog/0xtrails-0.16.0), wagmi is opt-in — install `@0xtrails/adapter-wagmi` and configure `wagmiAdapter` to use wagmi hooks alongside Trails. See [SDK Hooks](/sdk/hooks#apps-with-wagmi).
+</Note>
+
 ## Wallet Transaction History
 
 Query a user's transaction history for a specific chain using their connected wallet address:

examples/wallet-compatibility.mdx

@@ -4,11 +4,15 @@ description: 'Comprehensive wallet integration support and compatibility across
 icon: 'wallet'
 ---
 
-Trails works with virtually all wallets through wagmi connectors, including embedded wallets like Privy, smart contract wallets like Sequence, or injected EOAs like MetaMask. This enables complex transaction orchestration cross-chain in 1-click without requiring wallets to natively support ERC-7702.
+Trails works with virtually all wallets, including embedded wallets like Privy, smart contract wallets like Sequence, or injected EOAs like MetaMask. This enables complex transaction orchestration cross-chain in 1-click without requiring wallets to natively support ERC-7702.
+
+<Note>
+Since `0xtrails@0.16.0`, Trails uses its own built-in EVM runtime by default — wagmi is no longer required. The patterns below still work for apps that share an existing wagmi session, via the `@0xtrails/adapter-wagmi` package. See the [0.16 release notes](/sdk/changelog/0xtrails-0.16.0) for the migration.
+</Note>
 
 ## How It Works
 
-Trails automatically detects and uses any wagmi connectors configured in your application. Simply wrap your app with a wagmi provider and include the desired wallet connectors in your config.
+Trails detects and uses connected wallets through its built-in runtime, or through wagmi connectors when you install the wagmi adapter. For apps that already use wagmi, wrap your app with a wagmi provider, include the desired wallet connectors in your config, and pass `wagmiAdapter({ wagmiConfig })` to `TrailsProvider`.
 
 ## Basic Wagmi Setup
 

examples/x402.mdx

@@ -87,6 +87,12 @@ Trails + x402 creates a powerful payment flow:
 pnpm add 0xtrails x402-axios axios
 ```
 
+This example pairs Trails with an existing wagmi + RainbowKit setup. Since [`0xtrails@0.16.0`](/sdk/changelog/0xtrails-0.16.0), wagmi is opt-in for Trails — also install `@0xtrails/adapter-wagmi` so Trails can share the wagmi session:
+
+```bash
+pnpm add @0xtrails/adapter-wagmi
+```
+
 #### 2. Configure Providers
 
 <CodeGroup>
@@ -95,6 +101,8 @@ import { WagmiProvider, createConfig, http } from "wagmi"
 import { RainbowKitProvider } from "@rainbow-me/rainbowkit"
 import { QueryClientProvider, QueryClient } from "@tanstack/react-query"
 import { mainnet, base } from "wagmi/chains"
+import { TrailsProvider } from "0xtrails"
+import { wagmiAdapter } from "@0xtrails/adapter-wagmi"
 
 const config = createConfig({
   chains: [mainnet, base],
@@ -107,13 +115,17 @@ const config = createConfig({
 
 const queryClient = new QueryClient()
 
+const adapters = [wagmiAdapter({ wagmiConfig: config })]
+
 export function Providers({ children }: { children: React.ReactNode }) {
   return (
     <WagmiProvider config={config}>
       <QueryClientProvider client={queryClient}>
-        <RainbowKitProvider>
-          {children}
-        </RainbowKitProvider>
+        <TrailsProvider config={{ trailsApiKey: "YOUR_TRAILS_API_KEY", adapters }}>
+          <RainbowKitProvider>
+            {children}
+          </RainbowKitProvider>
+        </TrailsProvider>
       </QueryClientProvider>
     </WagmiProvider>
   )

resources/supported-chains.mdx

@@ -18,18 +18,17 @@ Trails supports the following mainnet chains with full cross-chain routing capab
 | Avalanche | 43114 | AVAX |
 | BNB Chain | 56 | BNB |
 | Gnosis | 100 | xDAI |
-| Blast | 81457 | ETH |
 | Arbitrum Nova | 42170 | ETH |
 | Ape Chain | 33139 | APE |
 | B3 | 8333 | ETH |
 | Soneium | 1868 | ETH |
-| Xai | 660279 | XAI |
 | Katana | 747474 | ETH |
 | Etherlink | 42793 | XTZ |
 | Berachain | 80094 | BERA |
 | Sonic | 146 | S |
 | Monad | 143 | MON |
 | Somnia | 5031 | SOMI |
+| HyperEVM | 999 | HYPE |
 
 <Note>
 Berachain, Sonic, Monad, and Somnia are newly integrated chains shipping with v1.5. Route coverage and supported token pairs will expand over time.

sdk/composable-actions/supported-chains.mdx

@@ -10,9 +10,9 @@ Chain identifiers are either **names** or **chain IDs**. The following names are
 
 ```
 apechain, arbitrum, arbitrum-nova, avalanche, avalanche-c, b3,
-base, binance, bsc, bnb, etherlink, gnosis, hyperevm, katana,
-mainnet, ethereum, monad, optimism, polygon, soneium, somnia,
-sonic, xai
+base, berachain, binance, bsc, bnb, etherlink, gnosis, hyperevm,
+katana, mainnet, ethereum, monad, optimism, polygon, soneium,
+somnia, sonic
 ```
 
 Chain IDs (e.g. `8453` for Base, `42161` for Arbitrum) work interchangeably.

sdk/configuration.mdx

@@ -38,12 +38,14 @@ appMetadata={{
 |------|------|-------------|
 | `walletConnectProjectId` | `string` | WalletConnect project ID |
 | `walletOptions` | `string[]` | Wallet connector IDs to show (e.g. `["metamask", "walletconnect"]`) |
-| `wagmiConnectors` | `Connector[]` | Custom wagmi connectors |
-| `decoupleWagmi` | `boolean` | Decouple from external wagmi provider |
-| `hideDisconnect` | `boolean` | Hide the disconnect button |
+| `adapters` | `TrailsAdapterEntry[]` | Explicit wallet runtime adapters. Use `wagmiAdapter` from [`@0xtrails/adapter-wagmi`](/sdk/hooks#apps-with-wagmi) to share an existing wagmi session, or build your own with `evmAdapter`. |
 | `hideAddWallet` | `boolean` | Hide "Add wallet" option |
 | `isSmartWallet` | `boolean` | Signal that the connected wallet is a smart wallet |
 
+<Note>
+The `wagmiConnectors` and `decoupleWagmi` props were removed in [`0xtrails@0.16.0`](/sdk/changelog/0xtrails-0.16.0). Wagmi is no longer required by default — pass adapters via the `adapters` prop instead.
+</Note>
+
 #### Route options
 
 | Prop | Type | Description |