# Ivem Kit

> IOST toolkit with a shared core package, React hooks, Vue composables, and an iWallet connector.

## Vue Composables

### Usage

```ts
import { useAccount, useConnect } from '@ivem/kit-vue'
```

### Parameters

Composables read config from `IvemPlugin` context.
Mutation/composable state is managed by TanStack Query.

### Return Type

State values are exposed as Vue `Ref` wrappers when applicable.

### Examples

* [useIvemConfig](/vue/composables/useIvemConfig)
* [useAccount](/vue/composables/useAccount)
* [useConnect](/vue/composables/useConnect)
* [useReconnect](/vue/composables/useReconnect)
* [useDisconnect](/vue/composables/useDisconnect)
* [useChainId](/vue/composables/useChainId)
* [useSignMessage](/vue/composables/useSignMessage)
* [useSendTransaction](/vue/composables/useSendTransaction)
* [useWriteContract](/vue/composables/useWriteContract)
* [useWaitForTransactionReceipt](/vue/composables/useWaitForTransactionReceipt)
* [useCallContract](/vue/composables/useCallContract)

### Related

* [React Hooks](/react/hooks)
* [Core Actions](/core/actions)


## Getting Started

Create a shared config, then install `IvemPlugin` when bootstrapping the app.

### Create Config

```ts
import { createConfig, iwallet, mainnet } from '@ivem/kit-vue'

export const config = createConfig({
  chains: [mainnet],
  connector: iwallet(),
})
```

Use `ssr: true` in Nuxt or other SSR setups to avoid persisted-state hydration during the first render.

### Install the Plugin

```ts
import { createApp } from 'vue'
import { QueryClient } from '@tanstack/vue-query'
import { IvemPlugin } from '@ivem/kit-vue'
import { config } from './config'
import App from './App.vue'

const queryClient = new QueryClient()

createApp(App)
  .use(IvemPlugin({ config, queryClient }))
  .mount('#app')
```


## Installation

Install the Vue bindings together with the shared core client and TanStack Query.

:::code-group
```bash [pnpm]
pnpm add @ivem/core @ivem/kit-vue @tanstack/vue-query
```

```bash [npm]
npm i @ivem/core @ivem/kit-vue @tanstack/vue-query
```

```bash [yarn]
yarn add @ivem/core @ivem/kit-vue @tanstack/vue-query
```
:::

### Packages

* `@ivem/core` provides the low-level IOST client types and transports.
* `@ivem/kit-vue` provides `IvemPlugin` and Vue composables.
* `@tanstack/vue-query` powers async composable state.


## Vue

`@ivem/kit-vue` provides a plugin and composables:

* `IvemPlugin`
* `useAccount`
* `useConnect`
* `useReconnect`
* `useDisconnect`
* `useChainId`
* `useSignMessage`
* `useSendTransaction`
* `useWriteContract`
* `useWaitForTransactionReceipt`
* `useCallContract`

Async composables are powered by TanStack Query (`@tanstack/vue-query`) via `IvemPlugin`.

```ts
import { createApp } from 'vue'
import { QueryClient } from '@tanstack/vue-query'
import { createConfig, iwallet, mainnet, IvemPlugin } from '@ivem/kit-vue'

const config = createConfig({
  chains: [mainnet],
  connector: iwallet(),
})

const queryClient = new QueryClient()

createApp(App).use(IvemPlugin({ config, queryClient })).mount('#app')
```


## Why Ivem Kit for Vue

`@ivem/kit-vue` is built for apps that want a small IOST-specific surface area with a plugin-and-composables workflow.

### Why use it

* **Shared config model** Use the same `createConfig` and connector setup across Vue, React, and headless usage.
* **Composable-first API** Reach account state, connection flows, signing, transfers, and contract calls through focused composables.
* **Query-powered async state** TanStack Query handles mutation state and async caching without extra glue code.
* **Easy escape hatches** Drop down to `@ivem/kit` whenever you need direct action calls or tighter control.


## useAccount

### Usage

```ts
import { useAccount } from '@ivem/kit-vue'

const account = useAccount()
```

### Parameters

* None

### Return Type

* `Ref<GetAccountReturnType>`

### Examples

```ts
if (account.value.isConnected) {
  console.log(account.value.address)
}
```

### Related

* [getAccount (Core)](/core/actions/getAccount)
* [useAccount (React)](/react/hooks/useAccount)


## useCallContract

> Compatibility alias. Prefer `useWriteContract`.

### Usage

```ts
import { useCallContract } from '@ivem/kit-vue'

const callContract = useCallContract()
await callContract.mutateAsync({
  contract: 'token.iost',
  action: 'transfer',
  args: ['iost', 'alice', 'bob', '1.00000000', 'memo'],
})
```

### Parameters

Call params:

* `contract: string`
* `action: string`
* `args: any[]`
* `account?: string`
* `gasRatio?: number`
* `gasLimit?: number`

### Return Type

