Web client (browser wallets)
The browser WebClient: detect the user's Stellar wallet, then build, sign and submit the transaction.
The web client runs in the browser and is the only part that touches the user's wallet. It is provider-agnostic and never needs your secret key.
@cosmosapp/pay_sdk/web completes an intent in the user's browser. Stellar
wallets don't ingest SEP-7 web+stellar: URIs from a dapp, so the web client
auto-detects the wallet, adapts the intent into a transaction, signs and submits.
npm install @cosmosapp/pay_sdk @stellar/stellar-sdkOne-call happy path
import { WebClient } from '@cosmosapp/pay_sdk/web';
const webClient = new WebClient(); // auto-detects the wallet
const result = await webClient.pay(intent); // intent = payload/instance/URI string
result.wallet; // 'freighter' | 'xbull' | 'rabet' | 'lobstr' | 'albedo' | …
result.account; // the G... account that signed
result.txHash; // on-chain transaction hash
result.submitted; // trueReport result.txHash to your server and finalize with intent.validate(txHash).
Supported wallets
Auto-detected (inject a browser global, zero config):
| Wallet | id | Detection |
|---|---|---|
| Freighter | freighter | window.freighterApi |
| xBull | xbull | window.xBullSDK |
| Rabet | rabet | window.rabet |
Enabled by passing their library (no reliable global):
| Wallet | id | Enable |
|---|---|---|
| Albedo | albedo | new WebClient({ albedo }) — import albedo from '@albedo-link/intent' |
| LOBSTR | lobstr | new WebClient({ lobstr }) — import * as lobstr from '@lobstrco/signer-extension-api' |
Inspect & choose
import { Wallets } from '@cosmosapp/pay_sdk/web';
const wallets = await webClient.getAvailableWallets(); // [{ id, name, available }]
const { wallet, address, network } = await webClient.connect(); // just connect
await webClient.pay(intent, { wallet: Wallets.XBULL }); // pin for one call
const pinned = new WebClient({ preferredWallets: [Wallets.XBULL, Wallets.FREIGHTER] });pay() options & variations
await webClient.pay(intent, { amount: '5' }); // open-amount intent
await webClient.pay(intent, { sign: true }); // sign WITHOUT submitting → { signedXdr }
await webClient.pay(intent, { submit: false }); // also skips submission
await webClient.pay(intent, { wallet: 'xbull' });
// Inspect the tx before prompting the wallet:
const { xdr, source, network } = await webClient.buildTransaction(intent);pay vs tx: for pay intents the client builds a payment from the connected
account (loads sequence from Horizon, adds op + memo, fee, timebounds). For tx
intents it signs the returned XDR as-is (throws if the connected wallet isn't the
intent's source).
Network
Inferred from the intent (network / SEP-7 network_passphrase). Override if you
self-host Horizon: new WebClient({ network: 'testnet', horizonUrl: '...' }).
Custom wallet adapter
import { WebClient } from '@cosmosapp/pay_sdk/web';
const myWallet = {
id: 'my-wallet',
name: 'My Wallet',
async isAvailable() { return Boolean(globalThis.myWallet); },
async getPublicKey() { return globalThis.myWallet.getAddress(); },
async signTransaction(xdr, { networkPassphrase }) {
return globalThis.myWallet.sign(xdr, networkPassphrase);
},
};
const wc = new WebClient();
wc.registerWallet(myWallet, /* prepend */ true);Dependency injection (SSR / bundle control)
import * as StellarSdk from '@stellar/stellar-sdk';
import freighter from '@stellar/freighter-api';
const wc = new WebClient({ stellarSdk: StellarSdk, freighter });Direct API (trusted environments only)
⚠️ Ships your API key to the browser. Only for prototypes/internal tools with a scoped testnet
dv_key. For production, create/validate on your server.
const wc = new WebClient({ apiKey: 'dv_test_only' });
const intent = await wc.createPay({ destination: 'G...', amount: '10' });
const result = await wc.pay(intent);
const outcome = await wc.validate(intent.id, result.txHash);