llms.txt

# antd SDK

> Go, JavaScript/TypeScript, Python, C#, Kotlin, Swift, Ruby, PHP, Dart, Lua, Elixir, Zig, Rust, C++, and Java SDKs for the Autonomi network via the antd daemon. Provides REST and gRPC transports, an MCP server (14 tools), and a local daemon that manages wallet, payments, and network connectivity.

## Quick Start

```python
from antd import AntdClient
client = AntdClient()  # REST on localhost:8082
result = client.data_put_public(b"hello world")
data = client.data_get_public(result.address)
```

## SDKs

- [Go SDK](antd-go/) — `go get github.com/WithAutonomi/ant-sdk/antd-go` — REST + gRPC, context-based (Go 1.21+)
- [JS/TS SDK](antd-js/) — `npm install antd` — REST, async (Node.js 18+)
- [Python SDK](antd-py/) — `pip install antd` — REST + gRPC, sync + async
- [C# SDK](antd-csharp/Antd.Sdk/) — `dotnet add package Antd.Sdk` — REST + gRPC, async
- [Kotlin SDK](antd-kotlin/) — REST + gRPC, coroutine-based async (JDK 17+)
- [Swift SDK](antd-swift/) — REST + gRPC, async/await (Swift 5.9+, macOS only)
- [Ruby SDK](antd-ruby/) — `gem install antd` — REST + gRPC, sync (Ruby 3.0+)
- [PHP SDK](antd-php/) — `composer require autonomi/antd` — REST, sync + async (PHP 8.1+)
- [Dart SDK](antd-dart/) — `dart pub add antd` — REST + gRPC, async (Dart 3.0+)
- [Lua SDK](antd-lua/) — `luarocks install antd` — REST, sync (Lua 5.1+)
- [Elixir SDK](antd-elixir/) — `{:antd, "~> 0.1"}` in mix.exs — REST + gRPC, async (Elixir 1.14+)
- [Zig SDK](antd-zig/) — build.zig.zon dependency — REST, sync (Zig 0.14+)
- [Rust SDK](antd-rust/) — `cargo add antd-client` — REST + gRPC, async/tokio
- [C++ SDK](antd-cpp/) — CMake FetchContent — REST + gRPC, sync + async (C++20)
- [Java SDK](antd-java/) — Gradle/Maven — REST + gRPC, sync + async (Java 17+)
- [MCP Server](antd-mcp/) — 14 tools for AI agent integration

## API Reference

- [OpenAPI Spec](antd/openapi.yaml) — OpenAPI 3.1.0 for REST endpoints
- [Full API Reference](llms-full.txt) — complete endpoint, gRPC, and SDK docs
- [Proto definitions](antd/proto/antd/v1/) — gRPC service definitions

## REST Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/health` | Health check and network status |
| GET | `/v1/data/public/{addr}` | Retrieve public data by address |
| GET | `/v1/data/public/{addr}/stream` | Stream public data by address |
| POST | `/v1/data/public` | Store public data (accepts optional `payment_mode`) |
| GET | `/v1/data/private` | Retrieve private (encrypted) data |
| POST | `/v1/data/private` | Store private (encrypted) data (accepts optional `payment_mode`) |
| POST | `/v1/data/cost` | Estimate data storage cost |
| GET | `/v1/chunks/{addr}` | Get raw chunk by address |
| POST | `/v1/chunks` | Store raw chunk |
| POST | `/v1/files/upload/public` | Upload file to network (accepts optional `payment_mode`) |
| POST | `/v1/files/download/public` | Download file from network |
| POST | `/v1/dirs/upload/public` | Upload directory to network (accepts optional `payment_mode`) |
| POST | `/v1/dirs/download/public` | Download directory from network |
| POST | `/v1/files/cost` | Estimate file upload cost |
| GET | `/v1/wallet/address` | Get wallet public address |
| GET | `/v1/wallet/balance` | Get wallet token and gas balances |
| POST | `/v1/wallet/approve` | Approve wallet to spend tokens on payment contracts |
| POST | `/v1/data/prepare` | Prepare data upload for external signer — returns `payment_type` ("wave_batch" or "merkle") |
| POST | `/v1/upload/prepare` | Prepare file upload for external signer — returns `payment_type` ("wave_batch" or "merkle") |
| POST | `/v1/upload/finalize` | Finalize upload — accepts `tx_hashes` (wave_batch) or `winner_pool_hash` (merkle) |

## gRPC Services

| Service | RPCs | Proto file |
|---------|------|------------|
| HealthService | Check | health.proto |
| DataService | GetPublic, PutPublic, StreamPublic, GetPrivate, PutPrivate, GetCost | data.proto |
| ChunkService | Get, Put | chunks.proto |
| FileService | UploadPublic, DownloadPublic, DirUploadPublic, DirDownloadPublic, GetFileCost | files.proto |
| EventService | Subscribe | events.proto |

## Error Codes

| HTTP | gRPC | Exception | Meaning |
|------|------|-----------|---------|
| 400 | INVALID_ARGUMENT | BadRequestError | Invalid request |
| 402 | FAILED_PRECONDITION | PaymentError | Insufficient funds |
| 404 | NOT_FOUND | NotFoundError | Resource not found |
| 409 | ALREADY_EXISTS / ABORTED | AlreadyExistsError / ForkError | Conflict |
| 413 | RESOURCE_EXHAUSTED | TooLargeError | Payload too large |
| 500 | INTERNAL | InternalError | Server error |
| 502 | UNAVAILABLE | NetworkError | Network unreachable |
| 503 | UNAVAILABLE | ServiceUnavailableError | Wallet not configured |

## Examples

- [Go examples](antd-go/examples/) — 5 runnable examples (01-connect through 05-files)
- [JS/TS examples](antd-js/examples/) — 10 runnable scripts (01-connect.ts through 10-private-data.ts)
- [Python examples](antd-py/examples/) — 10 runnable scripts (01_connect.py through 10_private_data.py)
- [C# examples](antd-csharp/Examples/) — 10 examples in a single console app
- [Kotlin examples](antd-kotlin/examples/) — 10 examples in a single app
- [Swift examples](antd-swift/Sources/AntdExamples/) — 10 examples in a single executable
- [Ruby examples](antd-ruby/examples/) — runnable example scripts
- [PHP examples](antd-php/examples/) — runnable example scripts
- [Dart examples](antd-dart/example/) — runnable example scripts
- [Lua examples](antd-lua/examples/) — runnable example scripts
- [Elixir examples](antd-elixir/examples/) — runnable example scripts
- [Zig examples](antd-zig/examples/) — runnable example files
- [Rust examples](antd-rust/examples/) — runnable example files
- [C++ examples](antd-cpp/examples/) — runnable example files
- [Java examples](antd-java/examples/) — runnable example files

## Port Discovery

All SDKs support automatic daemon discovery via a `daemon.port` file written by antd on startup. Every SDK provides an auto-discover constructor:

```python
client, url = RestClient.auto_discover()           # Python
```
```go
client, url := antd.NewClientAutoDiscover()        // Go
```
```typescript
const { client, url } = RestClient.autoDiscover(); // TypeScript
```

Port file locations: `%APPDATA%\ant\daemon.port` (Windows), `~/.local/share/ant/daemon.port` (Linux), `~/Library/Application Support/ant/daemon.port` (macOS). File format: two lines — REST port, gRPC port.

## Default Ports (fallback when no port file)

- REST: `http://localhost:8082`
- gRPC: `localhost:50051`

## Payment Modes

All data and file PUT/upload endpoints accept an optional `payment_mode` field in the request body:

| Mode | Behavior |
|------|----------|
| `"auto"` (default) | Uses merkle batch payments for 64+ chunks, single payments otherwise |
| `"merkle"` | Forces merkle batch payments regardless of chunk count (minimum 2 chunks). Saves gas on larger uploads |
| `"single"` | Forces per-chunk payments. Useful for small data or debugging |

REST example: `POST /v1/data/public` with `{"data": "<base64>", "payment_mode": "merkle"}`

All SDK `*_put_public`, `*_put_private`, `file_upload_public`, and `dir_upload_public` methods accept a `payment_mode` parameter (defaults to `"auto"`).