JavaScript

Use the JavaScript 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 REST client.

Install

Use Node.js 18 or later. Install @withautonomi/antd 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. Save each example as app.mjs and run it with node app.mjs.

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() {
  const client = createClient();
  const health = await client.health();
  console.log(`antd version: ${health.version}`);
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

A successful run prints:

antd version: <version>

For a different port, pass baseUrl to createClient. Alternatively, import RestClient from the package and call RestClient.autoDiscover() to read antd's port file. It returns { client, url }; an empty url means the client uses the default URL. 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() {
  const client = createClient();
  const data = 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

All methods below return promises.

Method	Input	Result
health()	None	HealthStatus
dataGetPublic(address)	Public address as a 64-character hexadecimal string	Buffer
dataGet(dataMap)	Caller-held DataMap as a hexadecimal string	Buffer
dataPutPublic(data)	Buffer	DataPutPublicResult; retrieve with its address
dataPut(data)	Buffer	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	JavaScript type
HealthStatus	object with ok, network, version, evmNetwork, uptimeSeconds, buildCommit, paymentTokenAddress, and paymentVaultAddress
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	string values: 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() {
  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.