REST API

This page describes the REST surface exposed by antd. By default, the daemon listens on http://localhost:8082.

All current REST payloads are JSON. When you send or receive binary data, the bytes are base64-encoded inside a data field.

Health

Health Check

Endpoint: GET /health

Returns daemon health and the selected network.

Response:

{
  "status": "ok",
  "network": "default",
  "version": "0.6.1",
  "evm_network": "arbitrum-one",
  "uptime_seconds": 12345,
  "build_commit": "529280c3",
  "payment_token_address": "0xde817De9d8AC8C3aA10C3Ed0EE5FCB6C53cE7B0a",
  "payment_vault_address": "0x607483B50C5F06c25cDC316b6d1E071084EeC9f5"
}

All six fields (version, evm_network, uptime_seconds, build_commit, payment_token_address, payment_vault_address) are always present. On a local devnet, payment_token_address and payment_vault_address may be empty strings, and build_commit is empty when the binary was built outside a git checkout.

Example:

curl http://localhost:8082/health

Data

Store Public Data

Endpoint: POST /v1/data/public

Stores public data and returns the public address that can be shared with readers.

Parameters:

Name	Type	Required	Description
data	string	Yes	Base64-encoded payload
payment_mode	string	No	auto, merkle, or single

Response:

{
  "address": "<64_hex_address>",
  "chunks_stored": <chunk_count>,
  "payment_mode_used": "auto"
}

Example:

DATA_B64=$(printf 'Hello, Autonomi!' | base64)

curl -X POST http://localhost:8082/v1/data/public \
  -H "Content-Type: application/json" \
  -d "{\"data\":\"$DATA_B64\"}"

Get Public Data

Endpoint: GET /v1/data/public/{addr}

Fetches public data by address.

Parameters:

Name	Type	Required	Description
addr	path	Yes	64-character hex data address

Response:

{
  "data": "SGVsbG8sIEF1dG9ub21pIQ=="
}

Example:

curl http://localhost:8082/v1/data/public/<addr>

Stream Public Data

Endpoint: GET /v1/data/public/{addr}/stream

Streams a public object by address with constant memory, decrypting one batch at a time instead of buffering the whole object into a JSON body. Use this for large objects.

The response framing depends on the Accept header:

• Default (any Accept other than application/x-ndjson): a raw application/octet-stream body of the decrypted plaintext. The Content-Length header is set from the object's original size, so a client detects a failed download as a short read.

• Accept: application/x-ndjson: newline-delimited JSON (NDJSON) frames, one JSON object per line, so the caller can drive a determinate progress bar. A leading {"type":"meta","total_size":<bytes>} frame is followed by interleaved {"type":"progress",...} and {"type":"data","chunk":"<base64>"} frames, and a terminal {"type":"error","message":"..."} frame if the download fails partway. Each progress frame carries phase ("resolving_map", "resolved", or "fetching"), fetched (chunks fetched so far), and total (chunks for the phase, or 0 while still unknown).

Parameters:

Name	Type	Required	Description
addr	path	Yes	64-character hex data address

Example:

# Raw bytes
curl http://localhost:8082/v1/data/public/<addr>/stream -o object.bin

# Progress framing
curl -H "Accept: application/x-ndjson" \
  http://localhost:8082/v1/data/public/<addr>/stream

Store Private Data

Endpoint: POST /v1/data

Stores private data. The DataMap is returned to the caller and is not stored on-network.

Parameters:

Name	Type	Required	Description
data	string	Yes	Base64-encoded payload
payment_mode	string	No	auto, merkle, or single

Response:

{
  "data_map": "<hex_encoded_datamap>",
  "chunks_stored": <chunk_count>,
  "payment_mode_used": "auto"
}

Example:

DATA_B64=$(printf 'Secret message' | base64)

curl -X POST http://localhost:8082/v1/data \
  -H "Content-Type: application/json" \
  -d "{\"data\":\"$DATA_B64\"}"

Get Private Data

Endpoint: POST /v1/data/get

Retrieves private data using a caller-held DataMap. Uses POST so the hex-encoded DataMap (which can be many KB) goes in the request body rather than a URL query string.

Parameters:

Name	Type	Required	Description
data_map	string	Yes	Hex-encoded serialized DataMap

Response:

{
  "data": "U2VjcmV0IG1lc3NhZ2U="
}