* `mutate(params, options?) => void`
* `mutateAsync(params) => Promise<{ hash: string }>`
* `isPending: Ref<boolean>`
* `error: Ref<Error | null>`
* `data: Ref<{ hash: string } | null>`

### Examples

```ts
const tx = await callContract.mutateAsync({
  contract: 'token.iost',
  action: 'transfer',
  args: ['iost', 'alice', 'bob', '1.00000000', 'memo'],
  gasRatio: 1,
  gasLimit: 2000000,
})
```

### Related

* [useWriteContract (Vue)](/vue/composables/useWriteContract)
* [writeContract (Core)](/core/actions/writeContract)


## useChainId

### Usage

```ts
import { useChainId } from '@ivem/kit-vue'

const chainId = useChainId()
```

### Parameters

* None

### Return Type

* `Ref<string>`

### Examples

```ts
console.log(chainId.value)
```

### Related

* [getChainId (Core)](/core/actions/getChainId)
* [useChainId (React)](/react/hooks/useChainId)


## useConnect

### Usage

```ts
import { useConnect } from '@ivem/kit-vue'

const connect = useConnect()
await connect.mutateAsync()
```

### Parameters

* `parameters.config?: Config`
* `parameters.mutation?: Omit<UseMutationOptions<...>, "mutationFn">`

### Return Type

* `mutate(params?, options?) => void`
* `mutateAsync(params?) => Promise<{ accounts: readonly string[]; chainId: string }>`
* `isPending: Ref<boolean>`
* `error: Ref<Error | null>`

### Examples

```ts
await connect.mutateAsync()
```

### Related

* [connect (Core)](/core/actions/connect)
* [useConnect (React)](/react/hooks/useConnect)


## useDisconnect

### Usage

```ts
import { useDisconnect } from '@ivem/kit-vue'

const disconnect = useDisconnect()
await disconnect.mutateAsync()
```

### Parameters

* None

### Return Type

* `mutate() => void`
* `mutateAsync() => Promise<void>`
* `isPending: Ref<boolean>`
* `error: Ref<Error | null>`

### Examples

```ts
await disconnect.mutateAsync()
```

### Related

* [disconnect (Core)](/core/actions/disconnect)
* [useDisconnect (React)](/react/hooks/useDisconnect)


## useIvemConfig

### Usage

```ts
import { useIvemConfig } from '@ivem/kit-vue'

const config = useIvemConfig()
```

### Parameters

* None

### Return Type

* `Config`

### Examples

```ts
const config = useIvemConfig()
console.log(config.state)
```

### Related

* [useConfig (React)](/react/hooks/useConfig)
* [createConfig (Core)](/core/create-config)


## useReconnect

### Usage

```ts
import { useReconnect } from '@ivem/kit-vue'

const reconnect = useReconnect()
await reconnect.mutateAsync()
```

### Parameters

* None

### Return Type

* `mutate() => void`
* `mutateAsync() => Promise<{ accounts: readonly string[]; chainId: string } | null>`
* `isPending: Ref<boolean>`
* `error: Ref<Error | null>`

### Examples

```ts
onMounted(() => reconnect.mutate())
```

### Related

* [reconnect (Core)](/core/actions/reconnect)
* [useReconnect (React)](/react/hooks/useReconnect)


## useSendTransaction

### Usage

```ts
import { useSendTransaction } from '@ivem/kit-vue'

const sendTransaction = useSendTransaction()
await sendTransaction.mutateAsync({ to: 'receiver_account', amount: '1.00000000', memo: 'from Ivem Kit' })
```

### Parameters

Call params:

* `to: string`
* `amount: string`
* `memo?: string`
* `from?: string`

### Return Type

* `mutate(params, options?) => void`
* `mutateAsync(params) => Promise<{ hash: string }>`
* `isPending: Ref<boolean>`
* `error: Ref<Error | null>`
* `data: Ref<{ hash: string } | null>`

### Examples

```ts
const tx = await sendTransaction.mutateAsync({ to: 'receiver', amount: '1.00000000' })
console.log(tx.hash)
```

### Related

* [sendTransaction (Core)](/core/actions/sendTransaction)
* [useSendTransaction (React)](/react/hooks/useSendTransaction)


## useSignMessage

### Usage

```ts
import { useSignMessage } from '@ivem/kit-vue'

const signMessage = useSignMessage()
await signMessage.mutateAsync({ message: 'hello iost' })
```

### Parameters

* `parameters.config?: Config`
* `parameters.mutation?: Omit<UseMutationOptions<...>, "mutationFn">`

Call params:

* `message: string | object`
* `account?: string`

### Return Type

* `mutate(params, options?) => void`
* `mutateAsync(params) => Promise<unknown>`
* `isPending: Ref<boolean>`
* `error: Ref<Error | null>`
* `data: Ref<unknown | null>`

### Examples

```ts
await signMessage.mutateAsync({ message: { type: 'login', nonce: '123' } })
```

### Related

* [signMessage (Core)](/core/actions/signMessage)
* [useSignMessage (React)](/react/hooks/useSignMessage)


