@stakefish/sdk-starknet

The @stakefish/sdk-starknet is a JavaScript/TypeScript library that provides a unified interface for STRK staking operations on Starknet with stake.fish. It supports preparing stake, unstake, withdraw, and claim rewards transactions, signing with starknet.js, and checking transaction status.

Table of Contents

• Installation
• Configuration
• API Reference
  • stake
  • unstake
  • withdraw
  • claimRewards
  • sign
  • broadcast
  • getTransactionStatus
• Examples
• Important Notes

Installation

npm install @stakefish/sdk-starknet

yarn add @stakefish/sdk-starknet

Configuration

interface StarknetConfig {
  rpcUrl: string; // Starknet RPC URL (required)
}

const starknet = new Starknet({
  rpcUrl: 'https://starknet-mainnet.public.blastapi.io',
});

The SDK is pre-configured for Starknet mainnet (SN_MAIN) and the stake.fish STRK delegation pool.

API Reference

stake

Prepares a stake transaction (approve + enter/add_to_delegation_pool). Amount is in wei (1 STRK = 10^18 wei).

stake(params: { delegatorAddress: string; amount: string }): Promise<StarknetUnsignedTransaction>

unstake

Prepares an unstake intent (exit_delegation_pool_intent). This starts the 21-day unbonding period.

unstake(params: { delegatorAddress: string; amount: string }): Promise<StarknetUnsignedTransaction>

withdraw

Prepares a withdraw transaction (exit_delegation_pool_action). Call this after the unbonding period completes to claim your unstaked STRK.

withdraw(params: { delegatorAddress: string }): Promise<StarknetUnsignedTransaction>

claimRewards

Prepares a claim rewards transaction.

claimRewards(params: { delegatorAddress: string }): Promise<StarknetUnsignedTransaction>

sign

Signs and submits the transaction using starknet.js. Requires network access (for nonce). Returns a payload containing the transaction hash.

sign(privateKey: string, unsignedTx: StarknetUnsignedTransaction): Promise<StarknetSignedTransaction>

• privateKey: Hex string (with or without 0x)
• Returns { signedTransaction: string } (JSON with transaction_hash)

broadcast

Waits for transaction confirmation. The transaction is submitted during sign(). Use this to wait until it is accepted on L2/L1.

broadcast(
  signedTx: StarknetSignedTransaction,
  checkInclusion?: boolean,  // default true
  timeoutMs?: number,        // default 60000
  pollIntervalMs?: number   // default 2000
): Promise<StarknetBroadcastResult>

Returns { txHash: string; status: 'pending' | 'confirmed' }.

getTransactionStatus

Fetches transaction status by hash.

getTransactionStatus(txHash: string): Promise<StarknetTransactionStatus>

Examples

Stake STRK

import { Starknet } from '@stakefish/sdk-starknet';

const starknet = new Starknet({
  rpcUrl: process.env.STARKNET_RPC_URL!,
});

const delegator = process.env.STARKNET_DELEGATOR!;
const privateKey = process.env.STARKNET_PRIVATE_KEY!;

// 100 STRK in wei
const amount = '100000000000000000000';

const unsignedTx = await starknet.stake({ delegatorAddress: delegator, amount });
const signedTx = await starknet.sign(privateKey, unsignedTx);
const result = await starknet.broadcast(signedTx);
console.log('Tx hash:', result.txHash, 'Status:', result.status);

Unstake and withdraw (two-step flow)

Unstaking starts a 21-day unbonding period. After it completes, call withdraw.

// Step 1: Start unbonding
const unstakeTx = await starknet.unstake({
  delegatorAddress: delegator,
  amount: '50000000000000000000', // 50 STRK
});
const signedUnstake = await starknet.sign(privateKey, unstakeTx);
await starknet.broadcast(signedUnstake);

// Step 2: After 7 days, withdraw
const withdrawTx = await starknet.withdraw({ delegatorAddress: delegator });
const signedWithdraw = await starknet.sign(privateKey, withdrawTx);
await starknet.broadcast(signedWithdraw);

Claim rewards

const claimTx = await starknet.claimRewards({ delegatorAddress: delegator });
const signedClaim = await starknet.sign(privateKey, claimTx);
await starknet.broadcast(signedClaim);

Check transaction status

const status = await starknet.getTransactionStatus(txHash);
console.log(status.status); // 'pending' | 'confirmed' | 'failed'

Important Notes

• 21-day unbonding: Unstake (exit_delegation_pool_intent) starts a 21-day unbonding period. Tokens are only claimable via withdraw (exit_delegation_pool_action) after that period.
• Amounts in wei: All amounts use the smallest unit (1 STRK = 10^18 wei). Minimum stake is typically 100 STRK.
• Address format: Delegator addresses must be valid Starknet addresses (0x + hex, 1–64 chars).
• Sign submits: sign() uses starknet.js Account.execute() and therefore signs and submits in one step. broadcast() then waits for confirmation.
• Account abstraction: Transactions are signed by the user's wallet; the SDK uses starknet.js for signing and submission.