# Multisender SDK

> TypeScript SDK for the Multisender Enterprise API. Batches ERC-20 and native token distributions on EVM chains — the SDK generates transaction calldata that consumers sign and submit themselves. Authenticated via API key, `@multisender.app/multisender-sdk` exposes four services: `catalogs`, `distributions`, `lists`, `project`.

The SDK is generated from an OpenAPI spec using `@hey-api/openapi-ts` and then wrapped by a hand-written service layer that maps HTTP errors to typed error classes (`ApiError`, `NetworkError`, `ValidationError`, `TimeoutError`) and unwraps `{ data: T }` envelopes. All amount fields are strings — decimal precision and `uint256` values cannot be safely represented by JS `number`. For native currency (ETH, POL, BNB, …) pass `0x0000000000000000000000000000000000000000` as `tokenAddress`.

The complete reference lives in `llms-full.txt` — a single self-contained document an LLM can fetch in one request. The links below point to sections inside that file.

## Getting started

- [Installation](llms-full.txt#installation): npm / yarn / bun install instructions and Node.js/browser support
- [Quick start](llms-full.txt#quick-start): minimal working example — create the client, call `distributions.distribute()`, sign and submit calldata
- [Configuration](llms-full.txt#configuration): `MultisenderConfig` — `apiKey`, `baseUrl`, `timeout`, `headers`
- [Authentication](llms-full.txt#authentication): how the SDK applies your API key and how to obtain one
- [Native tokens](llms-full.txt#native-tokens): why the zero address is used for ETH/POL/BNB and how server-side symbol normalization works

## Services

- [CatalogsService](llms-full.txt#catalogsservice): 2 methods — `getChains`, `getChain`
- [DistributionsService](llms-full.txt#distributionsservice): 12 methods — single-step `distribute()` and the two-step flow (`createDraft` → `replaceRecipients` → `prepare` → sign)
- [ListsService](llms-full.txt#listsservice): 14 methods — recipient list CRUD, bulk add/delete recipients, CSV import, recipient validation, `createDistributionList`
- [ProjectService](llms-full.txt#projectservice): 2 methods — `getInfo`, `getMembers`
- [CLI](llms-full.txt#cli): `multisender distribute|lists|distributions` commands

## Types

- [Common types](llms-full.txt#common-types): `PaginationParams`, `PaginatedResponse<T>`, `AddressType`, `TransactionStatus`, `MessageResponse`
- [Distribution types](llms-full.txt#distribution-types): `Distribution`, `DistributeResult`, `DistributionStats`, request DTOs (`CreateDistributeRequest`, `CreateDistributionRequest`, `UpdateDistributionRequest`, `UpdateDistributionRecipientsRequest`, `PrepareDistributionRequest`)
- [Recipient list types](llms-full.txt#recipient-list-types): `RecipientList`, `ListItem`, `Recipient`, `AddRecipientRequest`, `AddRecipientsBulkRequest`, `BulkDeleteRecipientsRequest`, `ValidateDistributionRecipientsRequest`, `CreateDistributionListRequest`, `ImportCsvDistributionRequest`, `ImportFromCsvOptions`
- [Project types](llms-full.txt#project-types): `Project`, `ProjectMember`, `ApiKey`, create/update API key DTOs
- [Catalog types](llms-full.txt#catalog-types): `Chain`, `Token`
- [Approve calldata](llms-full.txt#approve-calldata-types): `ApproveCalldataRequest`, `ApproveCalldata`
- [CSV utility types](llms-full.txt#csv-utility-types): `CsvParseOptions`, `ImportListResponse`, `ImportListFailedRow`, `ImportListFailedReason`

## Errors

- [Error classes](llms-full.txt#error-classes): the full hierarchy under `MultisenderError`
- [Error handling example](llms-full.txt#error-handling): narrow errors with `instanceof` and recover accordingly

## Utilities

- [CSV helpers](llms-full.txt#csv-helpers): `parseCsv`, `toCsv`, `validateCsv`
- [Node entrypoint](llms-full.txt#node-entrypoint): Buffer-based CSV ingest helpers (`importFromCsvBuffer`, `createCsvBlobFromBuffer`) from `@multisender.app/multisender-sdk/node`
- [Validation helpers](llms-full.txt#validation-helpers): address / amount / chainId / token / API key / recipients validators

## Patterns and recipes

- [Distribution lifecycle](llms-full.txt#distribution-lifecycle): state machine from `DRAFT` through `PREPARED → IN_PROGRESS → COMPLETED` or `CANCELLED`
- [Single-step vs two-step flow](llms-full.txt#flows): when to use `distribute()` vs `createDraft()` + `prepare()`
- [ERC-20 approval](llms-full.txt#erc-20-approval): `getApproveCalldata()` / `getApproveCalldataForDistribution()` and when to skip for native tokens
- [Idempotency](llms-full.txt#idempotency): how `idempotencyKey` prevents duplicate distributions on retry
- [Pagination](llms-full.txt#pagination): `PaginationParams` shape, response envelope, `limit` max 100
- [Examples](llms-full.txt#examples): basic Node script, CSV distribution, recipient list management