Solana Support
Implement Solana payment capabilities in your wallet including native SOL transactions and mixed-chain payment options.
WalletConnect Pay supports Solana payments, enabling users to pay with native SOL and SPL tokens. This guide covers how to extend your wallet's WalletConnect Pay integration to support Solana payments end-to-end.
This guide applies whether you integrate with the Wallet Pay SDK or directly with the Gateway API (API-first). The signing requirements are identical — Solana actions arrive as walletRpc actions, and the signed transaction is returned in the results array. The code samples below use SDK method names; if you are integrating API-first, the equivalents are:
| SDK | Gateway API |
|---|---|
getPaymentOptions({ accounts }) | POST /v1/gateway/payment/{id}/options with accounts[] |
option.actions / getRequiredPaymentActions | the option's actions[], resolved via POST /v1/gateway/payment/{id}/fetch when an action is type build |
confirmPayment(data) | POST /v1/gateway/payment/{id}/confirm with results[] |
Everything else in this guide — advertising Solana accounts, routing by namespace, the solana_signTransaction payload, and returning the signed transaction blob — is the same in both integrations.
Solana payment flow
A Solana payment follows the same three-call flow as any other WalletConnect Pay payment. The only Solana-specific parts are the signing method (solana_signTransaction) and that your wallet signs but never broadcasts — the WalletConnect Pay backend submits the signed transaction to the network.
The data[] (or results[] API-first) you submit on confirm must match the option's actions[] in order and length — including any EVM actions that precede a Solana action in a mixed-chain option. The former signatures parameter is deprecated but still accepted.
Key capabilities
Implementing Solana support enables three primary features:
- Native SOL transactions — Users can initiate Solana payments through Pay links when merchants support the network
- Mixed-chain options — Single payment links can present both EVM and Solana choices simultaneously
- Namespace-based routing — Individual actions route to appropriate signers based on CAIP-2 namespace identifiers
Implementation requirements
Follow these requirements to correctly implement Solana payment support in your wallet.
Advertise Solana accounts
Include Solana accounts when calling getPaymentOptions using the CAIP-10 format:
solana:<chainReference>:<base58Pubkey>For example, a Solana mainnet account would be formatted as:
solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsUconst evmAccounts = evmChains.map(
(chain) => `eip155:${chain.id}:${evmAddress}`
);
const solanaAccounts = solanaChains.map(
(chain) => `solana:${chain.reference}:${solanaPublicKey.toBase58()}`
);
const options = await pay.getPaymentOptions({
paymentId,
accounts: [...evmAccounts, ...solanaAccounts],
});Only advertise Solana accounts if your wallet has Solana keys available. Wallets without Solana support should not include Solana accounts in the request.
Route actions by namespace
Determine the signing wallet for each action using the namespace from the chain ID. Extract the namespace from actions[i].walletRpc.chainId rather than assuming a single wallet type for all actions.
function getNamespace(chainId: string): string {
return chainId.split(':')[0];
}
for (const action of actions) {
const namespace = getNamespace(action.walletRpc.chainId);
switch (namespace) {
case 'eip155':
// Route to EVM wallet
await handleEvmAction(action);
break;
case 'solana':
// Route to Solana wallet
await handleSolanaAction(action);
break;
default:
throw new Error(`Unsupported namespace: ${namespace}`);
}
}Implement Solana signing
For Solana actions, implement the solana_signTransaction method. Sign the transaction and append the signed transaction blob, base64-encoded to the data array.
async function handleSolanaAction(action: Action): Promise<string> {
const { method, params } = action.walletRpc;
if (method !== 'solana_signTransaction') {
throw new Error(`Unsupported Solana method: ${method}`);
}
// Params are array-wrapped: [{ transaction }]
const [{ transaction }] = JSON.parse(params);
// Decode the base64 transaction
const txBuffer = Buffer.from(transaction, 'base64');
const tx = Transaction.from(txBuffer);
// Sign the transaction
tx.sign(solanaKeypair);
// Return the signed transaction as base64
return tx.serialize().toString('base64');
}Return the signed transaction, not the signature. Solana signer libraries may return both a detached bs58 signature and the signed transaction blob. WalletConnect Pay expects the complete base64-encoded signed transaction, not the detached signature.
Do not send transactions
Do not implement solana_signAndSendTransaction for Pay flows. The WalletConnect Pay backend handles broadcasting the signed transaction. Your wallet should only sign and return the signed transaction blob.
Handle array-wrapped params
The Pay backend provides params in an array-wrapped structure: [{ transaction }]. Make sure to unwrap this structure when parsing the transaction data.
// Correct: unwrap the array
const [{ transaction }] = JSON.parse(params);
// Incorrect: accessing params directly
const { transaction } = JSON.parse(params); // This will failValidate signers at runtime
Guard action handlers against missing signers at execution time. If your wallet doesn't have a Solana signer available when a Solana action is encountered, raise an error rather than silently skipping the action.
if (namespace === 'solana' && !solanaWallet) {
throw new Error('Solana wallet not available');
}Reject unknown methods
Reject unknown wallet-RPC methods instead of silently omitting them from result arrays. The data array must match the actions array in order and length.
default:
throw new Error(`Unknown method: ${method}`);
// Never silently skip or return undefinedComplete action handler
Here's a complete example showing how to handle both EVM and Solana actions in a single payment flow:
async function approvePayment(actions: Action[]): Promise<string[]> {
const data: string[] = [];
for (const action of actions) {
const { chainId, method, params } = action.walletRpc;
const namespace = chainId.split(':')[0];
let signature: string;
switch (namespace) {
case 'eip155':
signature = await handleEvmAction(method, chainId, params);
break;
case 'solana':
signature = await handleSolanaAction(method, params);
break;
default:
throw new Error(`Unsupported namespace: ${namespace}`);
}
data.push(signature);
}
return data;
}
async function handleEvmAction(
method: string,
chainId: string,
params: string
): Promise<string> {
const parsed = JSON.parse(params);
switch (method) {
case 'eth_sendTransaction': {
const tx = await evmWallet.sendTransaction(chainId, parsed[0]);
await tx.wait();
return tx.hash;
}
case 'eth_signTypedData_v4':
return await evmWallet.signTypedData(chainId, parsed);
default:
throw new Error(`Unsupported EVM method: ${method}`);
}
}
async function handleSolanaAction(
method: string,
params: string
): Promise<string> {
if (method !== 'solana_signTransaction') {
throw new Error(`Unsupported Solana method: ${method}`);
}
const [{ transaction }] = JSON.parse(params);
const txBuffer = Buffer.from(transaction, 'base64');
const tx = Transaction.from(txBuffer);
tx.sign(solanaKeypair);
return tx.serialize().toString('base64');
}Validate your integration
Before shipping your Solana support implementation, verify these scenarios work correctly:
SOL-only payment
Test a payment link that only offers Solana options. Verify that:
- The Solana option is presented to the user
- The transaction is signed correctly
- The base64-encoded signed transaction is submitted
- The payment completes successfully
Mixed EVM and Solana payment
Test a payment link that offers both EVM and Solana options. Verify that:
- Both option types are presented
- Users can select either network
- The correct signer is used for the selected option
- Payment completes regardless of which option is chosen
EVM flow regression
After adding Solana support, verify that existing EVM flows still work:
- USDC payments with EIP-3009
- USDT payments with Permit2
- Native token payments
Missing Solana wallet
Test behavior when Solana keys are not available:
- Solana options should not be advertised to users
- No errors should occur during option fetching
- EVM options should work normally
Sample implementation
The React Native reference wallet demonstrates Solana support implementation:
React Native
wallets/rn_cli_wallet — see PaymentStore.approvePayment for namespace dispatch logic and usePairing.handlePaymentLink for account concatenation.