feat: InterwovenKit API docs

docs.json

@@ -414,10 +414,55 @@
             ]
           },
           {
-            "group": "References",
+            "group": "API Reference",
             "pages": [
-              "interwovenkit/references/interwovenkit-provider",
-              "interwovenkit/references/useinterwovenkit"
+              "interwovenkit/references/index",
+              {
+                "group": "Setup",
+                "pages": ["interwovenkit/references/setup/providers"]
+              },
+              {
+                "group": "Components",
+                "pages": [
+                  "interwovenkit/references/components/interwovenkit-provider"
+                ]
+              },
+              {
+                "group": "Hooks",
+                "pages": [
+                  "interwovenkit/references/hooks/use-interwovenkit",
+                  "interwovenkit/references/hooks/use-address",
+                  "interwovenkit/references/hooks/use-initia-address",
+                  "interwovenkit/references/hooks/use-hex-address",
+                  "interwovenkit/references/hooks/use-portfolio",
+                  "interwovenkit/references/hooks/use-username-query"
+                ]
+              },
+              {
+                "group": "Utilities",
+                "pages": ["interwovenkit/references/utilities/inject-styles"]
+              },
+              {
+                "group": "Errors",
+                "pages": ["interwovenkit/references/errors/move-error"]
+              },
+              {
+                "group": "Constants",
+                "pages": [
+                  "interwovenkit/references/constants/mainnet",
+                  "interwovenkit/references/constants/testnet",
+                  "interwovenkit/references/constants/default-gas-adjustment",
+                  "interwovenkit/references/constants/default-gas-price-multiplier",
+                  "interwovenkit/references/constants/privy-app-id"
+                ]
+              },
+              {
+                "group": "Social Login",
+                "pages": [
+                  "interwovenkit/references/social-login/initia-privy-wallet",
+                  "interwovenkit/references/social-login/initia-privy-wallet-connector"
+                ]
+              }
             ]
           }
         ]

interwovenkit/integrations/evm.mdx

@@ -41,7 +41,7 @@ import {
   InterwovenKitProvider,
   TESTNET,
 } from '@initia/interwovenkit-react'
