Class AccountApi

constructor

• new AccountApi(config: ApiConfig): AccountApi

  Parameters

  • config: ApiConfig

  Returns AccountApi

ReadonlycurrentAccount

accountBalance

• accountBalance(): Promise<FullBalances>

  Get the account balance of the current account. This method returns the account balance of the current user, including settled, credit, debit, and unclaimed earnings amounts.

  Returns Promise<FullBalances>

  Example: Get the account balance of the current user

  const balance = await sogni.account.accountBalance();
  console.log(balance);
  Copy

createSubscriptionCheckout

• createSubscriptionCheckout(
      planId: SubscriptionPlanId,
      term: SubscriptionTerm,
      options?: CreateSubscriptionCheckoutOptions,
  ): Promise<SubscriptionCheckoutResult>

  Create a Stripe checkout session to subscribe to a plan.

  Returns a url to which the user should be redirected to complete payment. After a successful checkout Stripe will redirect back to your configured return URL and the subscription entitlement will become active.

  Pass options.startTrial to control free-trial behavior: true starts a trial when the account is eligible, while false is sent verbatim to subscribe immediately with no trial even if the account is eligible. Host applications may pass options.deviceId when their integration requires the corresponding server-side context.

  Parameters

  • planId: SubscriptionPlanId

    The plan identifier from getSubscriptionPlans
  • term: SubscriptionTerm

    Billing cadence: 'monthly' or 'annual'
  • options: CreateSubscriptionCheckoutOptions = {}

    Optional checkout metadata, redirect target, and trial controls.

  Returns Promise<SubscriptionCheckoutResult>

  Example

  const { url } = await sogni.account.createSubscriptionCheckout('unlimited', 'monthly');
  window.location.href = url;
  Copy

createSubscriptionPortalSession

• createSubscriptionPortalSession(): Promise<SubscriptionPortalSession>

  Create a Stripe customer portal session for managing an existing subscription.

  Returns a url to which the user should be redirected. The portal lets them update payment methods, cancel, or view invoices.

  Returns Promise<SubscriptionPortalSession>

  Example

  const { url } = await sogni.account.createSubscriptionPortalSession();
  window.location.href = url;
  Copy

deposit

• deposit(
      password: string,
      amount: string | number,
      provider?: string,
  ): Promise<void>

  Deposit tokens from wallet to account

  Parameters

  • password: string

    account password
  • amount: string | number

    amount to transfer
  • provider: string = 'base'

    blockchain provider, 'base' or 'etherlink' defaults to 'base'

  Returns Promise<void>

  Example: withdraw to current wallet address

  await sogni.account.deposit('your-account-password', 100, 'base');
  Copy

getSubscriptionPlans

• getSubscriptionPlans(): Promise<SubscriptionPlan[]>

  Fetch the list of available subscription plans.

  This is a public endpoint; no authentication is required.

  Returns Promise<SubscriptionPlan[]>

  Example

  const plans = await sogni.account.getSubscriptionPlans();
  plans.forEach(p => console.log(p.displayName, p.priceUsd));
  Copy

getSubscriptionStatus

• getSubscriptionStatus(): Promise<SubscriptionEntitlementSnapshot>

  Fetch the current user's subscription entitlement snapshot.

  Returns an object describing whether the account has an effective subscription entitlement, the tier, period boundaries, usage, limits, and enabled capabilities. When no subscription exists, active is false and status is 'none'.

  Also updates currentAccount.subscription so callers can read the snapshot from the observable entity without re-fetching.

  Returns Promise<SubscriptionEntitlementSnapshot>

  Example

  const snap = await sogni.account.getSubscriptionStatus();
  if (snap.active) {
    console.log('Plan:', snap.tier, 'until', snap.currentPeriodEnd);
  }
  Copy

getSubscriptionUsage

• getSubscriptionUsage(): Promise<SubscriptionUsage>

  Fetch the current user's usage for the active billing cycle.

  Returns the render/job counters for the subscriber's current billing cycle (not a calendar month). While the entitlement is 'trialing', the response also carries trialEndsAt, trialCreditsLimit, and trialCreditsUsed so you can render "X of N trial credits used" messaging; those fields are omitted for non-trial subscriptions.

  Note: these trial usage fields come from this endpoint, NOT from getSubscriptionStatus — the entitlement snapshot never carries trial usage.

  Returns Promise<SubscriptionUsage>

  Example

  const usage = await sogni.account.getSubscriptionUsage();
  if (usage.trialCreditsLimit !== undefined) {
    console.log(`${usage.trialCreditsUsed} of ${usage.trialCreditsLimit} trial credits used`);
  }
  Copy

getTrialEligibility

• getTrialEligibility(): Promise<TrialEligibility>

  Check whether the current account is eligible to start a free trial.

  Returns { eligible, reasonCode }. Use eligible as the decision and treat reasonCode as an opaque display hint.

  Returns Promise<TrialEligibility>

  Example

  const { eligible, reasonCode } = await sogni.account.getTrialEligibility();
  if (eligible) {
    const { url } = await sogni.account.createSubscriptionCheckout('unlimited', 'monthly', {
      startTrial: true
    });
  }
  Copy

