Stellar Support

WalletConnect Pay supports Stellar payments with USDC. Stellar is a sign-only, fee-sponsored chain: WalletConnect Pay builds the payment transaction, your wallet signs it with stellar_signXDR, and WalletConnect Pay wraps the signed transaction in a fee-bump transaction and broadcasts it. The buyer never pays the XLM network fee, and your wallet never submits the transaction.

Stellar payment flowCopy Anchor Link

A Stellar payment follows the same three-call flow as any other WalletConnect Pay payment. The Stellar-specific parts are the signing method (stellar_signXDR), the checks your wallet performs before signing, and the fee bump WalletConnect Pay adds on confirm.

Key differences from other chainsCopy Anchor Link

1. Fee-sponsored — WalletConnect Pay wraps the buyer-signed transaction in a fee bump and pays the XLM fee. The buyer only needs USDC; there is no fee or gas balance check.
2. Sign only, never submit — use stellar_signXDR, not stellar_signAndSubmitXDR. Submitting the inner transaction yourself would make the buyer pay the fee and consume the sequence number WalletConnect Pay is waiting for, which fails the payment.
3. The envelope is opaque — WalletConnect Pay pins the transaction to the buyer's next sequence number, a single USDC payment operation, no memo, and a time bound that ends when the quote expires. Confirm validates all of these, so re-building, adding operations, changing the fee, or adjusting the time bounds gets the payment rejected.
4. Plain string result — the confirm result is the signed TransactionEnvelope as a base64 string, just like a Solana signed transaction. No object result is involved.
5. Mainnet only — WalletConnect Pay settles Stellar on pubnet (stellar:pubnet).

Supported assetsCopy Anchor Link

USDC is a Stellar issued asset, so the buyer's account must have a trustline to the Circle issuer above. An account without the trustline reads as a zero balance, and the gateway does not offer the Stellar option.

Implementation requirementsCopy Anchor Link

Advertise Stellar accountsCopy Anchor Link

Include the wallet's Stellar pubnet account when calling getPaymentOptions, using the CAIP-10 format with the G… StrKey account ID:

stellar:pubnet:<G… account ID>

For example:

stellar:pubnet:GCZ73GTH6LBGTT2K6UB76JR3JQIKMMIPCTI3ZGKN5SJVLJ65GPYSCIBQ

const evmAccounts = evmChains.map(
  (chain) => `eip155:${chain.id}:${evmAddress}`
);
const stellarAccounts = stellarAddress ? [`stellar:pubnet:${stellarAddress}`] : [];

const options = await pay.getPaymentOptions({
  paymentLink,
  accounts: [...evmAccounts, ...stellarAccounts],
});

Route actions by namespaceCopy Anchor Link

Extract the namespace from actions[i].walletRpc.chainId and route stellar actions to the Stellar signer:

const data: string[] = [];

for (const action of actions) {
  const namespace = action.walletRpc.chainId.split(':')[0];

  switch (namespace) {
    case 'eip155':
      data.push(await handleEvmAction(action));
      break;
    case 'solana':
      data.push(await handleSolanaAction(action));
      break;
    case 'stellar':
      data.push(handleStellarAction(action)); // signed envelope, see below
      break;
    default:
      throw new Error(`Unsupported namespace: ${namespace}`);
  }
}

The stellar_signXDR actionCopy Anchor Link

After the user selects the Stellar option, the build action resolves to a walletRpc action. Its params is a JSON string containing a single-element array:

{
  "chainId": "stellar:pubnet",
  "method": "stellar_signXDR",
  "params": "[{\"xdr\":\"AAAAAgAAAACz/ZNn8sJpz0r1A/8mO0wQVjEPFNG8mU3sk1Wk7TPxIQAAAGQAGYGzAAAACgAAAAEAAAAA...\",\"chain\":\"stellar:pubnet\",\"account\":\"stellar:pubnet:GCZ73GTH6LBGTT2K6UB76JR3JQIKMMIPCTI3ZGKN5SJVLJ65GPYSCIBQ\"}]"
}

The payload follows the Stellar RPC reference. If your wallet already implements stellar_signXDR for WalletConnect sessions, reuse that signer.

Verify and sign the envelopeCopy Anchor Link

Before signing, your wallet must:

1. Bind the network passphrase from chainId — derive it from the action's CAIP-2 chain (stellar:pubnet → Public Global Stellar Network ; September 2015). Never trust a network reference from the request body.
2. Check the source account — the transaction's source must equal the account parameter, and your wallet must custody that account.
3. Show the payment — decode the operation and display the USDC amount and destination in the signing UI.
4. Sign without modifying — add the buyer's signature and return the full envelope. Do not change the fee, sequence number, time bounds, memo, or operations.

import { Keypair, Networks, TransactionBuilder } from '@stellar/stellar-sdk';

const NETWORK_PASSPHRASES: Record<string, string> = {
  'stellar:pubnet': Networks.PUBLIC,
};

function handleStellarAction(action: Action): string {
  const { chainId, method, params } = action.walletRpc;
  if (method !== 'stellar_signXDR') {
    throw new Error(`Unsupported Stellar method: ${method}`);
  }

  // Bound from the action's chain, never from the request body
  const networkPassphrase = NETWORK_PASSPHRASES[chainId];
  if (!networkPassphrase) {
    throw new Error(`Unsupported Stellar chain: ${chainId}`);
  }

  const [{ xdr, account }] = JSON.parse(params);
  const signerAddress = account.split(':')[2];

  const transaction = TransactionBuilder.fromXDR(xdr, networkPassphrase);
  if ('innerTransaction' in transaction || transaction.source !== signerAddress) {
    throw new Error('Stellar transaction source does not match the buyer account');
  }

  const keypair: Keypair = getStellarKeypair(signerAddress); // your key management
  transaction.sign(keypair);

  // Plain base64 string — WalletConnect Pay adds the fee bump and broadcasts
  return transaction.toXDR();
}

Return the signed envelope on confirmCopy Anchor Link

Pass the signed envelope in data, in the same position as its action. It is a plain base64 string, so it fits the same data array as EVM signatures and Solana transactions:

const result = await pay.confirmPayment({
  paymentId,
  optionId,
  data, // e.g. ["AAAAAgAAAACz/ZNn8sJpz0r1A/8mO0wQVjEPFNG8mU3sk1Wk7TPxIQAAAGQ...AAAAAEFNB7s="]
});

The gateway also accepts { "signedXDR": "<base64>" } — the stellar_signXDR response shape — as the result. Returning the bare string is the simplest option and works with every SDK version.

On confirm, WalletConnect Pay validates the envelope against the quote, wraps it in a fee bump paid by WalletConnect Pay, and broadcasts it. confirmPayment resolves with succeeded or failed, exactly as on other chains.

Error handlingCopy Anchor Link

Validate your integrationCopy Anchor Link

Sample implementationCopy Anchor Link

Additional resourcesCopy Anchor Link

• Stellar RPC reference — method signatures, account format, and signing semantics for WalletConnect sessions.
• Fee-bump transactions — how the sponsored fee works.
• Stellar XDR reference.