## useWaitForTransactionReceipt

### Usage

```ts
import { computed } from 'vue'
import { useSendTransaction, useWaitForTransactionReceipt } from '@ivem/kit-vue'

const sendTransaction = useSendTransaction()
const { data: receipt, isLoading } = useWaitForTransactionReceipt({
  hash: computed(() => sendTransaction.data.value?.hash),
})

await sendTransaction.mutateAsync({ to: 'receiver_account', amount: '1.00000000' })
```

### Parameters

* `hash?: MaybeRef<string | undefined>`
* `retryCount?: MaybeRef<number | undefined>`
* `retryDelay?: MaybeRef<number | undefined>`
* `timeout?: MaybeRef<number | undefined>`
* `enabled?: MaybeRef<boolean | undefined>`

### Return Type

* `data: Ref<TxReceipt | undefined>`
* `error: Ref<Error | null>`
* `isLoading: Ref<boolean>`
* `isSuccess: Ref<boolean>`
* `isError: Ref<boolean>`
* `refetch: () => Promise<unknown>`

### Examples

```ts
const { data: receipt } = useWaitForTransactionReceipt({
  hash: computed(() => sendTransaction.data.value?.hash),
  enabled: computed(() => Boolean(sendTransaction.data.value?.hash)),
})

console.log(receipt.value?.status_code)
```

### Related

* [waitForTransactionReceipt (Core)](/core/actions/waitForTransactionReceipt)
* [useWaitForTransactionReceipt (React)](/react/hooks/useWaitForTransactionReceipt)


## useWriteContract

### Usage

```ts
import { useWriteContract } from '@ivem/kit-vue'

const writeContract = useWriteContract()
await writeContract.mutateAsync({
  contract: 'token.iost',
  action: 'transfer',
  args: ['iost', 'alice', 'bob', '1.00000000', 'memo'],
})
```

### Parameters

Write params:

* `contract: string`
* `action: string`
* `args: any[]`
* `gasRatio?: number`
* `gasLimit?: number`
* `approves?: Array<{ token: string; amount: string }>`

### Return Type

* `mutate(params, options?) => void`
* `mutateAsync(params) => Promise<{ hash: string }>`
* `isPending: Ref<boolean>`
* `error: Ref<Error | null>`
* `data: Ref<{ hash: string } | null>`

### Examples

```ts
const tx = await writeContract.mutateAsync({
  contract: 'token.iost',
  action: 'transfer',
  args: ['iost', 'alice', 'bob', '1.00000000', 'memo'],
  gasRatio: 1,
  gasLimit: 2000000,
})
```

### Related

* [writeContract (Core)](/core/actions/writeContract)
* [useWriteContract (React)](/react/hooks/useWriteContract)


## Getting Started

Start by creating a shared config, then mount `IvemProvider` at the app root.

### Create Config

```ts
import { createConfig, iwallet, mainnet } from '@ivem/kit-react'

export const config = createConfig({
  chains: [mainnet],
  connector: iwallet(),
})
```

Use `ssr: true` in Next.js or other SSR setups to skip persisted-state hydration during the first render.

`testnet` is still exported for compatibility, but as of 2026-03-11 the public IOST testnet is unavailable and should not be used in new setups.

### Mount the Provider

```tsx
import { QueryClient } from '@tanstack/react-query'
import { IvemProvider, useAccount, useConnect, useDisconnect } from '@ivem/kit-react'
import { config } from './config'

const queryClient = new QueryClient()

function App() {
  return (
    <IvemProvider config={config} queryClient={queryClient}>
      <Page />
    </IvemProvider>
  )
}

function Page() {
  const account = useAccount()
  const connect = useConnect()
  const disconnect = useDisconnect()

  if (!account.isConnected) {
    return <button onClick={() => connect.mutate()}>Connect</button>
  }

  return (
    <div>
      <p>{account.address}</p>
      <button onClick={() => disconnect.mutate()}>Disconnect</button>
    </div>
  )
}
```


## React Hooks

The React package exposes hooks for wallet connection, chain state, signing, transactions, and contract calls.

### Prerequisite

```tsx
import { QueryClient } from '@tanstack/react-query'
import { createConfig, iwallet, mainnet, IvemProvider } from '@ivem/kit-react'

const config = createConfig({
  chains: [mainnet],
  connector: iwallet(),
})

const queryClient = new QueryClient()

export function App() {
  return (
    <IvemProvider config={config} queryClient={queryClient}>
      {/* your app */}
    </IvemProvider>
  )
}
```

### Hook List

* [useConfig](/react/hooks/useConfig)
* [useAccount](/react/hooks/useAccount)
* [useConnect](/react/hooks/useConnect)
* [useReconnect](/react/hooks/useReconnect)
* [useDisconnect](/react/hooks/useDisconnect)
* [useChainId](/react/hooks/useChainId)
* [useSignMessage](/react/hooks/useSignMessage)
* [useSendTransaction](/react/hooks/useSendTransaction)
* [useWriteContract](/react/hooks/useWriteContract)
* [useWaitForTransactionReceipt](/react/hooks/useWaitForTransactionReceipt)
* [useCallContract](/react/hooks/useCallContract)