getWallet

• getWallet(username: string, password: string): Wallet

  Create Ethers.js Wallet instance from username and password. This method is used internally to create a wallet for the user. You can use this method to create a wallet if you need to sign transactions.

  Parameters

  • username: string

    Sogni account username
  • password: string

    Sogni account password

  Returns Wallet

  Example: Create a wallet from username and password

  const wallet = sogni.account.getWallet('username', 'password');
  console.log(wallet.address);
  Copy

login

• login(
      username: string,
      password: string,
      rememberMe?: boolean,
      appSource?: string,
  ): Promise<LoginData>

  Login with username and password. WebSocket connection is established after successful login.

  Parameters

  • username: string
  • password: string
  • rememberMe: boolean = false

    Whether to establish a long-lived session. Default is false. Only applicable for cookie-based authentication.
  • OptionalappSource: string

    Optional client app/source label for login attribution. Defaults to the SogniClient connection appSource when configured.

  Returns Promise<LoginData>

  Example: Login with username and password

  await sogni.account.login('username', 'password');
  console.log('Logged in');
  Copy

logout

• logout(): Promise<void>

  Logout the user and close the WebSocket connection.

  Returns Promise<void>

  Example: Logout the user

  await sogni.account.logout();
  console.log('Logged out');
  Copy

me

• me(): Promise<MeData>

  Returns Promise<MeData>

refreshBalance

• refreshBalance(): Promise<Balances>

  Refresh the balance of the current account.

  Usually, you don't need to call this method manually. Balance is updated automatically through WebSocket events. But you can call this method to force a balance refresh. Note that will also trigger updated event on the current account.

  Returns Promise<Balances>

  Example: Refresh user account balance

  const balance = await sogni.account.refreshBalance();
  console.log(balance);
  Copy

refreshSubscription

• refreshSubscription(): Promise<SubscriptionEntitlementSnapshot>

  Refresh the cached subscription entitlement on currentAccount.

  Convenience wrapper around getSubscriptionStatus that makes the intent ("I want to pull fresh entitlement data into the observable account entity") explicit at the call site.

  Returns Promise<SubscriptionEntitlementSnapshot>

  Example

  await sogni.account.refreshSubscription();
  console.log(sogni.account.currentAccount.isUnlimited);
  Copy

setDeviceId

• setDeviceId(deviceId: string): Promise<void>

  Associate an opaque host-application identifier with the current account. Requires an authenticated session.

  Parameters

  • deviceId: string

    Opaque host-application identifier.

  Returns Promise<void>

  Example

  await sogni.account.setDeviceId(myPersistentDeviceId);
  Copy

switchNetwork

• switchNetwork(network: SupernetType): Promise<SupernetType>

  Switch between fast and relaxed networks. This will change default network used to process projects. After switching, client will receive list of AI models available for on selected network.

  Parameters

  • network: SupernetType

    Network type to switch to

  Returns Promise<SupernetType>

  Example: Switch to the fast network

  await sogni.account.switchNetwork('fast');
  console.log('Switched to the fast network, now lets wait until we get list of models');
  await sogni.projects.waitForModels();
  Copy

transactionHistory

• transactionHistory(
      params: TxHistoryParams,
  ): Promise<{ entries: TxHistoryEntry[]; next: TxHistoryParams }>

  Get the transaction history of the current account.

  Parameters

  • params: TxHistoryParams

    Transaction history query parameters

  Returns Promise<{ entries: TxHistoryEntry[]; next: TxHistoryParams }>

  Transaction history entries and next query parameters

  Example: Get the transaction history

  const { entries, next } = await sogni.account.transactionHistory({
   status: 'completed',
   limit: 10,
   address: sogni.account.currentAccount.walletAddress
  });
  Copy

walletBalance

• walletBalance(
      walletAddress: string,
      provider?: "base" | "etherlink",
  ): Promise<{ ether: string; sogni: string; spark: string }>

  Get the balance of the wallet address.

  This method is used to get the balance of the wallet address. It returns $SOGNI and ETH balance.

  Parameters

  • walletAddress: string
  • provider: "base" | "etherlink" = 'base'

    blockchain provider, 'base' or 'etherlink' defaults to 'base'

  Returns Promise<{ ether: string; sogni: string; spark: string }>

  Example: Get the balance of the wallet address

  const address = sogni.account.currentAccount.walletAddress;
  const balance = await sogni.account.walletBalance(address);
  console.log(balance);
  // { token: '100.000000', ether: '0.000000' }
  Copy

withdraw

• withdraw(
      password: string,
      amount: string | number,
      provider?: string,
  ): Promise<void>

  Withdraw funds from the current account to wallet.

  Parameters

  • password: string

    account password
  • amount: string | number

    amount of tokens to withdraw from account to wallet
  • provider: string = 'base'

    blockchain provider, 'base' or 'etherlink' defaults to 'base'

  Returns Promise<void>

  Example: withdraw to current wallet address

  await sogni.account.withdraw('your-account-password', 100, 'etherlink');
  Copy