# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://atoma.gitbook.io/atoma-docs/node-operators/atoma-node/atoma-node-daemon.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.