Example:

curl -X POST http://localhost:8082/v1/data/get \
  -H "Content-Type: application/json" \
  -d '{"data_map":"<hex_encoded_datamap>"}'

Estimate Data Cost

Endpoint: POST /v1/data/cost

Estimates the storage cost for a data payload without uploading it.

Parameters:

Name	Type	Required	Description
data	string	Yes	Base64-encoded payload
payment_mode	string	No	auto, merkle, or single

Response:

{
  "cost": "<atto_token_amount>",
  "file_size": <bytes>,
  "chunk_count": <chunk_count>,
  "estimated_gas_cost_wei": "<wei_amount>",
  "payment_mode": "auto"
}

Example:

DATA_B64=$(printf 'Hello, Autonomi!' | base64)

curl -X POST http://localhost:8082/v1/data/cost \
  -H "Content-Type: application/json" \
  -d "{\"data\":\"$DATA_B64\"}"

Chunks

Store a Chunk

Endpoint: POST /v1/chunks

Stores a raw chunk.

Parameters:

Name	Type	Required	Description
data	string	Yes	Base64-encoded chunk bytes

Response:

{
  "cost": "<atto_token_amount>",
  "address": "<64_hex_address>"
}

Example:

CHUNK_B64=$(printf 'chunk bytes' | base64)

curl -X POST http://localhost:8082/v1/chunks \
  -H "Content-Type: application/json" \
  -d "{\"data\":\"$CHUNK_B64\"}"

Get a Chunk

Endpoint: GET /v1/chunks/{addr}

Retrieves a raw chunk by address.

Parameters:

Name	Type	Required	Description
addr	path	Yes	64-character hex chunk address

Response:

{
  "data": "Y2h1bmsgYnl0ZXM="
}

Example:

curl http://localhost:8082/v1/chunks/<addr>

Prepare a Single-Chunk Upload

Endpoint: POST /v1/chunks/prepare

Prepares one raw chunk for the external-signer flow. The daemon computes the chunk address, checks whether the chunk is already stored, and returns either the existing address or the payment details needed before finalizing.

Parameters:

Name	Type	Required	Description
data	string	Yes	Base64-encoded raw chunk bytes

Response:

When the chunk already exists on-network:

{
  "address": "<64_hex_address>",
  "already_stored": true
}

When payment is required:

{
  "address": "<64_hex_address>",
  "already_stored": false,
  "upload_id": "<hex_id>",
  "payment_type": "wave_batch",
  "payments": [
    {
      "quote_hash": "0x...",
      "rewards_address": "0x...",
      "amount": "<atto_token_amount>"
    }
  ],
  "total_amount": "<atto_token_amount>",
  "payment_vault_address": "0x...",
  "payment_token_address": "0x...",
  "rpc_url": "http://127.0.0.1:8545"
}

Example:

CHUNK_B64=$(printf 'chunk bytes' | base64)

curl -X POST http://localhost:8082/v1/chunks/prepare \
  -H "Content-Type: application/json" \
  -d "{\"data\":\"$CHUNK_B64\"}"

Finalize a Single-Chunk Upload

Endpoint: POST /v1/chunks/finalize

Stores a chunk prepared by POST /v1/chunks/prepare after the external signer has submitted the matching payment transaction.

Parameters:

Name	Type	Required	Description
upload_id	string	Yes	Value returned by POST /v1/chunks/prepare
tx_hashes	object	Yes	Map of quote_hash to the transaction hash returned by the external payment

Response:

{
  "address": "<64_hex_address>"
}

Example:

curl -X POST http://localhost:8082/v1/chunks/finalize \
  -H "Content-Type: application/json" \
  -d '{"upload_id":"<hex_id>","tx_hashes":{"0xquote":"0xtx"}}'

Files

These endpoints work on paths visible to the machine running antd.

Upload a Public File

Endpoint: POST /v1/files/public

Uploads a local file publicly. Also stores the DataMap on-network as an additional chunk and returns its network address.

Parameters:

Name	Type	Required	Description
path	string	Yes	Local file path
payment_mode	string	No	auto, merkle, or single

Response:

{
  "address": "<64_hex_address>",
  "storage_cost_atto": "<atto_token_amount>",
  "gas_cost_wei": "<wei_amount>",
  "chunks_stored": 42,
  "payment_mode_used": "auto"
}

