Add Freighter developer documentation

[piyalbasu]

This pull request introduces a comprehensive overhaul of the Freighter wallet developer documentation. The updates include a new documentation structure, a rewritten and expanded developer guide, and improved navigation for both browser extension and mobile integration. The documentation now provides clear, example-driven guides for all major Freighter API features, as well as a summary table and integration resources.

Documentation Restructure and Navigation:

• Introduced .gitbook.yaml and SUMMARY.md to define the documentation structure and table of contents, organizing content by integration type and feature. [1] [2]
• Added index.html to support Docsify-based local documentation browsing, enabling easier preview and navigation.

Content Overhaul and Expansion:

• Rewrote the README.md to provide a welcoming introduction, integration options, quick links, and resource references, making it easier for developers to get started and find relevant guides.
• Added a new integrations/README.md page to document third-party integrations such as Soroswap and hardware wallets, encouraging ecosystem adoption.

Developer Guide Enhancements:

• Created and expanded feature-specific guides under developer-guide/:
  • Installation instructions for both npm/yarn and CDN usage, with clear next steps.
  • Connecting to Freighter: detecting, authorizing, and requesting access, with robust code examples and best practices.
  • Reading user data and network details, including when to use each method.
  • Signing transactions, auth entries, and messages, with full API reference and a complete end-to-end example.
  • Token management for Soroban tokens, with example usage and user experience notes.
  • Watching wallet changes in real time using the WatchWalletChanges API.
• Added a new developer guide overview (developer-guide/README.md) summarizing the API and linking to all feature pages.

These changes make the documentation more accessible, up-to-date, and actionable for both new and experienced developers.

References:
[1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12]

[Copilot]

Pull request overview

This PR overhauls the Freighter developer documentation by introducing a structured table of contents and adding/rewriting integration guides for both the browser extension (@stellar/freighter-api) and Freighter Mobile via WalletConnect v2.

Changes:

• Added GitBook navigation structure (.gitbook.yaml, SUMMARY.md) and a Docsify index.html for local browsing.
• Rewrote the root README.md to provide clearer integration pathways and quick links.
• Added new extension and mobile guide pages covering installation, connecting, signing, and related features.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
.gitbook.yaml	Defines GitBook structure (readme + summary).
SUMMARY.md	Adds a table of contents organizing Extension, Mobile, and Integrations docs.
README.md	New landing page with integration selection, quick links, and resources.
index.html	Adds Docsify-based local documentation viewer.
developer-guide/README.md	Extension developer guide overview and API entry points.
developer-guide/installation.md	Extension install/setup instructions (npm/yarn + CDN).
developer-guide/connecting.md	Extension connection/authorization flows (isConnected, isAllowed, setAllowed, requestAccess).
developer-guide/reading-data.md	Extension read methods for address/network details.
developer-guide/signing.md	Extension signing docs + end-to-end example.
developer-guide/token-management.md	Adds Soroban token add flow (addToken).
developer-guide/watching-changes.md	Documents WatchWalletChanges polling watcher.
mobile/README.md	Mobile WalletConnect overview, chains, API list, and error handling.
mobile/installation.md	WalletConnect client installation and initialization.
mobile/connecting.md	WalletConnect session creation, events, and disconnect flow.
mobile/signing.md	WalletConnect signing methods and auth-entry signing example.
integrations/README.md	Lists documented third-party integrations (Soroswap, HW wallets).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[piyalbasu]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

[piyalbasu]

Code review

Found 4 issues:

1. Broken internal link to a non-existent page (soroban-development.md does not exist in the repo)

freighter-developer-docs/developer-guide/signing.md

