Skip to main content

Sessions

Sessions provide time-limited authorization for SDK operations without requiring repeated signatures.

What is a Session?

A session is an authorization token that allows the SDK to execute transactions on behalf of the user for a limited time.
const { activeSession } = await sdk.setup();

console.log('Session key:', activeSession.sessionKeyAddress);
console.log('Valid until:', new Date(activeSession.validUntil * 1000));
console.log('Scope:', activeSession.scope);

Session Properties

PropertyTypeDescription
sessionKeyAddressstringAddress of the session key
validUntilnumberUnix timestamp of expiry
scopeSessionScopePermission level
authorizationSignaturestringAuthorization proof

Session Scopes

Sessions have different permission levels:
import { SessionScope } from '@satsterminal-sdk/borrow';

SessionScope.READ   // Read-only operations
SessionScope.DEFI   // DeFi operations (borrow, repay)
SessionScope.FULL   // All operations

Scope Permissions

ScopeRead DataBorrowRepayWithdrawAdmin
READ
DEFI
FULL
The SDK uses DEFI scope by default.

Session Lifecycle

1. Creation

Sessions are created during setup():
const { activeSession } = await sdk.setup();
// Session is now active

2. Usage

The SDK automatically uses the session for subsequent operations:
// These use the active session
await sdk.getLoan({ ... });
await sdk.repay(loanId, amount);
await sdk.getLoanHistory();

3. Expiration

Sessions expire after the configured validity period:
const sdk = new BorrowSDK({
  // ...
  sessionValiditySeconds: 259200 // 3 days (default)
});

4. Renewal

Create a new session by calling setup() again:
// Check if session is expired
if (Date.now() / 1000 > activeSession.validUntil) {
  await sdk.setup(); // Creates new session
}

Checking Session Status

Via User Status

const { userStatus } = await sdk.setup();

console.log('Has session:', userStatus.hasActiveSession);
console.log('Expires:', new Date(userStatus.sessionExpiry! * 1000));

Manual Check

function isSessionValid(session: ActiveSession): boolean {
  return Date.now() / 1000 < session.validUntil;
}

Session Configuration

Validity Duration

const sdk = new BorrowSDK({
  // ...
  sessionValiditySeconds: 86400 // 24 hours
});
DurationSecondsUse Case
1 hour3600High security
24 hours86400Daily usage
3 days259200Default, convenience
7 days604800Infrequent usage

Minimum Duration

Sessions must be at least 60 seconds:
sessionValiditySeconds: 60 // Minimum allowed

Session Flow Diagram

Clearing Sessions

Clear Current Session

sdk.clearSession();
This clears:
  • Active session
  • Cached signatures
  • User status
  • Stops workflow tracking

When to Clear

  • User logs out
  • User disconnects wallet
  • Security concern
  • Switching accounts

Session Errors

Expired Session

try {
  await sdk.getLoan({ ... });
} catch (error) {
  if (error.message.includes('session expired')) {
    await sdk.setup(); // Refresh session
    await sdk.getLoan({ ... }); // Retry
  }
}

No Active Session

try {
  await sdk.executeBorrow(quote);
} catch (error) {
  if (error instanceof SmartAccountError) {
    // Likely no active session
    await sdk.setup();
  }
}

Best Practices

1. Check Session Before Operations

async function ensureSession(sdk: BorrowSDK) {
  if (!sdk.userStatus.hasActiveSession ||
      Date.now() / 1000 > (sdk.userStatus.sessionExpiry || 0)) {
    await sdk.setup();
  }
}

2. Handle Session Expiry Gracefully

async function safeOperation<T>(
  sdk: BorrowSDK,
  operation: () => Promise<T>
): Promise<T> {
  try {
    return await operation();
  } catch (error) {
    if (isSessionError(error)) {
      await sdk.setup();
      return await operation();
    }
    throw error;
  }
}

3. Clear on Disconnect

function onWalletDisconnect() {
  sdk.clearSession();
}

4. Appropriate Validity Duration

Choose based on your use case:
  • Web app - 24 hours to 3 days
  • Mobile app - 7 days
  • Script/automation - 1 hour