delegatedSignTransaction

Signs a Solana transaction using delegated access on behalf of a user

Function Signature

delegatedSignTransaction(
  client: DelegatedSvmWalletClient,
  params: {
    walletId: string;
    walletApiKey: string;
    keyShare: ServerKeyShare | ServerKeyShare[];
    transaction: VersionedTransaction | Transaction;
    shareSetId?: string;
    signerAddress?: string;
    derivationPath?: Uint32Array;
    chainId?: string;
    context?: SignMessageContext;
    sponsor?: boolean;
    userId?: string;
    traceContext?: TraceContext;
  }
): Promise<VersionedTransaction | Transaction>

Description

Signs a Solana transaction on behalf of a user who has granted delegation permission. This function supports both legacy Transaction and VersionedTransaction types from @solana/web3.js.

The function returns the signed transaction object with the signature added, ready to be sent to the Solana network.

For gasless transactions where a separate fee payer covers gas, set transaction.feePayer to the fee payer’s public key and pass signerAddress to identify the actual signer.

Pass sponsor: true and userId to use Dynamic-funded gas sponsorship instead of a separate fee payer. The SDK sends the transaction to the sponsorship endpoint, swaps the fee payer for a sponsor, and signs as the user.

Parameters

Required Parameters

• client (DelegatedSvmWalletClient) - The delegated client instance created with createDelegatedSvmWalletClient()
• walletId (string) - The wallet ID from the delegation webhook
• walletApiKey (string) - The wallet-specific API key from the delegation webhook
• keyShare (ServerKeyShare | ServerKeyShare[]) - The server key share(s) from the delegation webhook
• transaction (VersionedTransaction | Transaction) - The Solana transaction to sign

Optional Parameters

• shareSetId (string) - The shareSetId from the wallet.delegation.created webhook payload. If omitted, the server resolves the correct share set by walletId and share-set type.
• signerAddress (string) - The address that should sign the transaction. If not provided, defaults to the first signer (VersionedTransaction) or fee payer (Transaction). Use this for gasless transactions where a separate fee payer pays the fees.
• derivationPath (Uint32Array) - Custom derivation path for the signing key.
• chainId (string) - Chain ID for the signing context.
• context (SignMessageContext) - Additional context for the signing operation.
• sponsor (boolean) - When true, Dynamic funds the transaction fee. Defaults to false.
• userId (string) - Required when sponsor is true. UUID of the end user who owns the wallet.
• traceContext (TraceContext) - Distributed tracing context for observability.

Returns

Promise<VersionedTransaction | Transaction> - The signed transaction with the signature added

Example

Basic Transaction Signing

import {
  createDelegatedSvmWalletClient,
  delegatedSignTransaction
} from '@dynamic-labs-wallet/node-svm';
import { Transaction, SystemProgram, PublicKey, Connection } from '@solana/web3.js';

const delegatedClient = createDelegatedSvmWalletClient({
  environmentId: 'your-environment-id',
  apiKey: 'your-server-api-key',
});

const connection = new Connection('https://api.mainnet-beta.solana.com');

const transaction = new Transaction().add(
  SystemProgram.transfer({
    fromPubkey: new PublicKey(senderAddress),
    toPubkey: new PublicKey(recipientAddress),
    lamports: 1000000,
  })
);

transaction.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
transaction.feePayer = new PublicKey(senderAddress);

const signedTx = await delegatedSignTransaction(delegatedClient, {
  walletId: 'wallet-id-from-webhook',
  walletApiKey: 'wallet-api-key-from-webhook',
  keyShare: keyShareFromWebhook,
  transaction,
});

console.log('Transaction signed:', signedTx);

Gasless Transaction with Separate Fee Payer

When a separate wallet pays the gas fees, set feePayer to the sponsor and pass signerAddress so the delegated wallet signs only the instruction:

import {
  createDelegatedSvmWalletClient,
  delegatedSignTransaction,
} from '@dynamic-labs-wallet/node-svm';
import { Transaction, SystemProgram, PublicKey, Connection, Keypair, VersionedTransaction } from '@solana/web3.js';
import bs58 from 'bs58';
import nacl from 'tweetnacl';

const delegatedClient = createDelegatedSvmWalletClient({
  environmentId: process.env.DYNAMIC_ENVIRONMENT_ID!,
  apiKey: process.env.DYNAMIC_API_KEY!,
});