## Installation

Install the React bindings together with the shared core client and TanStack Query.

:::code-group
```bash [pnpm]
pnpm add @ivem/core @ivem/kit-react @tanstack/react-query
```

```bash [npm]
npm i @ivem/core @ivem/kit-react @tanstack/react-query
```

```bash [yarn]
yarn add @ivem/core @ivem/kit-react @tanstack/react-query
```
:::

### Packages

* `@ivem/core` provides the low-level IOST client types and transports.
* `@ivem/kit-react` provides `IvemProvider` and React hooks.
* `@tanstack/react-query` powers async hook state.


## React

`@ivem/kit-react` provides React hooks for connection state, signing, transfers, contract calls, and receipt polling. The recommended app structure is `IvemProvider + hooks`.

Async hooks are powered by TanStack Query (`@tanstack/react-query`) via `IvemProvider`.

* `useAccount`
* `useConnect`
* `useReconnect`
* `useDisconnect`
* `useChainId`
* `useSignMessage`
* `useSendTransaction`
* `useWriteContract`
* `useWaitForTransactionReceipt`
* `useCallContract`

Detailed API docs:

* [Hooks Overview](/react/hooks)
* [useConfig](/react/hooks/useConfig)
* [useAccount](/react/hooks/useAccount)
* [useConnect](/react/hooks/useConnect)
* [useReconnect](/react/hooks/useReconnect)
* [useDisconnect](/react/hooks/useDisconnect)
* [useChainId](/react/hooks/useChainId)
* [useSignMessage](/react/hooks/useSignMessage)
* [useSendTransaction](/react/hooks/useSendTransaction)
* [useWriteContract](/react/hooks/useWriteContract)
* [useWaitForTransactionReceipt](/react/hooks/useWaitForTransactionReceipt)
* [useCallContract](/react/hooks/useCallContract)

```tsx
import { useAccount, useConnect, useReconnect } from '@ivem/kit-react'

function Header() {
  const account = useAccount()
  const connect = useConnect()
  const reconnect = useReconnect()

  return (
    <div>
      <button onClick={() => reconnect.mutate()}>Reconnect</button>
      {!account.isConnected && <button onClick={() => connect.mutate()}>Connect</button>}
    </div>
  )
}
```


## Why Ivem Kit for React

`@ivem/kit-react` is built for apps that want a small IOST-specific surface area with a familiar provider-and-hooks workflow.

### Why use it

* **Shared config model** Use the same `createConfig` and connector setup across React, Vue, and headless usage.
* **Hook-first app structure** Reach account state, connection flows, signing, transfers, and contract calls through focused hooks.
* **Query-powered async state** TanStack Query handles mutation state and async caching without extra glue code.
* **Easy escape hatches** Drop down to `@ivem/kit` whenever you need direct action calls or tighter control.


## useAccount

### Usage

```tsx
import { useAccount } from '@ivem/kit-react'

const account = useAccount()
```

### Parameters

* None

### Return Type

* `address?: string`
* `addresses: readonly string[]`
* `chainId: string`
* `status: 'connected' | 'connecting' | 'disconnected' | 'reconnecting'`
* `isConnected: boolean`
* `isConnecting: boolean`
* `isDisconnected: boolean`
* `isReconnecting: boolean`

### Examples

```tsx
function AccountStatus() {
  const account = useAccount()
  if (!account.isConnected) return <p>Disconnected</p>
  return <p>{account.address}</p>
}
```

### Related

* [getAccount (Core)](/core/actions/getAccount)
* [useAccount (Vue)](/vue/composables/useAccount)


## useCallContract

> Compatibility alias. Prefer `useWriteContract`.

### Usage

```tsx
import { useCallContract } from '@ivem/kit-react'

const callContract = useCallContract()
await callContract.mutateAsync({
  contract: 'token.iost',
  action: 'transfer',
  args: ['iost', 'alice', 'bob', '1.00000000', 'memo'],
})
```

### Parameters

Call params:

* `contract: string`
* `action: string`
* `args: any[]`
* `account?: string`
* `gasRatio?: number`
* `gasLimit?: number`

### Return Type

* `mutate(params, options?) => void`
* `mutateAsync(params) => Promise<{ hash: string }>`
* `isPending: boolean`
* `error: Error | null`
* `data: { hash: string } | null`

### Examples

```tsx
const tx = await callContract.mutateAsync({
  contract: 'token.iost',
  action: 'transfer',
  args: ['iost', 'alice', 'bob', '1.00000000', 'memo'],
  gasRatio: 1,
  gasLimit: 2000000,
})
```

### Related

* [useWriteContract (React)](/react/hooks/useWriteContract)
* [writeContract (Core)](/core/actions/writeContract)


## useChainId

### Usage

```tsx
import { useChainId } from '@ivem/kit-react'

const chainId = useChainId()
```