-import InterwovenKitStyles from '@initia/interwovenkit-react/styles.js'
+import interwovenKitStyles from '@initia/interwovenkit-react/styles.js'
 
 const minievm = {
   id: 4303131403034904,
@@ -63,7 +63,7 @@ const queryClient = new QueryClient()
 export default function Providers({ children }: PropsWithChildren) {
   useEffect(() => {
     // Inject styles into the shadow DOM used by Initia Wallet
-    injectStyles(InterwovenKitStyles)
+    injectStyles(interwovenKitStyles)
   }, [])
 
   return (
@@ -96,7 +96,8 @@ export default function Providers({ children }: PropsWithChildren) {
   blockchain for Initia Wallet operations. For EVM rollups, use your rollup's
   chain ID (like `"minievm-2"`), not the EVM chain ID. This ensures proper
   balance display and bridging functionality. See [InterwovenKitProvider
-  reference](/interwovenkit/references/interwovenkit-provider) for more details.
+  reference](/interwovenkit/references/components/interwovenkit-provider) for
+  more details.
 </Info>
 
 </Step>

interwovenkit/integrations/native.mdx

@@ -68,7 +68,7 @@ import {
   injectStyles,
   InterwovenKitProvider,
 } from '@initia/interwovenkit-react'
-import InterwovenKitStyles from '@initia/interwovenkit-react/styles.js'
+import interwovenKitStyles from '@initia/interwovenkit-react/styles.js'
 
 const wagmiConfig = createConfig({
   connectors: [initiaPrivyWalletConnector],
@@ -80,7 +80,7 @@ const queryClient = new QueryClient()
 export default function Providers({ children }: PropsWithChildren) {
   useEffect(() => {
     // Inject styles into the shadow DOM used by Initia Wallet
-    injectStyles(InterwovenKitStyles)
+    injectStyles(interwovenKitStyles)
   }, [])
 
   return (
@@ -102,7 +102,8 @@ export default function Providers({ children }: PropsWithChildren) {
   [initia-registry](https://registry.initia.xyz) This sets the primary network
   for transactions, balance queries, and serves as the default for all
   operations. See the [InterwovenKitProvider
-  reference](/interwovenkit/references/interwovenkit-provider) for details.
+  reference](/interwovenkit/references/components/interwovenkit-provider) for
+  details.
 </Info>
 
  </Step>

interwovenkit/integrations/rainbowkit.mdx

@@ -66,7 +66,7 @@ RainbowKit integration with InterwovenKit provides:
     import { connectorsForWallets, RainbowKitProvider } from "@rainbow-me/rainbowkit"
     import "@rainbow-me/rainbowkit/styles.css"
     import { initiaPrivyWallet, injectStyles, InterwovenKitProvider } from "@initia/interwovenkit-react"
-    import InterwovenKitStyles from "@initia/interwovenkit-react/styles.js"
+    import interwovenKitStyles from "@initia/interwovenkit-react/styles.js"
 
     const connectors = connectorsForWallets(
       [
@@ -92,7 +92,7 @@ RainbowKit integration with InterwovenKit provides:
     export default function Providers({ children }: PropsWithChildren) {
       useEffect(() => {
         // Inject styles into the shadow DOM used by Initia Wallet
-        injectStyles(InterwovenKitStyles)
+        injectStyles(interwovenKitStyles)
       }, [])
 
       return (
@@ -117,7 +117,7 @@ RainbowKit integration with InterwovenKit provides:
         - Or any valid chain ID from the [initia-registry](https://registry.initia.xyz)
       - Update `appName` and `projectId` to match your application details
 
-      The `defaultChainId` sets the primary network for all Initia Wallet operations. See [InterwovenKitProvider reference](/interwovenkit/references/interwovenkit-provider) for details.
+      The `defaultChainId` sets the primary network for all Initia Wallet operations. See [InterwovenKitProvider reference](/interwovenkit/references/components/interwovenkit-provider) for details.
     </Info>
 
   </Step>

interwovenkit/migration.mdx

@@ -131,7 +131,7 @@ improved TypeScript support, and a more intuitive API.
       injectStyles,
       InterwovenKitProvider
     } from "@initia/interwovenkit-react"
-    import InterwovenKitStyles from "@initia/interwovenkit-react/styles.js"
+    import interwovenKitStyles from "@initia/interwovenkit-react/styles.js"
 
     // Configure Wagmi for wallet connections
     const wagmiConfig = createConfig({
@@ -145,7 +145,7 @@ improved TypeScript support, and a more intuitive API.
     export default function Providers({ children }: PropsWithChildren) {
       useEffect(() => {
         // Inject styles into the shadow DOM used by Initia Wallet
-        injectStyles(InterwovenKitStyles)
+        injectStyles(interwovenKitStyles)
       }, [])
 
       return (
@@ -345,7 +345,8 @@ export default function TransactionComponent() {
   For more granular control over transaction states, use `requestTxSync()` to
   get the transaction hash immediately, then `waitForTxConfirmation()` to wait
   for blockchain confirmation. See the [useInterwovenKit
-  reference](./references/useinterwovenkit#transactions) for details.
+  reference](./references/hooks/use-interwovenkit#transaction-methods) for
+  details.
 </Tip>
 
 ## Advanced Integration
@@ -436,5 +437,5 @@ export default function SendTransaction() {
 <Note>
   Need help with migration? Check out the [Getting Started
   guide](./getting-started) for complete implementation examples, or refer to
-  the [API Reference](./references) for detailed method documentation.
+  the [API Reference](./references/index) for detailed method documentation.
 </Note>

interwovenkit/references/components/interwovenkit-provider.mdx

@@ -0,0 +1,180 @@
+---
+title: InterwovenKitProvider
+---
+
+## Overview
+
+- React provider that configures and renders the InterwovenKit widget shell
+  (drawer, routes, and supporting providers).
+- Mount once near the top of your app, wrapping your root component.
+- Privy and AutoSign are optional. Configure `privyContext` and `enableAutoSign`
+  only if needed. AutoSign requires Privy (`PrivyProvider` and `privyContext`).
+
+## Prerequisites
+
+- Must be used within a React Query `QueryClientProvider`.
+- Must be used within a wagmi `WagmiProvider` if using wallet-related APIs.
+- Client-only (no SSR): Put this in a `use client` provider tree, or use a
+  dynamic import in Next.js.
+
+## Styles
+
+- CSS styles must be injected manually using
+  [`injectStyles`](../utilities/inject-styles) once at app startup. Otherwise
+  the UI will be unstyled.
+
+## Quickstart
+
+```tsx
+'use client'
+
+import { useEffect } from 'react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { createConfig, http, WagmiProvider } from 'wagmi'
+import { mainnet } from 'wagmi/chains'
+import {
+  initiaPrivyWalletConnector,
+  injectStyles,
+  InterwovenKitProvider,
+  MAINNET,
+} from '@initia/interwovenkit-react'
+import interwovenKitStyles from '@initia/interwovenkit-react/styles.js'
+
+const queryClient = new QueryClient()
+const wagmiConfig = createConfig({
+  connectors: [initiaPrivyWalletConnector],
+  chains: [mainnet],
+  transports: { [mainnet.id]: http() },
+})
+
+export function AppProviders({ children }: { children: React.ReactNode }) {
+  useEffect(() => {
+    injectStyles(interwovenKitStyles)
+  }, [])
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <WagmiProvider config={wagmiConfig}>
+        <InterwovenKitProvider {...MAINNET}>{children}</InterwovenKitProvider>
+      </WagmiProvider>
+    </QueryClientProvider>
+  )
+}
+```
+
+<Note>
+  This example shows the provider structure. For complete setup configurations,
+  see [Provider Setup](../setup/providers).
+</Note>
+
+## Props
+
+| Prop                     | Type                                  | Default                             | Description                                                                                                                                                                                                                                                                                                                   |
+| ------------------------ | ------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `defaultChainId`         | `string`                              | From preset                         | Initia or rollup chain ID that InterwovenKit should treat as the "home" chain                                                                                                                                                                                                                                                 |
+| `registryUrl`            | `string`                              | From preset                         | Base URL for the Initia registry API used to resolve chains and assets                                                                                                                                                                                                                                                        |
+| `routerApiUrl`           | `string`                              | From preset                         | Base URL for the router API used by the bridge and swap flows                                                                                                                                                                                                                                                                 |
+| `glyphUrl`               | `string`                              | From preset                         | Base URL for Glyph profile data (user avatars and related metadata)                                                                                                                                                                                                                                                           |
+| `usernamesModuleAddress` | `string`                              | From preset                         | On‑chain module address of the Initia (`.init`) username contract                                                                                                                                                                                                                                                             |
+| `theme`                  | `"light" \| "dark"`                   | From preset (typically dark)        | Visual theme for the widget                                                                                                                                                                                                                                                                                                   |
+| `customChain`            | `Chain`                               | `undefined`                         | Adds or overrides a chain definition in the Initia registry. Use when you run a private rollup or need to inject a chain that is not yet in the public registry                                                                                                                                                               |
+| `protoTypes`             | `Iterable<[string, GeneratedType]>`   | `undefined`                         | Additional protobuf type mappings used when encoding Cosmos transactions. Only needed if you use custom message types                                                                                                                                                                                                         |
+| `aminoConverters`        | `AminoConverters`                     | `undefined`                         | Custom Amino converters for legacy signing. Only needed for advanced integrations                                                                                                                                                                                                                                             |
+| `container`              | `HTMLElement`                         | `undefined`                         | Optional element the widget should render into instead of the default Shadow DOM host                                                                                                                                                                                                                                         |
+| `disableAnalytics`       | `boolean`                             | `false` (mainnet), `true` (testnet) | When `true`, disables InterwovenKit's built‑in analytics events                                                                                                                                                                                                                                                               |
+| `enableAutoSign`         | `boolean \| Record<string, string[]>` | `undefined`                         | Enables AutoSign and optionally whitelists chains and message types. `true` enables for supported chains and messages. `Record<string, string[]>` is a per-chain allowlist of message type URLs. **Requires Privy** (`PrivyProvider` and `privyContext`). Required at runtime only if you want AutoSign flows to be available |
+| `privyContext`           | `PrivyContext`                        | `undefined`                         | Passes Privy authentication and wallet helpers into InterwovenKit. **Required for AutoSign and embedded wallet features**, otherwise optional                                                                                                                                                                                 |
+
+## Return value
+
+Renders `children` and mounts the InterwovenKit UI shell.
+
+## Examples
+
+### Custom chain configuration
+
+```tsx
+import type { Chain } from '@initia/initia-registry-types'
+import { InterwovenKitProvider, MAINNET } from '@initia/interwovenkit-react'
+
+const MY_ROLLUP: Chain = {
+  chain_id: 'my-rollup-1',
+  chain_name: 'my-rollup',
+  pretty_name: 'My Rollup',
+  network_type: 'mainnet',
+  bech32_prefix: 'init',
+  fees: {
+    fee_tokens: [
+      {
+        denom: 'uinit',
+        fixed_min_gas_price: 0.1,
+      },
+    ],
+  },
+  apis: {
+    rpc: [{ address: 'https://rpc.my-rollup.com' }],
+    rest: [{ address: 'https://api.my-rollup.com' }],
+    indexer: [{ address: 'https://indexer.my-rollup.com' }],
+  },
+} as Chain
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <InterwovenKitProvider
+      {...MAINNET}
+      defaultChainId={MY_ROLLUP.chain_id}
+      customChain={MY_ROLLUP}
+    >
+      {children}
+    </InterwovenKitProvider>
+  )
+}
+```
+
+<Note>
+  This example shows only the `InterwovenKitProvider` configuration. For
+  complete provider setup including `QueryClientProvider`, `WagmiProvider`, and
+  `injectStyles`, see [Provider Setup](../setup/providers).
+</Note>
+
+## Notes
+
+- For AutoSign and Privy integration setup, see
+  [Provider Setup](../setup/providers).
+
+## Type reference (advanced)
+
+```ts
+type InterwovenKitProviderProps = React.PropsWithChildren<Partial<Config>>
+
+type Config = {
+  defaultChainId: string
+  customChain?: Chain
+  protoTypes?: Iterable<[string, GeneratedType]>
+  aminoConverters?: AminoConverters
+  registryUrl: string
+  routerApiUrl: string
+  glyphUrl: string
+  usernamesModuleAddress: string
+  theme: 'light' | 'dark'
+  container?: HTMLElement
+  disableAnalytics?: boolean
+  enableAutoSign?: boolean | Record<string, string[]>
+  privyContext?: PrivyContext
+}
+
+type PrivyContext = {
+  privy: ReturnType<typeof usePrivy>
+  createWallet: ReturnType<typeof useCreateWallet>['createWallet']
+  wallets: ReturnType<typeof useWallets>['wallets']
+  siwe: ReturnType<typeof useLoginWithSiwe>
+}
+```
+
+Types `Chain`, `GeneratedType`, and `AminoConverters` are from external
+packages. See `@initia/initia-registry-types`, `@cosmjs/proto-signing`, and
+`@cosmjs/stargate` for details.
+
+`PrivyContext` members are derived from Privy hooks: `usePrivy`,
+`useCreateWallet`, `useWallets`, and `useLoginWithSiwe` from
+`@privy-io/react-auth`.

interwovenkit/references/constants/default-gas-adjustment.mdx

@@ -0,0 +1,33 @@
+---
+title: DEFAULT_GAS_ADJUSTMENT
+---
+
+## Overview
+
+- Default gas adjustment multiplier used when `gasAdjustment` is not provided in
+  transaction requests.
+- Reference only if you need to match InterwovenKit's default in custom logic.
+
+## Quickstart
+
+```ts
+import { DEFAULT_GAS_ADJUSTMENT } from "@initia/interwovenkit-react"
+
+// Pass explicit gasAdjustment to match InterwovenKit's default
+const { requestTxBlock } = useInterwovenKit()
+await requestTxBlock({
+  messages: [...],
+  gasAdjustment: DEFAULT_GAS_ADJUSTMENT, // Optional: defaults to this value if omitted
+})
+```
+
+## Value
+
+```ts
+const DEFAULT_GAS_ADJUSTMENT: number // 1.4
+```
+
+## Notes
+
+- InterwovenKit uses this automatically when `gasAdjustment` is omitted.
+- Reference only if you need to match the default in custom logic.