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 |
| Stellar Wallets Kit | The built-in Scopuly module; SWK 2.7 integration |
| Soroban authorization or message verification | Signing formats and boundaries |
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
- Detect availability without prompting. Call
requestAccess()from the user's Connect action. Access is scoped to the dApp origin. - 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. - Subscribe to
onChange(). Invalidate cached account, network, prepared XDR and pending results when the connection changes. Unsubscribe on disposal. - Build or simulate the operation for the intended network. Immediately before signing, confirm the account and network still match. Pass both
addressandnetworkPassphraseexplicitly. - Handle rejected promises and resolved
{ error }results. Check required result fields before reporting success. Error-4means user rejection; do not retry it automatically. - 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 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 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 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 and device checklist 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.