### Parameters

* None

### Return Type

* `string`

### Examples

```tsx
function CurrentChain() {
  const chainId = useChainId()
  return <span>{chainId}</span>
}
```

### Related

* [getChainId (Core)](/core/actions/getChainId)
* [useChainId (Vue)](/vue/composables/useChainId)


## useConfig

### Usage

```tsx
import { useConfig } from '@ivem/kit-react'

const config = useConfig()
```

### Parameters

* None

### Return Type

* `Config`

### Examples

```tsx
function DebugConfig() {
  const config = useConfig()
  return <pre>{JSON.stringify(config.state, null, 2)}</pre>
}
```

### Related

* [useIvemConfig (Vue)](/vue/composables/useIvemConfig)
* [createConfig (Core)](/core/create-config)


## useConnect

### Usage

```tsx
import { useConnect } from '@ivem/kit-react'

const connect = useConnect()
await connect.mutateAsync()
```

### Parameters

* `parameters.config?: Config`
* `parameters.mutation?: Omit<UseMutationOptions<...>, "mutationFn">`

### Return Type

* `mutate(params?, options?) => void`
* `mutateAsync(params?) => Promise<{ accounts: readonly string[]; chainId: string }>`
* `isPending: boolean`
* `error: Error | null`

### Examples

```tsx
function ConnectButton() {
  const connect = useConnect()
  return <button disabled={connect.isPending} onClick={() => connect.mutate()}>Connect</button>
}
```

### Related

* [connect (Core)](/core/actions/connect)
* [useConnect (Vue)](/vue/composables/useConnect)


## useDisconnect

### Usage

```tsx
import { useDisconnect } from '@ivem/kit-react'

const disconnect = useDisconnect()
await disconnect.mutateAsync()
```

### Parameters

* None

### Return Type

* `mutate() => void`
* `mutateAsync() => Promise<void>`
* `isPending: boolean`
* `error: Error | null`

### Examples

```tsx
<button onClick={() => disconnect.mutate()}>Disconnect</button>
```

### Related

* [disconnect (Core)](/core/actions/disconnect)
* [useDisconnect (Vue)](/vue/composables/useDisconnect)


## useReconnect

### Usage

```tsx
import { useReconnect } from '@ivem/kit-react'

const reconnect = useReconnect()
await reconnect.mutateAsync()
```

### Parameters

* None

### Return Type

* `mutate() => void`
* `mutateAsync() => Promise<{ accounts: readonly string[]; chainId: string } | null>`
* `isPending: boolean`
* `error: Error | null`

### Examples

```tsx
useEffect(() => {
  reconnect.mutate()
}, [])
```

### Related

* [reconnect (Core)](/core/actions/reconnect)
* [useReconnect (Vue)](/vue/composables/useReconnect)


## useSendTransaction

### Usage

```tsx
import { useSendTransaction } from '@ivem/kit-react'

const sendTransaction = useSendTransaction()
await sendTransaction.mutateAsync({ to: 'receiver_account', amount: '1.00000000', memo: 'from Ivem Kit' })
```

### Parameters

Call params:

* `to: string`
* `amount: string`
* `memo?: string`
* `from?: string`

### Return Type

* `mutate(params, options?) => void`
* `mutateAsync(params) => Promise<{ hash: string }>`
* `isPending: boolean`
* `error: Error | null`
* `data: { hash: string } | null`

### Examples

```tsx
const result = await sendTransaction.mutateAsync({ to: 'receiver', amount: '1.00000000' })
console.log(result.hash)
```

### Related

* [sendTransaction (Core)](/core/actions/sendTransaction)
* [useSendTransaction (Vue)](/vue/composables/useSendTransaction)


## useSignMessage

### Usage

```tsx
import { useSignMessage } from '@ivem/kit-react'

const signMessage = useSignMessage()
await signMessage.mutateAsync({ message: 'hello iost' })
```

### Parameters

* `parameters.config?: Config`
* `parameters.mutation?: Omit<UseMutationOptions<...>, "mutationFn">`

Call params:

* `message: string | object`
* `account?: string`

### Return Type

* `mutate(params, options?) => void`
* `mutateAsync(params) => Promise<unknown>`
* `isPending: boolean`
* `error: Error | null`
* `data: unknown | null`

### Examples

```tsx
await signMessage.mutateAsync({ message: { type: 'login', nonce: '123' } })
```

### Related

* [signMessage (Core)](/core/actions/signMessage)
* [useSignMessage (Vue)](/vue/composables/useSignMessage)


## useWaitForTransactionReceipt

### Usage

```tsx
import { useSendTransaction, useWaitForTransactionReceipt } from '@ivem/kit-react'

const sendTransaction = useSendTransaction()
const { data: receipt, isLoading } = useWaitForTransactionReceipt({
  hash: sendTransaction.data?.hash,
})

await sendTransaction.mutateAsync({ to: 'receiver_account', amount: '1.00000000' })
```

### Parameters

