HTTP API

Asset Core exposes HTTP APIs through two daemons: the write daemon for commits and the read daemon for queries.

Overview

The API is RESTful with JSON payloads. Both daemons provide health endpoints for monitoring, and responses include freshness metadata where applicable.

The full specification is available in openapi.json in the distribution bundle.

Structure

Write Daemon Endpoints

Method	Path	Description
POST	/v1/commit	Submit a transaction
POST	/v1/register/class	Register a new asset class
POST	/v1/register/class-shape	Register a shape for a class
GET	/v1/health	Health check with commit log status
GET	/v1/metrics	Prometheus metrics

Read Daemon Endpoints

Method	Path	Description
GET	/v1/read/container/{id}	Get container metadata
GET	/v1/read/container/{id}/balances	Get container balances
GET	/v1/read/container/{id}/slots	Get container slots
GET	/v1/read/container/{id}/grid	Get container grid
GET	/v1/read/class/{id}	Get class details
GET	/v1/read/classes	List registered classes
GET	/v1/read/class/{id}/shapes	Get class shapes
GET	/v1/read/class/{id}/stats	Get class statistics
GET	/v1/read/freshness	Get freshness metadata
GET	/v1/health	Health check

Fields

Request Headers

Header	Required	Description
Content-Type	Yes	Must be application/json for POST requests
X-Idempotency-Key	No	Alternative to request body field

Response Headers

Header	Description
X-Asset-Idempotency	hit if response was cached
Content-Type	Always application/json

Common Response Fields

Success responses include:

{
  "global_seq": 42,
  "batch_seq": 1,
  "minted_instances": [9001, 9002],
  "metadata": { ... }
}

Query responses include freshness:

{
  "data": { ... },
  "freshness": {
    "checkpoint_seq": 42,
    "commit_log_seq": 45
  }
}

Examples

Submit a Transaction

curl -X POST http://localhost:8080/v1/commit \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "op": "CreateContainer",
        "args": {
          "container_id": 1001,
          "kind": "Standard",
          "owner": null
        }
      }
    ],
    "idempotency_key": "create-container-1001"
  }'

Response:

{
  "global_seq": 1,
  "batch_seq": 1,
  "minted_instances": [],
  "metadata": {
    "idempotency_key": "create-container-1001"
  }
}

Query Container Balances

curl http://localhost:8081/v1/read/container/1001/balances

Response:

{
  "container_id": 1001,
  "balances": [
    {
      "class_id": 100,
      "key": 1,
      "quantity": 500
    }
  ],
  "freshness": {
    "checkpoint_seq": 1,
    "commit_log_seq": 1
  }
}

Check Health

curl http://localhost:8080/v1/health

Response:

{
  "status": "healthy",
  "commit_log": {
    "end_seq": 100,
    "checkpoint_seq": 100,
    "lag": 0,
    "driver": {
      "name": "file",
      "path": "/var/lib/assetcore/commit_log.log"
    }
  }
}

Related references

• Transactions - Request body structure
• Error Model - Status codes and error responses
• OpenAPI Specification - Full API specification