Starkzap SDK

Core SDK powering wallets, tokens, staking, DCA, confidential transfers, Troves vaults, LST, and transaction building

Overview

Starkzap is the core SDK that powers all on-chain interactions in StarkFi. It provides a unified TypeScript API for Starknet — wallet management, token operations, staking, DCA, Troves yield vaults, Endur liquid staking, confidential transfers, gas abstraction, and multicall transaction building.

StarkFi uses Starkzap v3.0.0 as a direct dependency.

How StarkFi Uses Starkzap

Feature	Starkzap API	StarkFi Command
Token Balances	`wallet.balanceOf()`	`balance`, `portfolio`
Token Transfers	`wallet.transfer()`	`send`
Staking	`wallet.stake()`, `wallet.exitPoolIntent()`	`stake`, `unstake`
Rewards	`wallet.claimPoolRewards()`	`rewards --claim / --compound`
DCA	`wallet.dca()`	`dca-create`, `dca-cancel`, `dca-list`, `dca-preview`
Troves	`TxBuilder.trovesDeposit()`, `trovesWithdraw()`	`troves-deposit`, `troves-withdraw`
LST	`wallet.lstStake()`, `lstRedeem()`, `lstExitAll()`	`lst-stake`, `lst-redeem`, `lst-exit-all`
Confidential	`TongoConfidential`	`conf-fund`, `conf-transfer`, `conf-withdraw`, `conf-ragequit`, `conf-rollover`
Wallet Deploy	`wallet.ensureReady()`	`deploy`
Transaction Building	`wallet.tx()` (TxBuilder)	`batch`, `multi-swap`
Gas Abstraction	`feeMode: { type: "paymaster", gasToken }`	`config set-gasfree`

SDK Initialization

import { Starkzap } from "starkzap";

const sdk = new Starkzap({
	network: "mainnet",
	rpcUrl: "https://your-rpc.com", // optional — uses Starkzap preset by default
	paymaster: {
		nodeUrl: "https://starknet.paymaster.avnu.fi",
	},
});

Wallet Connection

StarkFi uses the onboard() API with OnboardStrategy.Privy and the argentXV050 account preset:

import { OnboardStrategy, type WalletInterface } from "starkzap";

const { wallet } = await sdk.onboard({
	strategy: OnboardStrategy.Privy,
	privy: {
		resolve: async () => ({
			walletId: session.walletId,
			publicKey: session.publicKey,
			serverUrl: session.serverUrl,
			headers: { Authorization: `Bearer ${session.token}` },
		}),
	},
	accountPreset: "argentXV050",
	feeMode: { type: "paymaster", gasToken: "0x04718f5a0f...7c938d" },
	deploy: "never",
});

The onboard() API handles signer creation, account class resolution, and fee mode configuration automatically — replacing the manual PrivySigner + connectWallet() pattern from v1. In v3, feeMode uses a discriminated union { type: "paymaster", gasToken: Address } instead of the legacy string "sponsored" format.

Key APIs

Token Operations

wallet.balanceOf(token); // Get token balance (Amount object)
wallet.transfer(token, transfers); // Send tokens to an address
Amount.parse("100", token); // Parse human-readable → Amount
Amount.fromRaw(wei, token); // Create from raw bigint

Staking

wallet.stake(poolAddress, amount); // Stake tokens
wallet.exitPoolIntent(pool, amount); // Begin unstaking (step 1)
wallet.exitPool(pool); // Finalize unstaking (step 2)
wallet.claimPoolRewards(pool); // Claim rewards
wallet.getPoolPosition(pool); // Get position details

TxBuilder (Multicall)

The TxBuilder composes multiple operations into a single atomic Starknet multicall:

const tx = await wallet
	.tx()
	.approve(token, amount, spender)
	.add(calls)
	.stake(poolAddress, amount)
	.send({ feeMode: { type: "paymaster", gasToken } });

StarkFi uses TxBuilder for batch, multi-swap, dca, confidential, lending, and troves operations where multiple calls must execute atomically.

Troves (DeFi Vaults)

// Deposit
const tx = await wallet.tx()
	.trovesDeposit({ strategyId, amount })
	.send({ feeMode });

// Withdraw
const tx = await wallet.tx()
	.trovesWithdraw({ strategyId, amount })
	.send({ feeMode });

Endur LST (Liquid Staking)

// Stake STRK → xSTRK
await wallet.lstStake(amount);

// Redeem xSTRK → STRK
await wallet.lstRedeem(amount);

// Exit entire position
await wallet.lstExitAll();

// Check position
const position = await wallet.getLstPosition();
// { shareBalance, underlyingValue, exchangeRate }

Important: Endur LST yield is embedded in the share price (xSTRK appreciates over time). There are no separate rewards to claim.

Confidential Transfers (Tongo Cash)

import { TongoConfidential, fromAddress } from "starkzap";

// Initialize
const tongo = new TongoConfidential({
	privateKey: tongoKey,
	contractAddress: contractAddr,
	provider: wallet.getProvider(),
});

// State queries
const address = tongo.address;         // Tongo public address
const balance = await tongo.balance(); // { active, pending, nonce }

// Transactional operations (return Call[])
const fundCalls = tongo.fund(amount);            // Fund from public
const transferCalls = tongo.transfer(amount, to); // Private transfer
const withdrawCalls = tongo.withdraw(amount, to); // Withdraw to public
const ragequitCalls = tongo.ragequit(to);         // Emergency exit
const rolloverCalls = tongo.rollover();           // Activate pending

v3 Enhancements

StarkFi leverages key capabilities introduced in Starkzap v3:

Feature	API	What It Does
FeeMode Union	`{ type: "paymaster", gasToken }`	Type-safe gas abstraction replacing legacy string format
Preflight	`builder.sendWithPreflight()`	Simulates the transaction before broadcasting — catches reverts early
Watch	`tx.watch()`	Streams real-time finality updates (`RECEIVED` → `ACCEPTED_ON_L2`)
Quote Health	`quoteHealth()`	Projects health factor impact of a lending action without executing
Troves	`TxBuilder.trovesDeposit()` / `trovesWithdraw()`	Native DeFi vault strategy operations
Endur LST	`wallet.lstStake()` / `lstRedeem()` / `lstExitAll()`	Liquid staking with yield in share price

// Preflight — simulate before sending
const tx = await builder.sendWithPreflight({ feeMode: { type: "paymaster", gasToken } });

// Watch — track transaction finality
for await (const update of tx.watch()) {
	console.log(update.status); // RECEIVED → ACCEPTED_ON_L2
}

// Quote Health — simulate lending impact
const projection = await sdk.quoteHealth({
	pool, collateralToken, debtToken,
	action: "borrow", amount,
});
// projection.currentHealth, projection.projectedHealth

Token Presets

import { getPresets, ChainId } from "starkzap";

const presets = getPresets(ChainId.MAINNET);
const tokens = presets.tokens; // All known tokens with addresses and decimals

Validator Presets

import { mainnetValidators, sepoliaValidators } from "starkzap";

Validator presets provide name-to-staker-address mappings used by the validators and pools commands.