Lines 67 to 69 in 6af05eb

	See the [`authorizeEntry` helper](https://github.com/stellar/js-stellar-base/blob/e3d6fc3351e7d242b374c7c6057668366364a279/src/auth.js#L97) in `js-stellar-base` for how signed auth entries are used, or the [Soroban Development](soroban-development.md) page for wallet-side patterns.

2. Wrong CDN path — the installed package exposes build/index.min.js, not dist/index.min.js. The URL as written returns a 404.

freighter-developer-docs/developer-guide/installation.md

Lines 50 to 52 in 6af05eb

	```html
	<script src="https://unpkg.com/@stellar/freighter-api/dist/index.min.js"></script>
	```

3. Deprecated package import — stellar-sdk is deprecated and has moved to @stellar/stellar-sdk. The full example should import from "@stellar/stellar-sdk", not "stellar-sdk".

freighter-developer-docs/developer-guide/signing.md

Lines 120 to 122 in 6af05eb

	import { isConnected, requestAccess, signTransaction } from "@stellar/freighter-api";
	import { Server, TransactionBuilder } from "stellar-sdk";

4. Inaccurate description of setAllowed() return value — the hint says it "resolves immediately with true", but the actual return type is Promise<{ isAllowed: boolean } & { error?: FreighterApiError }>. It resolves with { isAllowed: true }, not with the primitive true.

freighter-developer-docs/developer-guide/connecting.md

Lines 58 to 62 in 6af05eb

	{% hint style="info" %}
	If the user has already authorized your app, `setAllowed()` resolves immediately with `true`.
	{% endhint %}

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[piyalbasu]

Code review

Found 1 issue:

1. CDN script paths use dist/index.min.js which returns 404 — the correct path is build/index.min.js. Both the unversioned and pinned URLs are broken, so any developer following the CDN installation instructions will get a failed script load.

freighter-developer-docs/developer-guide/installation.md

Lines 50 to 58 in 6af05eb

	```html
	<script src="https://unpkg.com/@stellar/freighter-api/dist/index.min.js"></script>
	```
	This always loads the latest version automatically. To pin a specific version:
	```html
	<script src="https://unpkg.com/@stellar/freighter-api@6.0.1/dist/index.min.js"></script>
	```

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[piyalbasu]

Code review

Found 1 issue:

1. Server is not a top-level export of @stellar/stellar-sdk — the Horizon server class is namespaced under Horizon.Server. Importing { Server } from the top-level package will give undefined at runtime in v12+. The correct import is import { Horizon } from "@stellar/stellar-sdk" and usage is new Horizon.Server(...). TransactionBuilder is fine as a top-level import (it comes from @stellar/stellar-base which is re-exported at the top level).

freighter-developer-docs/developer-guide/signing.md

Lines 119 to 150 in a96a02a

	```typescript
	import { isConnected, requestAccess, signTransaction } from "@stellar/freighter-api";
	import { Server, TransactionBuilder } from "@stellar/stellar-sdk";
	// 1. Check Freighter is installed
	const connectResult = await isConnected();
	if (!connectResult.isConnected) {
	throw new Error("Freighter not found");
	}
	// 2. Request the user's public key
	const accessResult = await requestAccess();
	if (accessResult.error) {
	throw new Error(accessResult.error.message);
	}
	// 3. Sign the transaction
	const xdr = "AAAAAgAAAAA..."; // your assembled transaction XDR
	const signResult = await signTransaction(xdr, {
	network: "TESTNET",
	address: accessResult.address,
	});
	if (signResult.error) {
	throw new Error(signResult.error.message);
	}
	// 4. Submit to Horizon
	const server = new Server("https://horizon-testnet.stellar.org");
	const tx = TransactionBuilder.fromXDR(
	signResult.signedTxXdr,
	"Test SDF Network ; September 2015",
	);

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[piyalbasu]

Code review

Found 2 issues:

1. getAddress() example logs raw FreighterApiError object instead of error.message — when the error type was updated from string to FreighterApiError in commit 90e6545, this instance in reading-data.md was missed. Every other file (connecting.md, signing.md, token-management.md) was updated to use error.message, but this one still uses console.error(error), which will print [object Object] at runtime.

freighter-developer-docs/developer-guide/reading-data.md

Lines 20 to 27 in a96a02a

	const { address, error } = await getAddress();
	if (error) {
	console.error(error);
	} else {
	console.log("Public key:", address);
	}
	```

2. Docsify script URL returns 404 — index.html loads docsify from cdn.jsdelivr.net/npm/docsify@4.13.1/dist/docsify.min.js, but that path does not exist. The correct path is lib/docsify.min.js (the CSS on line 7 already uses the correct /lib/ prefix). This breaks the documentation site entirely.

freighter-developer-docs/index.html

Lines 18 to 22 in a96a02a

	</script>
	<script src="https://cdn.jsdelivr.net/npm/docsify@4.13.1/dist/docsify.min.js"></script>
	<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js"></script>
	<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-javascript.min.js"></script>
	<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js"></script>

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[JakeUrban]

There is a strong emphasis throughout these docs on user control and the dapp's limited liability

• "without you ever touching a private key"
• "the user reviews everything [...] and stays in full control"
• "You never handle private keys, seed phrases, or encryption."

I'm not sure this is a major concern for our audience worth addressing repeatedly. It may make sense to briefly describe what a self-custody/non-custodial wallet is, but once we do that I think repeated references are redundant.

[JakeUrban]

QR code scanning makes sense when you're connecting Freighter mobile to a website running in your desktop browser, but I think we should focus more on the in-app browser scenario. In that scenario a walletconnect-managed panel is displayed for the user to select their wallet.

ScreenRecording_04-10-2026.10-11-56_1.MP4

[JakeUrban]

stellar-wallets-kit supports walletconnect, which works on mobile?

[piyalbasu]

oh didn't realize they added this - I'll update

[CassioMG]

I've just realized SWK doesn't give support for signMessag and signAuthEntry for WC modules so I created this ticket to handle that with Enrique: stellar/freighter-mobile#815

for the moment dApps would need to handle WC implementation directly to explore all methods Freighter Mobile currently supports

[JakeUrban]

It feels like we're providing answers to this question for an audience that is considering building their own wallet as an alternative. But I think the real question is freighter vs. lobstr vs. xbull vs. stellar-wallets-kit.

Some reasons I can think of in that light:

• developed and maintained by the SDF
• most advanced Stellar wallet. (ex. custom tokens, auth entry and message signing, auth entry inspection, etc.)

[JakeUrban]

Alternatively, we could omit this section if we want to avoid comparisons. The audience is already reading this documentation, after all.

[piyalbasu]

I think I prefer the first suggestion here. Engineers often read integration guides (especially the introduction) of multiple SDK's to determine which option would scale the best for their specific use-case. IMO, It makes sense to highlight why they would want to use Freighter over another wallet

[JakeUrban]

Maybe remove since its the only option for desktop browsers?

[JakeUrban]

Same there -- only option for mobile.

[JakeUrban]

nit: can we rename the developer-guide directory to extension to match mobile?

[JakeUrban]

To this point about being the recommended approach, do we want to discourage usage of setAllowed/isAllowed? I think we even had discussions about deprecating these functions.

[JakeUrban]

Generally in integration guides, you want to optimize for clarity rather than being comprehensive. So even if there are multiple ways to do something, you want to guide users in the direction you want them to take.

[piyalbasu]

Actually, on second thought, we shouldn't add a recommendation here. setAllowed also handles authorization. The key difference is one returns the public key and the other just returns a boolean. I believe the Aha folks requested one of these.

One isn't necessarily better than the other, it just depends on your use-case.

[aristidesstaffieri]

should we consider explaining why you would do this? I think it's a surprise generally that you need to do this at all.

[piyalbasu]

Good call - I'll add this

[aristidesstaffieri]

This section references the freighter-api but we don't explain what it is until the next section called "Connecting". Should we consider a rearrangement of this info or wether it belongs in the overview?

[piyalbasu]

Code review

Found 2 issues:

1. isConnected() hint incorrectly equates "extension not found" with "user is on mobile" — isConnected() returns false for any desktop user without Freighter installed (Firefox, Safari, disabled extension), not just mobile users. Following this guidance would route desktop users without Freighter into the WalletConnect flow.

freighter-developer-docs/extension/connecting.md

Lines 22 to 26 in 53048a9

	{% hint style="info" %}
	`isConnected()` can also be used to detect if a user is on desktop or mobile — if it returns `false`, the user is likely on a mobile device and you should use WalletConnect instead.
	{% endhint %}

2. Full example in mobile signing only declares 2 of 4 methods (stellar_signXDR, stellar_signAndSubmitXDR) in requiredNamespaces.methods, omitting stellar_signMessage and stellar_signAuthEntry. A developer copying this boilerplate will get a session that rejects those two methods. This is inconsistent with mobile/connecting.md which lists all four.

freighter-developer-docs/mobile/signing.md

Lines 278 to 286 in 53048a9

	requiredNamespaces: {
	stellar: {
	methods: ["stellar_signXDR", "stellar_signAndSubmitXDR"],
	chains: ["stellar:pubnet"],
	events: ["accountsChanged"],
	},
	},
	});

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[CassioMG]