* `hash?: string`
* `retryCount?: number`
* `retryDelay?: number`
* `timeout?: number`
* `enabled?: boolean`

### Return Type

* `data: TxReceipt | undefined`
* `error: Error | null`
* `isLoading: boolean`
* `isSuccess: boolean`
* `isError: boolean`
* `refetch: () => Promise<unknown>`

### Examples

```tsx
const { data: receipt } = useWaitForTransactionReceipt({
  hash: sendTransaction.data?.hash,
  enabled: Boolean(sendTransaction.data?.hash),
})

console.log(receipt?.status_code)
```

### Related

* [waitForTransactionReceipt (Core)](/core/actions/waitForTransactionReceipt)
* [useWaitForTransactionReceipt (Vue)](/vue/composables/useWaitForTransactionReceipt)


## useWriteContract

### Usage

```tsx
import { useWriteContract } from '@ivem/kit-react'

const writeContract = useWriteContract()
await writeContract.mutateAsync({
  contract: 'token.iost',
  action: 'transfer',
  args: ['iost', 'alice', 'bob', '1.00000000', 'memo'],
})
```

### Parameters

Write params:

* `contract: string`
* `action: string`
* `args: any[]`
* `gasRatio?: number`
* `gasLimit?: number`
* `approves?: Array<{ token: string; amount: string }>`

### Return Type

* `mutate(params, options?) => void`
* `mutateAsync(params) => Promise<{ hash: string }>`
* `isPending: boolean`
* `error: Error | null`
* `data: { hash: string } | null`

### Examples

```tsx
const tx = await writeContract.mutateAsync({
  contract: 'token.iost',
  action: 'transfer',
  args: ['iost', 'alice', 'bob', '1.00000000', 'memo'],
  gasRatio: 1,
  gasLimit: 2000000,
})
```

### Related

* [writeContract (Core)](/core/actions/writeContract)
* [useWriteContract (Vue)](/vue/composables/useWriteContract)


## Actions Overview

Core actions are framework-agnostic APIs from `@ivem/kit`.

### Usage

```ts
import { connect, sendTransaction } from '@ivem/kit'

await connect(config)
await sendTransaction(config, {
  to: 'receiver',
  amount: '1.00000000',
  memo: 'Payment from app',
})
```

### Parameters

All actions accept `config` as the first argument.

### Return Type

Each action returns a typed value or promise result based on its behavior.

### Examples

* [connect](/core/actions/connect)
* [reconnect](/core/actions/reconnect)
* [disconnect](/core/actions/disconnect)
* [getAccount](/core/actions/getAccount)
* [getChainId](/core/actions/getChainId)
* [signMessage](/core/actions/signMessage)
* [sendTransaction](/core/actions/sendTransaction)
* [writeContract](/core/actions/writeContract)
* [callContract](/core/actions/callContract)
* [waitForTransactionReceipt](/core/actions/waitForTransactionReceipt)

### Related

* [React Hooks](/react/hooks)
* [Vue Composables](/vue/composables)


## createConfig

`createConfig` is the central state container for connection status, accounts, and chain settings across core, React, and Vue integrations.

```ts
import { createConfig, iwallet, mainnet } from '@ivem/kit'

const config = createConfig({
  chains: [mainnet],
  connector: iwallet(),
  storage: null,
  ssr: false,
})
```

### Core-Only Usage

`@ivem/kit` can be used standalone without React or Vue.

```ts
import { createConfig, iwallet, connect, getAccount, mainnet } from '@ivem/kit'

const config = createConfig({
  chains: [mainnet],
  connector: iwallet(),
})

await connect(config)
const account = getAccount(config)
```

### Parameters

* `chains`: supported IOST chains.
* `connector`: wallet connector (recommended: `iwallet()`).
* `storage`: persistence storage, pass `null` to disable persistence.
* `ssr`: skip persisted-store hydration and prevent React/Vue integrations from auto-applying `initialState` or calling `reconnect` during SSR-oriented startup.

`testnet` is still exported for compatibility, but as of 2026-03-11 the public IOST testnet is unavailable.


## Getting Started

Use `@ivem/kit` when you want direct access to config state and wallet actions without React or Vue.

### Create Config

```ts
import { createConfig, iwallet, mainnet } from '@ivem/kit'

export const config = createConfig({
  chains: [mainnet],
  connector: iwallet(),
})
```

### Connect and Read State

```ts
import { connect, getAccount, getChainId } from '@ivem/kit'
import { config } from './config'

await connect(config)

const account = getAccount(config)
const chainId = getChainId(config)

console.log(account.address, chainId)
```


## Installation

Install the headless toolkit together with the shared core client package.

:::code-group
```bash [pnpm]
pnpm add @ivem/core @ivem/kit
```

```bash [npm]
npm i @ivem/core @ivem/kit
```

```bash [yarn]
yarn add @ivem/core @ivem/kit
```
:::

### Packages

* `@ivem/core` provides the underlying IOST client and transport primitives.
* `@ivem/kit` provides `createConfig`, the iWallet connector, and framework-agnostic actions.


