Solana Support - WalletConnect Pay Docs

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(signatures)`	`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 results[] (or signatures[]) 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.

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:7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU

TypeScript
Kotlin
Swift

const 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],
});

val evmAccounts = evmChains.map { chain ->
    "eip155:${chain.id}:${evmAddress}"
}
val solanaAccounts = solanaChains.map { chain ->
    "solana:${chain.reference}:${solanaPublicKey}"
}

val options = pay.getPaymentOptions(
    paymentId = paymentId,
    accounts = evmAccounts + solanaAccounts
)

let evmAccounts = evmChains.map { chain in
    "eip155:\(chain.id):\(evmAddress)"
}
let solanaAccounts = solanaChains.map { chain in
    "solana:\(chain.reference):\(solanaPublicKey)"
}

let options = try await pay.getPaymentOptions(
    paymentId: 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.

TypeScript
Kotlin
Swift

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}`);
  }
}

fun getNamespace(chainId: String): String = chainId.split(':')[0]

for (action in actions) {
    val namespace = getNamespace(action.walletRpc.chainId)
    
    when (namespace) {
        "eip155" -> handleEvmAction(action)
        "solana" -> handleSolanaAction(action)
        else -> error("Unsupported namespace: $namespace")
    }
}

func getNamespace(_ chainId: String) -> String {
    chainId.split(separator: ":").first.map(String.init) ?? ""
}

for action in actions {
    let namespace = getNamespace(action.walletRpc.chainId)
    
    switch namespace {
    case "eip155":
        try await handleEvmAction(action)
    case "solana":
        try await handleSolanaAction(action)
    default:
        throw PaymentError.unsupportedNamespace(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 signatures array.

TypeScript
Kotlin
Swift

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');
}

suspend fun handleSolanaAction(action: Action): String {
    val method = action.walletRpc.method
    
    require(method == "solana_signTransaction") {
        "Unsupported Solana method: $method"
    }
    
    // Params are array-wrapped: [{ transaction }]
    val params = JSONArray(action.walletRpc.params)
    val txData = params.getJSONObject(0).getString("transaction")
    
    // Decode and sign the transaction
    val txBytes = Base64.decode(txData, Base64.DEFAULT)
    val signedTx = solanaWallet.signTransaction(txBytes)
    
    // Return the signed transaction as base64
    return Base64.encodeToString(signedTx, Base64.NO_WRAP)
}

func handleSolanaAction(_ action: Action) async throws -> String {
    let method = action.walletRpc.method
    
    guard method == "solana_signTransaction" else {
        throw PaymentError.unsupportedMethod(method)
    }
    
    // Params are array-wrapped: [{ transaction }]
    let params = try JSONDecoder().decode(
        [[String: String]].self,
        from: action.walletRpc.params.data(using: .utf8)!
    )
    let txData = params[0]["transaction"]!
    
    // Decode and sign the transaction
    let txBytes = Data(base64Encoded: txData)!
    let signedTx = try solanaWallet.signTransaction(txBytes)
    
    // Return the signed transaction as base64
    return signedTx.base64EncodedString()
}

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 fail

Validate 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 signatures array must match the actions array in order and length.

default:
  throw new Error(`Unknown method: ${method}`);
// Never silently skip or return undefined

Complete action handler

Here’s a complete example showing how to handle both EVM and Solana actions in a single payment flow:

TypeScript

async function approvePayment(actions: Action[]): Promise<string[]> {
  const signatures: 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}`);
    }
    
    signatures.push(signature);
  }
  
  return signatures;
}

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.

​Solana payment flow

​Key capabilities

​Implementation requirements

​Advertise Solana accounts

​Route actions by namespace

​Implement Solana signing

​Do not send transactions

​Handle array-wrapped params

​Validate signers at runtime

​Reject unknown methods

​Complete action handler

​Validate your integration

​Sample implementation

React Native

Solana payment flow

Key capabilities

Implementation requirements

Advertise Solana accounts

Route actions by namespace

Implement Solana signing

Do not send transactions

Handle array-wrapped params

Validate signers at runtime

Reject unknown methods

Complete action handler

Validate your integration

Sample implementation