---
name: scopuly-wallet
description: Integrate or troubleshoot the Scopuly Stellar wallet in a browser dApp using its Provider API or Stellar Wallets Kit. Use for wallet connection, transaction signing, SEP-53 messages, Soroban authorization signatures, and account or network changes on Scopuly Mobile and the paired browser extension.
license: MIT
metadata:
  author: Scopuly
  version: "0.1.0"
---

# Scopuly Wallet Integration

Build against the public Scopuly provider. Keep the application's existing framework and wallet-selection flow. If it already uses Stellar Wallets Kit, use that integration rather than adding a second connection manager.

## Choose the integration

| Existing application | Use |
| --- | --- |
| Scopuly-specific connection or direct provider integration | `@scopuly/signer-extension-api@0.3.3`; [provider lifecycle](references/provider.md) |
| Stellar Wallets Kit | The built-in Scopuly module; [SWK 2.7 integration](references/stellar-wallets-kit.md) |
| Soroban authorization or message verification | [Signing formats and boundaries](references/signing.md) |

The provider is injected as `window.scopuly` in Scopuly Mobile's dApp browser and by the paired browser extension. The npm API is a typed wrapper; installing it does not inject a wallet. An ordinary mobile browser does not automatically have a provider.

Use browser-only initialization in SSR applications. Check `isScopuly === true` and `platform === "mobile" || platform === "extension"`. If injection is delayed, listen for `scopuly#initialized`, use a bounded wait and remove the listener. Do not overwrite another wallet's `window.stellar.provider`.

## Implement the flow

1. Detect availability without prompting. Call `requestAccess()` from the user's Connect action. Access is scoped to the dApp origin.
2. Read the selected address and `networkPassphrase`. Compare the wallet's network with the application's intended network. `getNetwork()` reports state; it does not switch the wallet.
3. Subscribe to `onChange()`. Invalidate cached account, network, prepared XDR and pending results when the connection changes. Unsubscribe on disposal.
4. Build or simulate the operation for the intended network. Immediately before signing, confirm the account and network still match. Pass both `address` and `networkPassphrase` explicitly.
5. Handle rejected promises and resolved `{ error }` results. Check required result fields before reporting success. Error `-4` means user rejection; do not retry it automatically.
6. Verify the returned signer and signature where the application consumes the signed result. Treat a signed transaction, a submitted transaction and confirmed settlement as separate states.

The tested [wallet helper](assets/wallet.ts) implements connection invalidation, result checks, duplicate-request protection, SEP-53 verification and signed-XDR verification. It uses `@scopuly/signer-extension-api@0.3.3`, `@stellar/stellar-sdk@17.0.0` and `buffer@6.0.3`. Copy it only if it fits the application; do not replace an existing wallet architecture unnecessarily.

## Signing contract

| Method | Input | Result |
| --- | --- | --- |
| `signTransaction` | Base64 transaction-envelope XDR | `signedTxXdr`; use `submit: false` for sign-only flows |
| `signAndSubmitTransaction` | Base64 transaction-envelope XDR | `status`, optional `hash` and signed XDR; `pending` is not settlement |
| `signMessage` | UTF-8 string | `signedMessage`: 64-byte Ed25519 signature encoded as hex |
| `signAuthEntry` | Base64 **HashIdPreimage** XDR for Soroban authorization | `signedAuthEntry`: raw 64-byte Ed25519 signature encoded as base64 |

Despite its name, `signAuthEntry` does not take a full `SorobanAuthorizationEntry` or return a signed XDR entry. Do not interchange its base64 signature with the hex message signature. Read [signing.md](references/signing.md) before implementing these paths.

Scopuly signs through its approval UI. Do not request a secret key or seed phrase, invent a server signing endpoint, or add unattended signing. Signing options do not include derivation paths, custom submission URLs, or an API to switch networks. A provider-based integration does not need a WalletConnect/Reown project ID.

For sign-only transactions, return the verified XDR to the caller. Submit only when the requested application flow includes submission. After a timeout, reconcile the original transaction hash before offering another payment; a timeout is not evidence of failure.

`reportX402Receipt` attaches a verified receipt to wallet activity; it does not make a payment. This skill covers the wallet signing boundary, not an x402 merchant implementation, MPP sessions, autonomous agents or spending policies. Use the [Stellar payment skill](https://skills.stellar.org/skills/agentic-payments/SKILL.md) for protocol-specific work.

## Verify the integration

Exercise: missing provider, delayed injection, explicit connection, approved and rejected signing, account/network change during a request, malformed output, and listener cleanup. Verify layouts on mobile and desktop. Use Testnet for transaction examples; never substitute Mainnet when Testnet is unavailable.

The repository's [connect-and-sign example](https://github.com/Scopuly/scopuly-skills/tree/main/examples/connect-sign) and [device checklist](https://github.com/Scopuly/scopuly-skills/blob/main/docs/testing.md) provide reproducible checks. Report simulated-provider tests separately from real-device results.

## Sources and compatibility

Checked against the published Provider API **0.3.3** and SWK **2.7.0**, 2026-09-30. Pin versions in runnable examples; check newer releases before updating guidance.

- [Provider API and supported platforms](https://extension.scopuly.com/docs/provider-api/)
- [Public SDK source and types](https://github.com/Scopuly/signer-extension-api)
- [SWK Scopuly module](https://github.com/Creit-Tech/Stellar-Wallets-Kit/blob/main/src/sdk/modules/scopuly.module.ts)