## Why Ivem Kit Core

`@ivem/kit` is built for apps that want a headless IOST toolkit without framework bindings.

### Why use it

* **Headless by default** Build your own app shell around `createConfig`, connectors, and framework-agnostic actions.
* **Shared toolkit surface** Keep the same config and connector model that powers the React and Vue adapters.
* **Direct action control** Call connect, reconnect, signing, transfer, contract, and receipt APIs without provider wrappers.
* **Small migration surface** Start in core and add a framework adapter later without changing your connector setup.


## iWallet Connector

`iwallet()` uses `window.IWalletJS` by default and is compatible with `iost-iwallet-pro` request methods:

* `connect`
* `disconnect`
* `accounts`
* `chainId` (preferred)
* `network` (fallback)
* `signMessage`
* `sendTransaction`
* `callContract`

### Custom Provider Injection

```ts
import { iwallet } from '@ivem/kit'

const connector = iwallet({
  getProvider: () => window.IWalletJS,
})
```

This is useful for tests or multi-provider injection environments.


## callContract

> Compatibility alias. Prefer `writeContract`.

### Environment Imports

```ts
import { callContract } from '@ivem/kit'
import { useCallContract } from '@ivem/kit-react'
import { useCallContract } from '@ivem/kit-vue'
```

### Usage

```ts
import { callContract } from '@ivem/kit'

const result = await callContract(config, {
  contract: 'token.iost',
  action: 'transfer',
  args: ['iost', 'alice', 'bob', '1.00000000', 'memo'],
  gasRatio: 1,
  gasLimit: 2000000,
})
```

### Parameters

* `config: Config`
* `parameters: {`
* `  contract: string`
* `  action: string`
* `  args: any[]`
* `  account?: string`
* `  gasRatio?: number`
* `  gasLimit?: number`
* `}`

### Return Type

* `Promise<{ hash: string }>`

### Examples

```ts
const { hash } = await callContract(config, {
  contract: 'token.iost',
  action: 'transfer',
  args: ['iost', 'alice', 'bob', '1.00000000', 'memo'],
})
```

### Related

* [writeContract (Core)](/core/actions/writeContract)
* [useWriteContract (React)](/react/hooks/useWriteContract)
* [useWriteContract (Vue)](/vue/composables/useWriteContract)


## connect

### Environment Imports

```ts
import { connect } from '@ivem/kit'
import { useConnect } from '@ivem/kit-react'
import { useConnect } from '@ivem/kit-vue'
```

### Usage

```ts
import { connect } from '@ivem/kit'

await connect(config)
```

### Parameters

* `config: Config`
* `parameters?: undefined`

### Return Type

* `Promise<{ accounts: readonly string[]; chainId: string }>`

### Examples

```ts
const result = await connect(config)
console.log(result.accounts, result.chainId)
```

### Related

* [useConnect (React)](/react/hooks/useConnect)
* [useConnect (Vue)](/vue/composables/useConnect)


## disconnect

### Environment Imports

```ts
import { disconnect } from '@ivem/kit'
import { useDisconnect } from '@ivem/kit-react'
import { useDisconnect } from '@ivem/kit-vue'
```

### Usage

```ts
import { disconnect } from '@ivem/kit'

await disconnect(config)
```

### Parameters

* `config: Config`

### Return Type

* `Promise<void>`

### Examples

```ts
await disconnect(config)
```

### Related

* [useDisconnect (React)](/react/hooks/useDisconnect)
* [useDisconnect (Vue)](/vue/composables/useDisconnect)


## getAccount

### Environment Imports

```ts
import { getAccount } from '@ivem/kit'
import { useAccount } from '@ivem/kit-react'
import { useAccount } from '@ivem/kit-vue'
```

### Usage

```ts
import { getAccount } from '@ivem/kit'

const account = getAccount(config)
```

### Parameters

* `config: Config`

### Return Type

* `{`
* `  address?: string`
* `  addresses: readonly string[]`
* `  chainId: string`
* `  status: 'connected' | 'connecting' | 'disconnected' | 'reconnecting'`
* `  isConnected: boolean`
* `  isConnecting: boolean`
* `  isDisconnected: boolean`
* `  isReconnecting: boolean`
* `}`

### Examples

```ts
const account = getAccount(config)
if (account.isConnected) console.log(account.address)
```

### Related

* [useAccount (React)](/react/hooks/useAccount)
* [useAccount (Vue)](/vue/composables/useAccount)


## getChainId

### Environment Imports

```ts
import { getChainId } from '@ivem/kit'
import { useChainId } from '@ivem/kit-react'
import { useChainId } from '@ivem/kit-vue'
```

### Usage

```ts
import { getChainId } from '@ivem/kit'

const chainId = getChainId(config)
```

### Parameters

* `config: Config`

### Return Type

* `string`

### Examples

```ts
console.log(getChainId(config))
```

### Related

* [useChainId (React)](/react/hooks/useChainId)
* [useChainId (Vue)](/vue/composables/useChainId)