const connection = new Connection(process.env.SOLANA_RPC_URL || 'https://api.devnet.solana.com');
const feePayer = Keypair.fromSecretKey(bs58.decode(process.env.FEE_PAYER_PRIVATE_KEY!));

const credentials = await getDelegationCredentials(userId);
const sender = new PublicKey(credentials.publicKey);

const transaction = new Transaction();
const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash('confirmed');
transaction.recentBlockhash = blockhash;
transaction.lastValidBlockHeight = lastValidBlockHeight;
transaction.feePayer = feePayer.publicKey; // Sponsor pays fees

transaction.add(
  SystemProgram.transfer({
    fromPubkey: sender,
    toPubkey: new PublicKey(recipientAddress),
    lamports: 1000000,
  })
);

// Sign with delegated wallet — signerAddress identifies the sender
let signedTx = await delegatedSignTransaction(delegatedClient, {
  walletId: credentials.walletId,
  walletApiKey: credentials.walletApiKey,
  keyShare: credentials.keyShare,
  transaction,
  signerAddress: sender.toString(),
});

// Add fee payer signature
if (signedTx instanceof VersionedTransaction) {
  signedTx.sign([feePayer]);
} else {
  const message = signedTx.serializeMessage();
  const feePayerSig = nacl.sign.detached(message, feePayer.secretKey);
  signedTx.addSignature(feePayer.publicKey, Buffer.from(feePayerSig));
}

const signature = await connection.sendRawTransaction(signedTx.serialize());
await connection.confirmTransaction({ signature, blockhash, lastValidBlockHeight });
console.log('Gasless transaction confirmed:', signature);

Dynamic Sponsorship

Pass sponsor: true and the wallet owner’s userId to have Dynamic fund the transaction fee. signerAddress is required so the delegated wallet signs as the user, not as the sponsor fee payer.

import {
  createDelegatedSvmWalletClient,
  delegatedSignTransaction,
} from '@dynamic-labs-wallet/node-svm';
import { Transaction, SystemProgram, PublicKey, Connection } from '@solana/web3.js';

const delegatedClient = createDelegatedSvmWalletClient({
  environmentId: process.env.DYNAMIC_ENVIRONMENT_ID!,
  apiKey: process.env.DYNAMIC_API_KEY!,
});

const connection = new Connection(process.env.SOLANA_RPC_URL || 'https://api.devnet.solana.com');

const userId = 'user-uuid';
const recipientAddress = 'RecipientPublicKey';
const credentials = await getDelegationCredentials(userId);
const sender = new PublicKey(credentials.publicKey);

const transaction = new Transaction();
const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash('confirmed');
transaction.recentBlockhash = blockhash;
transaction.lastValidBlockHeight = lastValidBlockHeight;
transaction.feePayer = sender;

transaction.add(
  SystemProgram.transfer({
    fromPubkey: sender,
    toPubkey: new PublicKey(recipientAddress),
    lamports: 1000000,
  })
);

const signedTx = await delegatedSignTransaction(delegatedClient, {
  walletId: credentials.walletId,
  walletApiKey: credentials.walletApiKey,
  keyShare: credentials.keyShare,
  transaction,
  signerAddress: sender.toString(),
  sponsor: true,
  userId,
});

const signature = await connection.sendRawTransaction(signedTx.serialize());
await connection.confirmTransaction({ signature, blockhash, lastValidBlockHeight });
console.log('Sponsored transaction confirmed:', signature);

Complete Transaction Flow

import {
  createDelegatedSvmWalletClient,
  delegatedSignTransaction
} from '@dynamic-labs-wallet/node-svm';
import {
  Transaction,
  SystemProgram,
  PublicKey,
  Connection,
  sendAndConfirmTransaction
} from '@solana/web3.js';

const delegatedClient = createDelegatedSvmWalletClient({
  environmentId: process.env.DYNAMIC_ENVIRONMENT_ID!,
  apiKey: process.env.DYNAMIC_API_KEY!,
});

const connection = new Connection('https://api.mainnet-beta.solana.com');

