Overview

Atoma

Welcome to Atoma - The Decentralized Private AI Network

Describes Atoma's compute AI cloud for private and verifiable AI

Compute Layer

Trust and Privacy

A brief overview of Atoma's architecture for a scalable and secure decentralized AI network

Atoma Architecture Overview

Quickstart

Learn how to use Atoma's Cloud API for AI inference

Get Started

This function processes completion requests by using the chat completions endpoint.

## Returns

Returns a Response containing either:
- A streaming SSE connection for real-time completions
- A single JSON response for non-streaming completions

## Errors

Returns an error status code if:
- The request processing fails
- The streaming/non-streaming handlers encounter errors
- The underlying inference service returns an error

Create completions

This handler processes completions requests in a confidential manner, providing additional
encryption and security measures for sensitive data processing. It supports both streaming and
non-streaming responses while maintaining data confidentiality through AEAD encryption and TEE hardware,
for full private AI compute.

## Returns

Returns a `Result` containing either:
* An HTTP response with the completions result
* A streaming SSE connection for real-time completions
* An `AtomaProxyError` error if the request processing fails

## Errors

Returns `AtomaProxyError::InvalidBody` if:
* The 'stream' field is missing or invalid in the payload

Returns `AtomaProxyError::InternalError` if:
* The inference service request fails
* Response processing encounters errors
* State manager updates fail

## Security Features

* Utilizes AEAD encryption for request/response data
* Supports TEE (Trusted Execution Environment) processing
* Implements secure key exchange using X25519
* Maintains confidentiality throughout the request lifecycle

Create confidential completions

This function processes chat completion requests by determining whether to use streaming
or non-streaming response handling based on the request payload. For streaming requests,
it configures additional options to track token usage.

## Returns

Returns a Response containing either:
- A streaming SSE connection for real-time completions
- A single JSON response for non-streaming completions

## Errors

Returns an error status code if:
- The request processing fails
- The streaming/non-streaming handlers encounter errors
- The underlying inference service returns an error

Create chat completions

This handler processes chat completion requests in a confidential manner, providing additional
encryption and security measures for sensitive data processing. It supports both streaming and
non-streaming responses while maintaining data confidentiality through AEAD encryption and TEE hardware,
for full private AI compute.

## Returns

Returns a `Result` containing either:
* An HTTP response with the chat completion result
* A streaming SSE connection for real-time completions
* An `AtomaProxyError` error if the request processing fails

## Errors

Returns `AtomaProxyError::InvalidBody` if:
* The 'stream' field is missing or invalid in the payload

Returns `AtomaProxyError::InternalError` if:
* The inference service request fails
* Response processing encounters errors
* State manager updates fail

## Security Features

* Utilizes AEAD encryption for request/response data
* Supports TEE (Trusted Execution Environment) processing
* Implements secure key exchange using X25519
* Maintains confidentiality throughout the request lifecycle

Create confidential chat completions

This endpoint follows the OpenAI API format for generating vector embeddings from input text,
but with confidential processing (through AEAD encryption and TEE hardware).
The handler receives pre-processed metadata from middleware and forwards the request to
the selected node.

## Returns
* `Ok(Response)` - The embeddings response from the processing node
* `Err(AtomaProxyError)` - An error status code if any step fails

## Errors
* `INTERNAL_SERVER_ERROR` - Processing or node communication failures

Create confidential embeddings

This handler processes image generation requests in a confidential manner, providing additional
encryption and security measures for sensitive data processing. It supports both streaming and
non-streaming responses while maintaining data confidentiality through AEAD encryption and TEE hardware,
for full private AI compute.

Create confidential image

This endpoint follows the OpenAI API format for generating vector embeddings from input text.
The handler receives pre-processed metadata from middleware and forwards the request to
the selected node.

# Returns
* `Ok(Response)` - The embeddings response from the processing node
* `Err(AtomaProxyError)` - An error status code if any step fails

## Errors
* `INTERNAL_SERVER_ERROR` - Processing or node communication failures

Create embeddings

Health

This endpoint processes requests to generate images using AI models by forwarding them
to the appropriate AI node. The request metadata and compute units have already been
validated by middleware before reaching this handler.

## Errors
* Returns various status codes based on the underlying `handle_image_generation_response`:
  - `INTERNAL_SERVER_ERROR` - If there's an error communicating with the AI node

Create image

This endpoint mimics the OpenAI models endpoint format, returning a list of
available models with their associated metadata. Each model includes standard
OpenAI-compatible fields to ensure compatibility with existing OpenAI client libraries.

List models

This endpoint returns a list of available models from the OpenRouter
models file. The file is expected to be in JSON format and contains
information about the models, including their IDs and other metadata.

OpenRouter models listing endpoint

This endpoint allows nodes to register or update their public address in the system.
When a node comes online or changes its address, it can use this endpoint to ensure
the system has its current address for routing requests.

## Errors

Returns various `AtomaProxyError` variants:
* `MissingHeader` - If the signature header is missing
* `InvalidHeader` - If the signature header is malformed
* `InvalidBody` - If:
  - The request body cannot be read
  - The signature is invalid
  - The body cannot be parsed
  - The sui address doesn't match the signature
* `InternalError` - If:
  - The state manager channel is closed
  - The registration event cannot be sent
  - Node Sui address lookup fails

Create node

This endpoint attempts to find a suitable node and retrieve its public key for encryption
through a two-step process:

1. First, it tries to select an existing node with a public key directly.
2. If no node is immediately available, it falls back to finding the cheapest compatible node
   and acquiring a new stack entry for it.

This endpoint is specifically designed for confidential compute scenarios where
requests need to be encrypted before being processed by nodes.

## Errors
  - `INTERNAL_SERVER_ERROR` - Communication errors or missing node public keys
  - `SERVICE_UNAVAILABLE` - No nodes available for confidential compute

Create a node lock for confidential compute

Setup Node

Learn how to manage tasks, nodes, and compute resources on the Atoma network

Interact with Atoma Contract

Configure Atoma Node

Run Atoma Node

Learn about the inference services available in Atoma Node

Inference Services

Lists all attestation disputes against a specific node.

List against attestation disputes

Lists all attestation disputes initiated by a specific node.

List own attestation disputes

Lists all claimed stacks for a specific node identified by its small ID.

List claimed stacks

Create claim funds transaction

Create model subscription transaction

Subscribes a node to a specific model.

Create model subscription transaction

Create node registration transaction

Registers a new node in the system.

Create node registration transaction

Create task subscription transaction

Subscribes a node to a specific task.

Create task subscription transaction

Unsubscribes a node from a specific task.

Delete task subscription

Modify task subscription

Updates an existing task subscription for a node.

Modify task subscription

Lists all stacks for a specific node identified by its small ID.

List stacks

Lists all subscriptions for a specific node identified by its small ID.

List subscriptions

Retrieves all tasks from the state manager.

Changelog

Cloud

Node