we should use this link instead: https://docs.walletconnect.network/app-sdk/overview
this other address (https://docs.walletconnect.com/) links to WalletConnect Pay which is a different thing

[CassioMG]

Suggested change

	Connect your dapp to Freighter Mobile using the [WalletConnect v2](https://docs.walletconnect.com/) protocol. All methods follow the standard JSON-RPC 2.0 request/response format over a WalletConnect session.
	Connect your dapp to Freighter Mobile using the [WalletConnect v2](https://docs.walletconnect.network/app-sdk/overview) protocol. All methods follow the standard JSON-RPC 2.0 request/response format over a WalletConnect session.

[CassioMG]

Suggested change

	- [WalletConnect v2 Docs](https://docs.walletconnect.com/)
	- [WalletConnect v2 Docs](https://docs.walletconnect.network/app-sdk/overview)

[CassioMG]

Suggested change

	1. Sign up at [WalletConnect Cloud](https://cloud.walletconnect.com/) and create a project to get your **Project ID**.
	1. Sign up at [WalletConnect Dashboard](https://dashboard.walletconnect.com/) and create a project to get your **Project ID**.

[CassioMG]

WC is rebranding all the time 😮‍💨

[CassioMG]

Hey @piyalbasu — I opened #2 targeting this branch with a migration of the mobile WalletConnect code samples.

What it does:

• Replaces @walletconnect/sign-client with @walletconnect/universal-provider in all mobile examples
• Adds @reown/appkit modal (createAppKit with manualWCControl) for QR code display and wallet selection
• Adds a Stellar Wallets Kit alternative note (with caveat that it only supports 2 of 4 Freighter Mobile methods)
• Removes the isFreighterInAppBrowser branching from the full example

Why:
@walletconnect/sign-client is no longer referenced in the official WalletConnect/Reown documentation — developers searching their docs won't find guidance on it. @walletconnect/universal-provider is the actively documented package for non-EVM chains, and @reown/appkit replaces the deprecated @walletconnect/modal for the connection UI.

References:

• UniversalProvider docs
• AppKit modal migration guide

[CassioMG]

Suggested change

For **mobile**, the integration works over WalletConnect v2. When a user opens your dapp in a mobile browser, WalletConnect presents a panel where they select Freighter as their wallet and approve the connection. On desktop, the same flow can display a QR code for the user to scan. Either way, a secure relay session is established and signing requests flow through the same pattern — your dapp proposes, the user reviews and approves in the wallet.

For **mobile**, the integration works over WalletConnect v2. When a user opens your dapp in a mobile browser, WalletConnect presents a modal where they select Freighter as their wallet and approve the connection. On desktop, the same flow can display a QR code for the user to scan. Either way, a secure relay session is established and signing requests flow through the same pattern — your dapp proposes, the user reviews and approves in the wallet.