## reconnect

### Environment Imports

```ts
import { reconnect } from '@ivem/kit'
import { useReconnect } from '@ivem/kit-react'
import { useReconnect } from '@ivem/kit-vue'
```

### Usage

```ts
import { reconnect } from '@ivem/kit'

const session = await reconnect(config)
```

### Parameters

* `config: Config`

### Return Type

* `Promise<{ accounts: readonly string[]; chainId: string } | null>`

### Examples

```ts
const restored = await reconnect(config)
if (!restored) console.log('No authorized session')
```

### Related

* [useReconnect (React)](/react/hooks/useReconnect)
* [useReconnect (Vue)](/vue/composables/useReconnect)


## sendTransaction

### Environment Imports

```ts
import { sendTransaction } from '@ivem/kit'
import { useSendTransaction } from '@ivem/kit-react'
import { useSendTransaction } from '@ivem/kit-vue'
```

### Usage

```ts
import { sendTransaction } from '@ivem/kit'

const result = await sendTransaction(config, {
  to: 'receiver_account',
  amount: '1.00000000',
  memo: 'from Ivem Kit',
})
```

### Parameters

* `config: Config`
* `parameters: { token?: string; from?: string; to: string; amount: string; memo?: string }`

### Return Type

* `Promise<{ hash: string }>`

### Examples

```ts
const { hash } = await sendTransaction(config, {
  to: 'receiver_account',
  amount: '1.00000000',
})
```

### Related

* [useSendTransaction (React)](/react/hooks/useSendTransaction)
* [useSendTransaction (Vue)](/vue/composables/useSendTransaction)


## signMessage

### Environment Imports

```ts
import { signMessage } from '@ivem/kit'
import { useSignMessage } from '@ivem/kit-react'
import { useSignMessage } from '@ivem/kit-vue'
```

### Usage

```ts
import { signMessage } from '@ivem/kit'

const signature = await signMessage(config, { message: 'hello iost' })
```

### Parameters

* `config: Config`
* `parameters: { message: string | object; account?: string }`

### Return Type

* `Promise<unknown>`

### Examples

```ts
const signature = await signMessage(config, {
  message: { type: 'login', nonce: '123' },
})
```

### Related

* [useSignMessage (React)](/react/hooks/useSignMessage)
* [useSignMessage (Vue)](/vue/composables/useSignMessage)


## waitForTransactionReceipt

### Environment Imports

```ts
import { waitForTransactionReceipt } from '@ivem/kit'
import { useWaitForTransactionReceipt } from '@ivem/kit-react'
import { useWaitForTransactionReceipt } from '@ivem/kit-vue'
```

### Usage

```ts
import { sendTransaction, waitForTransactionReceipt } from '@ivem/kit'

const tx = await sendTransaction(config, {
  to: 'receiver_account',
  amount: '1.00000000',
})

const receipt = await waitForTransactionReceipt(config, {
  hash: tx.hash,
  stage: 'irreversible',
})
```

### Parameters

* `config: Config`
* `parameters: { hash: string; retryCount?: number; retryDelay?: number; timeout?: number; stage?: "executed" | "irreversible" }`

### Return Type

* `Promise<TxReceipt>`

### Examples

```ts
const receipt = await waitForTransactionReceipt(config, {
  hash: tx.hash,
  timeout: 90_000,
  stage: 'executed',
})

console.log(receipt.status_code)
```

`stage: "executed"` is the fast default and resolves as soon as `transaction.tx_receipt` becomes available.

`stage: "irreversible"` waits for the final irreversible receipt.

### Related

* [useWaitForTransactionReceipt (React)](/react/hooks/useWaitForTransactionReceipt)
* [useWaitForTransactionReceipt (Vue)](/vue/composables/useWaitForTransactionReceipt)


## writeContract

### Environment Imports

```ts
import { writeContract } from '@ivem/kit'
import { useWriteContract } from '@ivem/kit-react'
import { useWriteContract } from '@ivem/kit-vue'
```

### Usage

```ts
import { writeContract } from '@ivem/kit'

const result = await writeContract(config, {
  contract: 'token.iost',
  action: 'transfer',
  args: ['iost', 'alice', 'bob', '1.00000000', 'memo'],
  gasRatio: 1,
  gasLimit: 2000000,
})
```

### Parameters

* `config: Config`
* `parameters: {`
* `  contract: string`
* `  action: string`
* `  args: any[]`
* `  gasRatio?: number`
* `  gasLimit?: number`
* `  approves?: Array<{ token: string; amount: string }>`
* `}`

### Return Type

* `Promise<{ hash: string }>`

### Examples

```ts
const { hash } = await writeContract(config, {
  contract: 'token.iost',
  action: 'balanceOf',
  args: ['iost', 'alice'],
})
```

### Related

* [useWriteContract (React)](/react/hooks/useWriteContract)
* [useWriteContract (Vue)](/vue/composables/useWriteContract)
* [callContract (compatibility)](/core/actions/callContract)