> For the complete documentation index, see [llms.txt](https://atoma.gitbook.io/atoma-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atoma.gitbook.io/atoma-docs/node-operators/atoma-node/atoma-node-daemon.md).

# Atoma node daemon

## Atoma Daemon API Documentation

The Atoma daemon provides a REST API for querying node state and submitting blockchain transactions. The daemon manages node operations, subscriptions, tasks, stacks, and attestation disputes.

### Base URL

All API endpoints are relative to the daemon's base URL (e.g., `http://localhost:3000`).

### Authentication

Currently, no authentication is required to access the API endpoints, as the Atoma daemon is supposed to be a standalone local service for ease of node operations.

### Response Format

All responses are returned in JSON format. Successful responses will contain the requested data, while errors will return appropriate HTTP status codes with error messages.

####

#### Claimed Stack Management

**Get All Claimed Stacks**

```
GET /claimed_stacks
```

Returns all claimed stacks for registered nodes.

**Get Node Claimed Stacks**

```
GET /claimed_stacks/:id
```

Returns claimed stacks for a specific node.

**Parameters**

* `id` (path): Node small ID

#### Transaction Submission Endpoints

**Register Node**

```
POST /register
```

Submits a node registration transaction.

**Request Body**

```json
{
  "gas": "0x123",
  "gas_budget": 1000,
  "gas_price": 10
}
```

**Subscribe to Model**

```
POST /model_subscribe
```

Subscribes a node to a specific model.

**Request Body**

```json
{
  "model_name": "example_model",
  "echelon_id": 1,
  "node_badge_id": "0x123",
  "gas": "0x456",
  "gas_budget": 1000,
  "gas_price": 10
}
```

**Subscribe to Task**

```
POST /task_subscribe
```

Subscribes a node to a specific task.

**Request Body**

```json
{
  "task_small_id": 123,
  "node_small_id": 456,
  "price_per_compute_unit": 10,
  "max_num_compute_units": 100,
  "gas": "0x789",
  "gas_budget": 1000,
  "gas_price": 10
}
```

**Unsubscribe from Task**

```
POST /task_unsubscribe
```

Unsubscribes a node from a specific task.

**Request Body**

```json
{
  "task_small_id": 123,
  "node_small_id": 456,
  "gas": "0x789",
  "gas_budget": 1000,
  "gas_price": 10
}
```

**Try Settle Stacks**

```
POST /try_settle_stack_ids
```

Attempts to settle specified stacks.

**Request Body**

```json
{
  "stack_small_ids": [123, 456],
  "num_claimed_compute_units": 50,
  "node_small_id": 789,
  "gas": "0x789",
  "gas_budget": 1000,
  "gas_price": 10
}
```

**Submit Stack Settlement Attestations**

```
POST /submit_stack_settlement_attestations
```

Submits attestations for stack settlement.

**Request Body**

```json
{
  "stack_small_ids": [123, 456],
  "node_small_id": 789,
  "gas": "0x789",
  "gas_budget": 1000,
  "gas_price": 10
}
```

**Claim Funds**

```
POST /claim_funds
```

Claims funds from completed stacks.

**Request Body**

```json
{
  "stack_small_ids": [123, 456],
  "node_small_id": 789,
  "gas": "0x789",
  "gas_budget": 1000,
  "gas_price": 10
}
```

### Error Handling

The API uses standard HTTP status codes:

* `200 OK`: Request successful
* `404 Not Found`: Resource not found
* `500 Internal Server Error`: Server-side error occurred

Error responses include a message describing the error:

```json
{
  "error": "Failed to submit transaction"
}
```

### Common Parameters

Many transaction submission endpoints share common parameters:

* `gas`: Gas object ID for transaction fee payment
* `gas_budget`: Maximum gas units allowed for transaction
* `gas_price`: Price per gas unit
* `node_small_id`: Optional node identifier (if not provided, applies to all registered nodes)

### Notes

1. All transaction submission endpoints return a transaction digest that can be used to track the transaction status on the blockchain.
2. When working with stack settlement attestations, note that the attestation node index is offset by 1 since the 0th index is reserved for the original selected node.
3. The daemon maintains thread-safe access to shared resources through the use of `Arc<RwLock>` for the Sui client.
4. All endpoints are instrumented with tracing for debugging and monitoring purposes.