async function sendPayment(
  userId: string,
  recipientAddress: string,
  amount: number
) {
  const credentials = await getDelegationCredentials(userId);
  const senderAddress = credentials.publicKey;

  const transaction = new Transaction().add(
    SystemProgram.transfer({
      fromPubkey: new PublicKey(senderAddress),
      toPubkey: new PublicKey(recipientAddress),
      lamports: amount,
    })
  );

  const { blockhash } = await connection.getLatestBlockhash();
  transaction.recentBlockhash = blockhash;
  transaction.feePayer = new PublicKey(senderAddress);

  const signedTx = await delegatedSignTransaction(delegatedClient, {
    walletId: credentials.walletId,
    walletApiKey: credentials.walletApiKey,
    keyShare: credentials.keyShare,
    transaction,
  });

  const signature = await connection.sendRawTransaction(
    signedTx.serialize()
  );

  await connection.confirmTransaction(signature);

  console.log('Transaction confirmed:', signature);
  return signature;
}

Versioned Transaction

import { VersionedTransaction, TransactionMessage } from '@solana/web3.js';

const message = new TransactionMessage({
  payerKey: new PublicKey(senderAddress),
  recentBlockhash: (await connection.getLatestBlockhash()).blockhash,
  instructions: [
    SystemProgram.transfer({
      fromPubkey: new PublicKey(senderAddress),
      toPubkey: new PublicKey(recipientAddress),
      lamports: 1000000,
    })
  ],
}).compileToV0Message();

const versionedTx = new VersionedTransaction(message);

const signedTx = await delegatedSignTransaction(delegatedClient, {
  walletId: 'wallet-id-from-webhook',
  walletApiKey: 'wallet-api-key-from-webhook',
  keyShare: keyShareFromWebhook,
  transaction: versionedTx,
});

const signature = await connection.sendTransaction(signedTx);

Type Definitions

type ServerKeyShare = {
  pubkey: {
    pubkey: Uint8Array;
  };
  secretShare: string;
};

Error Handling

The function throws an error if:

• Any required parameter is missing or invalid
• The transaction is malformed
• The delegation credentials are expired or revoked
• The MPC signing operation fails
• Network communication with Dynamic services fails

try {
  const signedTx = await delegatedSignTransaction(delegatedClient, {
    walletId: credentials.walletId,
    walletApiKey: credentials.walletApiKey,
    keyShare: credentials.keyShare,
    transaction,
  });

  const signature = await connection.sendTransaction(signedTx);
  console.log('Transaction sent:', signature);
} catch (error) {
  if (error.message.includes('key share')) {
    console.error('Invalid or expired delegation credentials');
  } else if (error.message.includes('transaction')) {
    console.error('Invalid transaction format');
  } else {
    console.error('Transaction signing failed:', error);
  }
}

Security Considerations

• Transaction Validation: Always validate transaction contents before signing
• Recipient Verification: Verify recipient addresses to prevent sending to wrong addresses
• Amount Validation: Implement checks for transaction amounts to prevent accidental large transfers
• Audit Logging: Log all transaction signing operations for security auditing
• Credential Storage: Never log or expose wallet API keys or key shares
• Rate Limiting: Implement rate limiting to prevent abuse

Common Use Cases

Automated Payments

async function processAutomatedPayment(
  userId: string,
  recipient: string,
  amount: number
) {
  const credentials = await getDelegationCredentials(userId);

  const transaction = new Transaction().add(
    SystemProgram.transfer({
      fromPubkey: new PublicKey(credentials.publicKey),
      toPubkey: new PublicKey(recipient),
      lamports: amount,
    })
  );

  const { blockhash } = await connection.getLatestBlockhash();
  transaction.recentBlockhash = blockhash;
  transaction.feePayer = new PublicKey(credentials.publicKey);

  const signedTx = await delegatedSignTransaction(delegatedClient, {
    walletId: credentials.walletId,
    walletApiKey: credentials.walletApiKey,
    keyShare: credentials.keyShare,
    transaction,
  });

  return await connection.sendTransaction(signedTx);
}

Batch Transactions

async function signMultipleTransactions(
  userId: string,
  transactions: Transaction[]
): Promise<Transaction[]> {
  const credentials = await getDelegationCredentials(userId);

  const signedTransactions = await Promise.all(
    transactions.map(transaction =>
      delegatedSignTransaction(delegatedClient, {
        walletId: credentials.walletId,
        walletApiKey: credentials.walletApiKey,
        keyShare: credentials.keyShare,
        transaction,
      })
    )
  );

  return signedTransactions;
}

Related Functions

• createDelegatedSvmWalletClient() - Create the client for delegated operations
• delegatedSignMessage() - Sign messages instead of transactions
• Sponsor Gas with Delegated Access (SVM) - Full guide on gasless transactions with a separate fee payer