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 before connecting. This reference covers the typed REST client.

Install

Use Node.js 18 or later. Install @withautonomi/antd, which includes TypeScript declarations, in your application directory:

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:

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.

import { createClient } from "@withautonomi/antd";

async function main(): Promise<void> {
  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: <version>

For a different port, pass baseUrl to createClient, or use RestClient.autoDiscover() as described in the JavaScript client. The health result does not include peer counts or write_ready; use the REST health endpoint 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.

import { writeFile } from "node:fs/promises";
import { createClient } from "@withautonomi/antd";

async function main(): Promise<void> {
  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<HealthStatus>
dataGetPublic(address)	Public address as a 64-character hexadecimal string	Promise<Buffer>
dataGet(dataMap)	Caller-held DataMap as a hexadecimal string	Promise<Buffer>
dataPutPublic(data)	Buffer	Promise<DataPutPublicResult>; retrieve with its address
dataPut(data)	Buffer	Promise<DataPutResult>; 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.

import { NotFoundError, createClient } from "@withautonomi/antd";

async function main(): Promise<void> {
  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 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 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 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 for multi-batch Merkle uploads.

Full API reference

For all available antd endpoints, see the REST API.

Related pages

• Native Node.js SDK: connect directly without a local service, using a different package and API.

• Native SDKs: language options for direct connections.