> For the complete documentation index, see [llms.txt](https://docs.autonomi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.autonomi.com/developers/sdk/reference/language-bindings/typescript.md). # TypeScript Use the TypeScript client library in your Node.js application to store and retrieve data. It sends requests to a local daemon, a separate background service called **antd** that connects to the Autonomi Network. Follow [Start the Local Daemon](/developers/sdk/how-to-guides/start-the-local-daemon.md) before connecting. This reference covers the typed REST client. ## Install Use Node.js 18 or later. Install [@withautonomi/antd](https://www.npmjs.com/package/@withautonomi/antd), which includes TypeScript declarations, in your application directory: ```bash npm install @withautonomi/antd ``` Installing the client does not install or start antd. Keep the `@withautonomi/` scope: the npm package named `antd` is the unrelated Ant Design library. Examples on this page use `@withautonomi/antd` 0.2 with antd 0.14. If your project does not already have TypeScript tooling, install these development tools to run the examples: ```bash npm install --save-dev @types/node tsx typescript ``` Save each example as `app.ts` and run it with `npx tsx app.ts`. ## Connect to antd With the local service running, `createClient()` uses `http://localhost:8082` with a 300,000-millisecond timeout. ```typescript import { createClient } from "@withautonomi/antd"; async function main(): Promise { const client = createClient(); const health = await client.health(); console.log(`antd version: ${health.version}`); } main().catch((error: unknown) => { console.error(error); process.exitCode = 1; }); ``` A successful run prints: ``` antd version: ``` For a different port, pass `baseUrl` to `createClient`, or use `RestClient.autoDiscover()` as described in the [JavaScript client](/developers/sdk/reference/language-bindings/javascript.md#connect-to-antd). The health result does not include peer counts or `write_ready`; use the [REST health endpoint](/developers/sdk/reference/rest-api.md#health) for those fields. A successful health check is not a guarantee that an upload will succeed. ## Retrieve public data Retrieve a public JPEG without a wallet. This example writes `example.jpg` in your working directory, replacing a file with that name if one exists. ```typescript import { writeFile } from "node:fs/promises"; import { createClient } from "@withautonomi/antd"; async function main(): Promise { const client = createClient(); const data: Buffer = await client.dataGetPublic( "711c7e20006ff3e0ac6c1f3063286a0c1a3e4c409642e8c526173fa60bb7078a", ); await writeFile("example.jpg", data); console.log(`Saved ${data.length} bytes to example.jpg`); } main().catch((error) => { console.error(error); process.exitCode = 1; }); ``` Expected output: ``` Saved 138931 bytes to example.jpg ``` ## Data methods | Method | Input | Return type | | ------------------------ | ----------------------------------------------------- | ------------------------------------------------------------ | | `health()` | None | `Promise` | | `dataGetPublic(address)` | Public address as a 64-character hexadecimal `string` | `Promise` | | `dataGet(dataMap)` | Caller-held DataMap as a hexadecimal `string` | `Promise` | | `dataPutPublic(data)` | `Buffer` | `Promise`; retrieve with its `address` | | `dataPut(data)` | `Buffer` | `Promise`; retain its `dataMap` for retrieval | The retrieval methods above return the complete content in memory. Keep private DataMaps secure: anyone with the DataMap can retrieve the content. ## Type mappings | Autonomi type | TypeScript type | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `HealthStatus` | `{ ok: boolean; network: string; version: string; evmNetwork: string; uptimeSeconds: number; buildCommit: string; paymentTokenAddress: string; paymentVaultAddress: string }` | | `PutResult` | `{ cost: string; address: string }` for chunk writes | | `DataPutPublicResult` | `{ address: string; chunksStored: number; paymentModeUsed: string }` | | `DataPutResult` | `{ dataMap: string; chunksStored: number; paymentModeUsed: string }` | | `FilePutPublicResult` | `{ address: string; storageCostAtto: string; gasCostWei: string; chunksStored: number; paymentModeUsed: string }` | | `FilePutResult` | `{ dataMap: string; storageCostAtto: string; gasCostWei: string; chunksStored: number; paymentModeUsed: string }` | | `PaymentMode` | `"auto"`, `"merkle"`, or `"single"` | | `WalletAddress` | `{ address: string }` | | `WalletBalance` | `{ balance: string; gasBalance: string }` | | `PaymentInfo` | `{ quoteHash: string; rewardsAddress: string; amount: string }` | | `CandidateNodeEntry` | `{ rewardsAddress: string; amount: string }` | | `PoolCommitmentEntry` | `{ poolHash: string; candidates: CandidateNodeEntry[] }` | | `PrepareUploadResult` | object with `uploadId`, `paymentType`, `payments`, `totalAmount`, `paymentVaultAddress`, `paymentTokenAddress`, `rpcUrl`, `totalChunks`, `alreadyStoredCount`, plus optional `depth`, `poolCommitments`, and `merklePaymentTimestamp` for Merkle uploads | | `FinalizeUploadResult` | `{ address: string; chunksStored: number; dataMap: string; dataMapAddress: string }` | | `PrepareChunkResult` | `{ address: string; alreadyStored: boolean; uploadId: string; paymentType: string; payments: PaymentInfo[]; totalAmount: string; paymentVaultAddress: string; paymentTokenAddress: string; rpcUrl: string }` | | `UploadCostEstimate` | `{ cost: string; fileSize: number; chunkCount: number; estimatedGasCostWei: string; paymentMode: string }` | | Raw data | `Buffer` | ## Error handling An address with no stored data rejects with `NotFoundError`, a subclass of `AntdError`. ```typescript import { NotFoundError, createClient } from "@withautonomi/antd"; async function main(): Promise { const client = createClient(); try { await client.dataGetPublic("0".repeat(64)); } catch (error) { if (error instanceof NotFoundError) { console.log("No data is stored at that address"); } else { throw error; } } } main().catch((error) => { console.error(error); process.exit(1); }); ``` Output when the valid address is not stored: ``` No data is stored at that address ``` External-signer finalize methods reject with `PartialUploadError`, a subclass of `NetworkError`, when some chunks remain unstored; it carries `chunksStored`, `chunksFailed`, `totalChunks`, `retryable`, and `retentionKnown`. When `retryable` is `true`, repeating the same finalize call with the same upload ID stores the remainder without paying again; see the [external-signer guide](/developers/sdk/how-to-guides/use-external-signers-for-upload-payments.md) for the other cases. ## Store and retrieve data `dataPutPublic` uploads content and returns a shareable address; `dataPut` returns a private DataMap instead. Both accept an optional `{ paymentMode }` argument, using `"auto"` by default. Follow [Store Data on the Network](/developers/sdk/how-to-guides/store-data-on-the-network.md) for wallet and upload setup. Uploads require a configured wallet and Ethereum Virtual Machine (EVM) payment settings. They can spend funds and publish data permanently. Confirm the intended network, payment contracts, and budget before uploading; a successful health check or retrieval does not establish upload readiness. Use the [local-development setup](/developers/how-to-guides/set-up-a-local-network.md) to assess your integration before committing funds. For an external signer, the client's Merkle prepare/finalize helpers expose a single batch, not the complete multi-batch response and finalization fields. Use the raw [REST external-signer workflow](/developers/sdk/how-to-guides/use-external-signers-for-upload-payments.md) for multi-batch Merkle uploads. ## Full API reference For all available **antd** endpoints, see the [REST API](/developers/sdk/reference/rest-api.md). ## Related pages * [Native Node.js SDK](/developers/sdk/reference/nodejs.md): connect directly without a local service, using a different package and API. * [Native SDKs](/developers/sdk/install/native.md): language options for direct connections.