> For the complete documentation index, see [llms.txt](https://docs.freighter.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.freighter.app/mobile-walletconnect/connecting.md).

# Connecting

Establish a WalletConnect session with Freighter Mobile, handle session lifecycle events, and disconnect.

Assumes `provider` and `modal` are initialized as shown in [Installation](/mobile-walletconnect/installation.md).

## Creating a Session

Call `modal.open()` to show the wallet selection modal, then `provider.connect()` to start the pairing. The modal displays a QR code and a list of wallets — when the user selects Freighter or scans the QR code, the connection is established automatically. `connect()` resolves once the wallet approves.

```typescript
// Open the modal (shows a spinner, then the QR code and wallet list)
modal.open();

// Connect — resolves when the wallet approves
const session = await provider.connect({
  namespaces: {
    stellar: {
      methods: [
        "stellar_signXDR",
        "stellar_signAndSubmitXDR",
        "stellar_signMessage",
        "stellar_signAuthEntry",
      ],
      chains: ["stellar:pubnet"],
      events: ["accountsChanged"],
    },
  },
});

if (!session) {
  throw new Error("Connection failed");
}

modal.close();
console.log("Connected! Session topic:", session.topic);
```

The connected session is also accessible at any time via `provider.session`.

Accounts are stored in `session.namespaces.stellar.accounts` as `"stellar:pubnet:G..."` strings — split on `:` to extract the public key:

```typescript
const publicKey = session.namespaces.stellar.accounts[0].split(":")[2];
```

{% hint style="info" %}
Use `namespaces` for methods your dapp needs to function. Use `optionalNamespaces` for methods that enhance the experience but aren't essential.

**Note:** `UniversalProvider` treats `namespaces` as optional at the protocol level on the first connection. After the wallet approves, the approved namespaces are persisted and become required on subsequent connections. To be safe, always verify the approved methods after connecting:

```typescript
const methods = session.namespaces.stellar?.methods || [];
if (!methods.includes("stellar_signXDR")) {
  throw new Error("Wallet does not support required methods");
}
```

{% endhint %}

## Handling Events

Listen for session lifecycle events to keep your UI in sync:

```typescript
// Session was disconnected by the wallet
provider.on("session_delete", ({ topic }) => {
  console.log("Session deleted:", topic);
});

// Session expired
provider.on("session_expire", ({ topic }) => {
  console.log("Session expired:", topic);
});
```

## Disconnecting

When the user wants to disconnect:

```typescript
await provider.disconnect();
```

## Next steps

Once connected, you can [sign transactions, messages, and auth entries](/mobile-walletconnect/signing.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.freighter.app/mobile-walletconnect/connecting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.