requestTransaction() — SocketFi Client SDK Method

requestTransaction() lets your application invoke a Soroban smart contract method on behalf of the authenticated user. When you call it, the SDK opens a hosted popup where the user can review the transaction details and approve or reject it. If the user approves, the SocketFi platform signs and submits the transaction using the user’s embedded Stellar wallet and returns a TransactionResult containing the transaction hash. Your application never has direct access to the user’s private key.

Method signature

requestTransaction(tx: TransactionRequest): Promise<TransactionResult>

Parameters

TransactionRequest

required

The transaction request object describing the contract call to execute.

Show TransactionRequest fields

string

required

The Soroban contract address on the Stellar network (e.g. "CBXXXXXX..."). This must be a deployed contract on the network you configured when constructing the SocketFi instance.

string

required

The name of the contract function to invoke (e.g. "transfer", "stake", "mint"). This must match the function name as defined in the contract’s ABI.

unknown[]

An optional array of arguments to pass to the contract function, in the order the function expects them. Argument types must be compatible with Soroban’s type system. Omit this field if the function takes no arguments.

Return value

requestTransaction() returns Promise<TransactionResult>.

boolean

required

true if the transaction was submitted and confirmed on-chain. false if submission failed after the user approved.

string

The Stellar transaction hash (XDR transaction ID) for the submitted transaction. Present when success is true. Use this to look up the transaction in a Stellar block explorer or to confirm finality in your backend.

What happens during a transaction request

requestTransaction() called
         ↓
  Transaction approval popup opens
         ↓
  User reviews contract, method, and args
         ↓
  User approves (or rejects) the transaction
         ↓
  SocketFi signs the transaction with the user's wallet key
         ↓
  Transaction submitted to Stellar network
         ↓
  TransactionResult returned

requestTransaction() requires an active session. If the user has not yet authenticated, call authenticate() first to obtain a session. Attempting a transaction without a valid session will throw a TOKEN_EXPIRED or INVALID_TOKEN error.

Examples

Token transfer

import { socketfi } from '@/lib/socketfi';

const result = await socketfi.requestTransaction({
  contractId: 'CBTOKEN_CONTRACT_ADDRESS_HERE',
  method: 'transfer',
  args: [
    'GDESTINATION_ADDRESS_HERE', // recipient
    '1000000',                   // amount in stroops
  ],
});

if (result.success) {
  console.log('Transfer confirmed:', result.transactionHash);
}

Staking

const result = await socketfi.requestTransaction({
  contractId: 'CBSTAKING_CONTRACT_ADDRESS_HERE',
  method: 'stake',
  args: ['5000000'], // amount to stake
});

if (result.success) {
  console.log('Staked successfully. Tx:', result.transactionHash);
}

General contract call

const result = await socketfi.requestTransaction({
  contractId: 'CBMY_CONTRACT_ADDRESS_HERE',
  method: 'register_user',
  args: [userId, referralCode],
});

Contract call with no arguments

const result = await socketfi.requestTransaction({
  contractId: 'CBMY_CONTRACT_ADDRESS_HERE',
  method: 'claim_rewards',
  // args can be omitted when the function takes no parameters
});

Error handling

Always handle errors from requestTransaction(), especially TRANSACTION_REJECTED and USER_CANCELLED, which indicate intentional user actions rather than application faults:

import { socketfi } from '@/lib/socketfi';
import type { SocketFiError } from '@socketfi/react';

async function executeTransfer(recipient: string, amount: string) {
  try {
    const result = await socketfi.requestTransaction({
      contractId: process.env.NEXT_PUBLIC_TOKEN_CONTRACT!,
      method: 'transfer',
      args: [recipient, amount],
    });

    if (result.success) {
      return { ok: true, hash: result.transactionHash };
    }

    // success: false means submission failed after approval
    return { ok: false, error: 'Transaction submission failed' };
  } catch (err) {
    const error = err as SocketFiError;

    switch (error.code) {
      case 'USER_CANCELLED':
        // User closed the popup — not an application error
        return { ok: false, cancelled: true };

      case 'TRANSACTION_REJECTED':
        // User saw the transaction details and chose to reject
        return { ok: false, error: 'Transaction rejected by user' };

      case 'TOKEN_EXPIRED':
        // Session has expired — re-authenticate
        await socketfi.authenticate();
        return executeTransfer(recipient, amount); // retry

      default:
        console.error(`Unexpected error: [${error.code}] ${error.message}`);
        return { ok: false, error: error.message };
    }
  }
}

TypeScript interfaces

interface TransactionRequest {
  contractId: string;
  method: string;
  args?: unknown[];
}

interface TransactionResult {
  success: boolean;
  transactionHash?: string;
}

React SDK

React Native SDK

Server SDK

API Reference

requestTransaction() — SocketFi Client SDK Method

Method signature

Parameters

Return value

What happens during a transaction request

Examples

Token transfer

Staking

General contract call

Contract call with no arguments

Error handling

TypeScript interfaces

​Method signature

​Parameters

​Return value

​What happens during a transaction request

​Examples

​Token transfer

​Staking

​General contract call

​Contract call with no arguments

​Error handling

​TypeScript interfaces

Method signature

Parameters

Return value

What happens during a transaction request

Examples

Token transfer

Staking

General contract call

Contract call with no arguments

Error handling

TypeScript interfaces