Example:

curl -X POST http://localhost:8082/v1/files/public \
  -H "Content-Type: application/json" \
  -d '{"path":"/absolute/path/to/document.pdf"}'

Download a Public File

Endpoint: POST /v1/files/public/get

Downloads a public file using its on-network DataMap address.

Parameters:

Name	Type	Required	Description
address	string	Yes	64-character hex on-network DataMap address
dest_path	string	Yes	Local destination path

Response: HTTP 200 OK with no JSON body

Example:

curl -X POST http://localhost:8082/v1/files/public/get \
  -H "Content-Type: application/json" \
  -d '{"address":"<64_hex_address>","dest_path":"/absolute/path/to/downloaded.pdf"}'

Upload a Private File

Endpoint: POST /v1/files

Uploads a local file privately. The DataMap is returned to the caller and is not stored on-network.

Parameters:

Name	Type	Required	Description
path	string	Yes	Local file path
payment_mode	string	No	auto, merkle, or single

Response:

{
  "data_map": "<hex_encoded_datamap>",
  "storage_cost_atto": "<atto_token_amount>",
  "gas_cost_wei": "<wei_amount>",
  "chunks_stored": 42,
  "payment_mode_used": "auto"
}

Example:

curl -X POST http://localhost:8082/v1/files \
  -H "Content-Type: application/json" \
  -d '{"path":"/absolute/path/to/document.pdf"}'

Download a Private File

Endpoint: POST /v1/files/get

Downloads a file using a caller-held DataMap (no address lookup required).

Parameters:

Name	Type	Required	Description
data_map	string	Yes	Hex-encoded serialized DataMap
dest_path	string	Yes	Local destination path

Response: HTTP 200 OK with no JSON body

Example:

curl -X POST http://localhost:8082/v1/files/get \
  -H "Content-Type: application/json" \
  -d '{"data_map":"<hex_encoded_datamap>","dest_path":"/absolute/path/to/downloaded.pdf"}'

Estimate File Cost

Endpoint: POST /v1/files/cost

Estimates upload cost for a local file.

Parameters:

Name	Type	Required	Description
path	string	Yes	Local file path
is_public	boolean	No	Defaults to true
payment_mode	string	No	auto, merkle, or single

Response:

{
  "cost": "<atto_token_amount>",
  "file_size": <bytes>,
  "chunk_count": <chunk_count>,
  "estimated_gas_cost_wei": "<wei_amount>",
  "payment_mode": "auto"
}

Example:

curl -X POST http://localhost:8082/v1/files/cost \
  -H "Content-Type: application/json" \
  -d '{"path":"/absolute/path/to/document.pdf","is_public":true}'

Wallet

Get Wallet Address

Endpoint: GET /v1/wallet/address

Returns the configured wallet address.

Response:

{
  "address": "0x1234abcd..."
}

Example:

curl http://localhost:8082/v1/wallet/address

Get Wallet Balance

Endpoint: GET /v1/wallet/balance

Returns token and gas balances.

Response:

{
  "balance": "<atto_token_balance>",
  "gas_balance": "<wei_balance>"
}

Example:

curl http://localhost:8082/v1/wallet/balance

Approve Wallet Spend

Endpoint: POST /v1/wallet/approve

Approves token spend for payment contracts.

Parameters: None

Response:

{
  "approved": true
}

Example:

curl -X POST http://localhost:8082/v1/wallet/approve \
  -H "Content-Type: application/json" \
  -d '{}'

External signer flow

Prepare a Data Upload

Endpoint: POST /v1/data/prepare

Prepares an in-memory data upload for external signing.

Parameters:

Name	Type	Required	Description
data	string	Yes	Base64-encoded payload
visibility	string	No	"private" (default) or "public". When "public", the serialized DataMap is bundled into the same external-signer payment batch and published on-network on finalize; data_map_address is then present in the finalize response.

Response:

The response varies by payment_type.

The daemon returns wave_batch for uploads under 64 chunks and merkle for uploads with 64 or more chunks.

