# stacks

> Typed Stacks client for TypeScript. By secondlayer.

## Docs

- [Getting started](/getting-started): Install `@secondlayer/stacks` and create a client against a Stacks network.
- [Accounts](/reference/accounts): Key derivation and account creation for signing transactions.
- [Actions](/reference/actions): Standalone action functions for tree-shakeable imports. These are the same functions available on clients, but usable without a client instance.
- [Bitcoin SPV](/reference/bitcoin): Trust-minimized Bitcoin verification for Stacks contracts (SIP-044): build an inclusion proof from your own node, encode it for Clarity, and prove a payment was mined without trusting a third party.
- [BNS v2](/reference/bns): BNS (Bitcoin Name System) v2 extension for name resolution, registration, and management on Stacks.
- [Chains](/reference/chains): Chain definitions for Stacks networks.
- [Clarity](/reference/clarity): Clarity value constructors, serialization, and ABI type system.
- [connect/walletconnect](/reference/connect-walletconnect): Native WalletConnect v2 for Stacks. Separate entry so it tree-shakes when unused.
- [Connect](/reference/connect): Browser wallet connection via SIP-030 (Leather, Xverse, etc.).
- [Filters](/reference/filters): Describe a chain event once, then hand the same filter to Index, Streams, Webhooks, or Subgraphs.
- [Post-Conditions](/reference/postconditions): Fluent builder for Stacks post-conditions. Protects users by asserting expected asset transfers.
- [PoX Stacking](/reference/pox): PoX (Proof of Transfer) extension for STX stacking — earn Bitcoin rewards by locking STX.
- [PoX-5 Bitcoin Staking](/reference/pox5): `pox5()` client extension for SIP-045 Bitcoin Staking: activation gating, staker reads, every `pox-5` public function as a typed wallet action, plus the pure helpers the contract's math and scripts depend on.
- [sBTC](/reference/sbtc): `sbtc()` client extension for the sBTC protocol: token reads, signer-set lookups, unit conversion, and the event types the registry emits.
- [Simnet transport](/reference/simnet): Clarinet simnet as a client transport. Same `getContract` / public actions as HTTP, against an in-process VM.
- [StackingDAO](/reference/stackingdao): StackingDAO liquid staking extension. Deposit STX, receive stSTX, earn auto-compounding stacking rewards.
- [Subscriptions](/reference/subscriptions): Real-time WebSocket subscriptions for blocks, mempool, transactions, and balances.
- [Transactions](/reference/transactions): Build, sign, and serialize Stacks transactions (SIP-005).
- [Utils](/reference/utils): Encoding, hashing, address, and unit conversion utilities.
- [Bitcoin addresses from the same mnemonic](/guide/bitcoin-addresses): Derive the paired BTC account (what Leather/Xverse show next to your Stacks address) with no extra dependencies — BIP84 native segwit or BIP86 taproot, network-aware:
- [Bitcoin SPV](/guide/bitcoin-spv): Prove a Bitcoin payment happened inside a Stacks contract, with no oracle.
- [Wait for confirmation](/guide/confirmation): `waitForTransactionReceipt` polls until a transaction is mined (optionally N confirmations deep) and returns a normalized receipt with the decoded Clarity result. It rejects with typed errors when the tx aborts (`TransactionAbortedError`, receipt attached), drops from the mempool (`TransactionDroppedError`), or times out — and it re-reads block placement every cycle, so reorgs don't strand the wait.
- [Errors](/guide/errors): The HTTP transport throws a typed `HttpRequestError` (`.status`, `.url`, `.method` attached) on any non-2xx response instead of handing back the error body as if it were a successful result, and it retries `429`s, not just `5xx`/network errors. One `timeout` covers each attempt end to end, headers and body, so a stalled response rejects with `TimeoutError` (`.url`, `.method`, `.timeout`, `.attempt`) instead of hanging. Pass `signal` on any request to cancel from your side; a caller abort is never retried. Broadcasts are sent once (`retryCount: 0`): re-posting a transaction the node may already hold would surface as a nonce conflict, so a timed-out broadcast checks whether the node knows the tx before failing. `MalformedResponseError` throws from `getBalance`, `getAccountInfo`, `getNonce`, `getMapEntry`, `getBlockHeight`, `getBurnBlockHeight`, and `readContract` when the node's response is missing an expected field, instead of failing with an opaque native error (`BigInt(undefined)` and friends). `readContract` (and `getContract().read`) throws `ReadContractError` when the node answers `okay: false`; the message is the node's cause. Both are exported from `@secondlayer/stacks`. Every error carries a stable `code` (`HTTP_REQUEST_ERROR`, `TIMEOUT_ERROR`, `MALFORMED_RESPONSE_ERROR`, `READ_CONTRACT_ERROR`, ...) that also appears in `toJSON()`, so a handler can branch on it without an `instanceof` chain and without parsing a message that may be reworded.
- [Fee tiers](/guide/fees): Every send action takes `fee` as an exact amount **or a named tier**: `'min' | 'low' | 'mid' | 'high'`. Tiers map to the node's three estimations; `'min'` is the minimum relay fee (1 uSTX per serialized byte), computed offline with no round-trip. Omitting `fee` estimates mid. When the node answers `NoEstimateAvailable` (a quiet chain or fresh devnet with no fee history), the SDK falls back to `'min'` instead of failing; `resolveFee` returns `{ fee, tier }` so you can see which happened. Any other estimator failure (timeout, 5xx, auth) throws rather than silently under-paying, and the nonce reserved for that send is handed back.
- [Nonce management](/guide/nonces): Stacks' `/v2/accounts` returns only the confirmed nonce — it ignores the mempool. Broadcasting several transactions from one account before the first confirms makes them reuse the same nonce, so every one after the first is rejected (`ConflictingNonceInMempool`). The usual workaround is tracking nonces by hand.
- [PoX-5 Bitcoin Staking](/guide/pox5): Reading bond prints from your instance is on [PoX-5 events](https://secondlayer.tools/docs/pox5-events). This page is the wallet and proof side, from `@secondlayer/stacks`.
- [Clarinet simnet](/guide/simnet): Same client as HTTP, against an in-process VM (`@stacks/clarinet-sdk` is an optional peer of this entry).
- [Stacks SDK](/guide/transactions): Build, sign, and broadcast Stacks transactions from TypeScript. Where [`@secondlayer/sdk`](https://secondlayer.tools/docs/sdk) reads decoded chain data, `@secondlayer/stacks` writes to the chain.
- [WalletConnect v2](/guide/walletconnect): Native WC v2 implementation — X25519 ECDH, AES-256-GCM envelope encryption, Ed25519 JWT relay auth. Zero cost if you don't import it, tree-shakes completely.