# How to connect to a wallet in AppKit (https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/howto/connect-to-a-wallet/content.md)



Learn how to open a wallet session, restore it across reloads, and disconnect cleanly.

## How it works [#how-it-works]

A wallet is the signing application that owns the keys. A connector is the transport AppKit uses to open the wallet flow, restore sessions, list connected wallets, and route signing requests. A connector is not a wallet and does not sign — signing always happens inside the user's wallet application.

AppKit can track multiple connected wallets, but one wallet is selected for actions such as transfers and data signing. A selected wallet can change after disconnects, network changes, or session restore, so read it from AppKit state instead of storing it as long-lived application state. The same wallet on a different network has a different wallet ID, and AppKit treats those as separate wallet objects.

## Before you begin [#before-you-begin]

You need an `AppKit` instance with at least one connector and the React providers mounted. See [Add wallet connectors](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/get-started/connectors/content.md) for the instance and [Install AppKit → Wrap the application](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/get-started/installation/react-app/content.md) for the provider setup.

## Drop-in button [#drop-in-button]

`<TonConnectButton />` from `@ton/appkit-react` opens the TON Connect modal, manages the session, and renders the connected address. This is the recommended path for most apps.

```tsx
import { TonConnectButton } from '@ton/appkit-react';

export function Header() {
  return <TonConnectButton />;
}
```

## Custom connector picker [#custom-connector-picker]

When the app needs a tailored UI, render the connector list directly. `useConnectors()` returns an array of registered connectors, and `useConnect()` accepts a `connectorId`.

```tsx
import { useConnect, useConnectors, useDisconnect, useSelectedWallet } from '@ton/appkit-react';

export function ConnectPanel() {
  const connectors = useConnectors();
  const [wallet] = useSelectedWallet();
  const connect = useConnect();
  const disconnect = useDisconnect();

  if (wallet) {
    return (
      <button onClick={() => disconnect.mutate({ connectorId: wallet.connectorId })}>
        Disconnect {wallet.getAddress()}
      </button>
    );
  }

  return connectors.map((connector) => (
    <button key={connector.id} onClick={() => connect.mutate({ connectorId: connector.id })}>
      Connect {connector.metadata.name}
    </button>
  ));
}
```

If the `connectorId` passed to `connect` is not registered, the action throws `Connector with ID "<ID>" not found`. Confirm registration with `getConnectors` (or `useConnectors` in React) before calling `connect`.

## Read the connected wallet [#read-the-connected-wallet]

`useSelectedWallet` returns the wallet used by the next action. The wallet exposes `getAddress()` and `getNetwork()`.

```tsx
import { useSelectedWallet } from '@ton/appkit-react';

const [wallet] = useSelectedWallet();
const address = wallet?.getAddress();
const network = wallet?.getNetwork();
```

For just the address string, `useAddress` is the convenience hook:

```tsx
import { useAddress } from '@ton/appkit-react';

const address = useAddress(); // string | undefined
```

## Register a connector after construction [#register-a-connector-after-construction]

If connector configuration is not available at construction time, register it with `addConnector`. Use this for user-scoped manifest URLs, feature flags, or dynamic wallet sets. `addConnector` accepts a `Connector` instance or a factory and returns an unregister function.

```ts
import { addConnector, createTonConnectConnector } from '@ton/appkit';
import { appKit } from './appkit';

const unregister = addConnector(
  appKit,
  createTonConnectConnector({
    tonConnectOptions: { manifestUrl: 'https://example.com/tonconnect-manifest.json' },
  }),
);

// Later, to remove and destroy the connector:
unregister();
```

Connector IDs are singletons. Registering a second connector with the same ID calls `destroy()` on the previous one before installing the new.

## Connect from vanilla JS [#connect-from-vanilla-js]

```ts
import { connect, disconnect, getConnectors } from '@ton/appkit';
import { appKit } from './appkit';

const [connector] = getConnectors(appKit);
await connect(appKit, { connectorId: connector.id });

// Later:
await disconnect(appKit, { connectorId: connector.id });
```

`connector.connectWallet()` and `connector.disconnectWallet()` are the lower-level equivalents when direct connector access is preferred.

## Wallet and Connector interfaces [#wallet-and-connector-interfaces]

Every connected wallet exposes the same minimum surface: a reference to the connector that produced it, four identity readers, and two wallet-approved operations that are routed through the connector.

```ts
interface WalletInterface {
  /** Connector that created this wallet */
  readonly connectorId: string;

  // Identity
  getAddress(): UserFriendlyAddress;
  getPublicKey(): Hex;
  getNetwork(): Network;
  getWalletId(): string;

  // Actions requiring wallet signature
  sendTransaction(request: TransactionRequest): Promise<SendTransactionResponse>;
  signData(payload: SignDataRequest): Promise<SignDataResponse>;
}
```

Connectors implement a small interface that AppKit treats as opaque transport — the protocol underneath is hidden.

```ts
interface Connector {
  readonly id: string;
  readonly type: string;
  readonly metadata: ConnectorMetadata;
  destroy(): void;
  connectWallet(network?: Network): Promise<void>;
  disconnectWallet(): Promise<void>;
  getConnectedWallets(): WalletInterface[];
}
```

The bundled `createTonConnectConnector` covers most apps. It wraps `@tonconnect/ui`, restores prior sessions when the connector is first read, and syncs TON Connect with AppKit's default network.

## Errors and recovery [#errors-and-recovery]

Wrap every action in try/catch and convert errors with `getErrorMessage` from `@ton/appkit`.

| Error             | Recovery                                           |
| ----------------- | -------------------------------------------------- |
| User rejected     | Keep state unchanged and allow retry.              |
| Missing connector | Check the AppKit configuration.                    |
| Expired session   | Disconnect and request a new connection.           |
| Wrong network     | Prompt the user to switch network in their wallet. |

## Tips [#tips]

* Do not call mutations or signing actions while `getSelectedWallet` is `null` — the action will throw.
* Do not assume every connector supports every flow. Catch rejections from the wallet and surface a recovery option.
* Do not store `selectedWalletId` as long-lived application state. The selected wallet can change after disconnects, network changes, or session restores.
* In application code, use public actions or React hooks instead of calling connector methods directly, so AppKit's event flow stays consistent. Connector methods are still the public surface for custom connector implementations.

## Related pages [#related-pages]

* [Set up AppKit](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/howto/appkit/content.md)
* [`@ton/appkit-react` reference](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/reference/appkit-react/content.md)
* [Use UI widgets](https://docs-rbcpr9qys-ton-core-docs.vercel.app/llms/applications/appkit/howto/use-ui-widgets/content.md)