> ## Documentation Index
> Fetch the complete documentation index at: https://docs.socket.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# requestTransaction() — SocketFi Client SDK Method

> Submit a Soroban smart contract transaction through the user's embedded wallet. Opens an approval popup and returns the transaction hash on success.

`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

```typescript theme={null}
requestTransaction(tx: TransactionRequest): Promise<TransactionResult>
```

## Parameters

<ParamField path="tx" type="TransactionRequest" required>
  The transaction request object describing the contract call to execute.

  <Expandable title="TransactionRequest fields">
    <ParamField path="tx.contractId" type="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.
    </ParamField>

    <ParamField path="tx.method" type="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.
    </ParamField>

    <ParamField path="tx.args" type="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.
    </ParamField>
  </Expandable>
</ParamField>

## Return value

`requestTransaction()` returns `Promise<TransactionResult>`.

<ResponseField name="success" type="boolean" required>
  `true` if the transaction was submitted and confirmed on-chain. `false` if submission failed after the user approved.
</ResponseField>

<ResponseField name="transactionHash" type="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.
</ResponseField>

## 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
```

<Note>
  `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.
</Note>

## Examples

### Token transfer

```typescript theme={null}
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

```typescript theme={null}
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

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

### Contract call with no arguments

```typescript theme={null}
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:

```typescript theme={null}
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

```typescript theme={null}
interface TransactionRequest {
  contractId: string;
  method: string;
  args?: unknown[];
}

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