{
  "upload_id": "<hex_id>",
  "payment_type": "wave_batch",
  "payments": [
    {
      "quote_hash": "0x...",
      "rewards_address": "0x...",
      "amount": "<atto_token_amount>"
    }
  ],
  "total_amount": "<atto_token_amount>",
  "payment_vault_address": "0x...",
  "payment_token_address": "0x...",
  "rpc_url": "http://127.0.0.1:8545",
  "total_chunks": 12,
  "already_stored_count": 4
}

Merkle variant:

{
  "upload_id": "<hex_id>",
  "payment_type": "merkle",
  "depth": 6,
  "pool_commitments": [
    {
      "pool_hash": "0x...",
      "candidates": [
        {
          "rewards_address": "0x...",
          "amount": "<atto_token_amount>"
        }
      ]
    }
  ],
  "merkle_payment_timestamp": 1744041600,
  "payment_vault_address": "0x...",
  "total_amount": "0",
  "payment_token_address": "0x...",
  "rpc_url": "http://127.0.0.1:8545",
  "total_chunks": 128,
  "already_stored_count": 0
}

Each pool_commitments entry contains exactly 16 candidate payments. The example above shows one candidate for brevity.

Both variants include total_chunks and already_stored_count. total_chunks is the full chunk count for the upload, including chunks already on-network; already_stored_count is how many of those were already stored and so excluded from payment and from the PUT. The external signer pays for total_chunks - already_stored_count chunks, which is why a prepared upload can cost less than the raw file size implies.

Example:

DATA_B64=$(printf 'Hello, Autonomi!' | base64)

curl -X POST http://localhost:8082/v1/data/prepare \
  -H "Content-Type: application/json" \
  -d "{\"data\":\"$DATA_B64\"}"

Prepare a File Upload

Endpoint: POST /v1/upload/prepare

Prepares a file upload for external signing.

Parameters:

Name	Type	Required	Description
path	string	Yes	Local file path
visibility	string	No	"private" (default) or "public". "public" bundles the serialized DataMap chunk into the same payment batch and stores it on-network; its address is returned on finalize via data_map_address.

Response: Same payment_type-based shape as POST /v1/data/prepare

Example:

curl -X POST http://localhost:8082/v1/upload/prepare \
  -H "Content-Type: application/json" \
  -d '{"path":"/absolute/path/to/document.pdf"}'

Finalize an Upload

Endpoint: POST /v1/upload/finalize

Finalizes a prepared upload after the external signer has submitted the matching payment transaction.

Parameters:

Name	Type	Required	Description
upload_id	string	Yes	Value returned by a prepare endpoint
tx_hashes	object	No	Wave-batch only: map of quote_hash to tx_hash
winner_pool_hash	string	No	Merkle only: winner pool hash emitted by MerklePaymentMade
store_data_map	boolean	No	If true, also stores the DataMap on-network

Provide tx_hashes when the prepare response returned payment_type: "wave_batch". Provide winner_pool_hash when it returned payment_type: "merkle".

Response:

{
  "data_map": "<hex_encoded_datamap>",
  "address": "<64_hex_address>",
  "data_map_address": "<64_hex_address>",
  "chunks_stored": <chunk_count>
}

address is only present when store_data_map is true; that path uses the daemon's own wallet to store the DataMap. data_map_address is only present when the upload was prepared with visibility:"public"; it is the network address of the bundled DataMap chunk whose payment was included in the same external-signer batch as the data chunks.

Examples:

curl -X POST http://localhost:8082/v1/upload/finalize \
  -H "Content-Type: application/json" \
  -d '{"upload_id":"<hex_id>","tx_hashes":{"0xquote":"0xtx"},"store_data_map":true}'

curl -X POST http://localhost:8082/v1/upload/finalize \
  -H "Content-Type: application/json" \
  -d '{"upload_id":"<hex_id>","winner_pool_hash":"0x...","store_data_map":true}'

Error codes

Code	Meaning	Resolution
400	Bad request	Check base64 encoding, address length, data map format, and local paths
402	Payment required	Fund the configured wallet or reduce the upload size
404	Not found	Check the address or upload_id
413	Payload too large	Split the upload or switch to file endpoints
500	Internal server error	Check daemon logs and retry
502	Network unreachable	Confirm the daemon can reach the Autonomi network
503	Service unavailable	Configure a wallet before calling wallet or write endpoints

Related pages

• Build with the SDKs

• Start the Local Daemon

• Store Data on the Network

• Store and Retrieve Data with the SDKs