service setup

Services define the capabilities your provider offers to the network. Each service has its own pricing, trust requirements, input/output schemas, and acceptance criteria that verifiers evaluate against.

Overview

Services are drafted independently from provider registration. Use halot service init to create a local draft in the services/ directory, then register that draft on Halot with halot service register. Registration publishes the service definition to 0G Storage and anchors its root hash on the 0G provider registry.

Identity: serviceId is the global machine identifier for a registered service. It must be unique across Halot. name is only the human-facing label and can repeat across providers. Starter service files can leave serviceId blank; Halot assigns the canonical svc_... ID when the service is registered.

Note: halot service init only creates a local draft. The canonical serviceId is assigned later by halot service register.

Ownership: service drafts do not carry a providerId field. halot service register, halot service update, and halot service remove read the current providerId from halot.provider.json and sign the request with the provider authority in wallets.json.

Service configuration

Each service JSON file defines the full specification for a capability exposed on Halot. Here is the complete schema:

Endpoints: services declare their own endpoint.health for availability checks. Worker-backed services also declare endpoint.execution. Middleware-backed services can omit endpoint.execution because the Express route wrapped with halot() is already the execution surface.

json

{
  "serviceId": "",
  "name": "GPT-5.4 Text",
  "description": "Returns paid text output for a prompt",
  "version": "1.0.0",
  "category": "text",
  "trustLevel": "standard",
  "endpoint": {
    "health": "https://your-provider.example/health",
    "execution": "https://your-provider.example/execute"
  },
  "pricing": {
    "baseFee": "3.00",
    "currency": "USDC",
    "model": "per-job"
  },
  "settlement": {
    "accepts": [
      {
        "network": "0g:testnet",
        "token": "USDC"
      },
      {
        "network": "stellar:testnet",
        "token": "USDC"
      }
    ]
  },
  "input": {
    "schema": {
      "type": "object",
      "properties": {
        "query": { "type": "string", "maxLength": 500 },
        "depth": { "type": "string", "enum": ["brief", "detailed"] }
      },
      "required": ["query"]
    },
    "maxSize": "10kb"
  },
  "output": {
    "schema": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "summary": { "type": "string" },
        "sections": { "type": "array" },
        "sources": { "type": "array" }
      },
      "required": ["title", "summary", "sections"]
    },
    "format": "json"
  },
  "acceptanceCriteria": {
    "schemaValid": true,
    "minSections": 3,
    "sourcesRequired": true
  },
  "sla": {
    "maxExecutionTime": 120,
    "retryPolicy": "none"
  }
}

Field reference

Required fields

Field	Type	Description
name	string	Human-readable service name.
description	string	What this service does.
version	string	Semver version of the service definition.
category	enum	`text`, `code`, `image`, `audio`, `video`, `document`, `tool`, or `workflow`.
trustLevel	enum	`standard` (3 verifiers), `thorough` (5 verifiers), `critical` (7 verifiers), or `auto` to derive the jury size from the base fee.
endpoint.health	string	Health check URL used before Halot confirms and relays funded jobs for this service.
endpoint.execution	string	Optional execution URL for worker-backed services. Leave it out when the service is handled directly by SDK middleware.
pricing.baseFee	string	Fixed cost per job in the specified currency.
input.schema	JSON Schema	Defines the expected input structure from requesters.
input.maxSize	string	Maximum input payload size (e.g., `"10kb"`).
output.schema	JSON Schema	Defines the expected output structure. Verifiers validate results against this.
output.format	string	Output format (e.g., `"json"`).
acceptanceCriteria	object	Custom criteria verifiers evaluate beyond schema validation.
sla.maxExecutionTime	number	Maximum seconds allowed for job execution.
sla.retryPolicy	string	Retry behavior on failure (`"none"` or `"once"`).

Settlement networks

The settlement.accepts array defines which payment networks your service supports. Services declare only network and token; Halot resolves the actual escrow contract and token metadata internally.

Network	CAIP-2 ID	Default settlement token
0G	0g:testnet or 0g:mainnet	USDC
Stellar	stellar:testnet or stellar:mainnet	USDC

A provider can have payout wallets for many networks, but each service still chooses its own accepted settlement networks. Wallet availability and service policy are separate.

CLI commands

bash

# Create a draft service
$ halot service init --name "GPT-5.4 Text"

# Register the first unregistered draft
$ halot service register

# Register a specific service file
$ halot service register --file service-002.json

# List all registered services for your provider
$ halot service list

# Edit the local file, then re-anchor that registered service
$ halot service update <serviceId>

# Or point at a specific service file
$ halot service update --file service-svc_abc123.json

# Remove a service from the network
$ halot service remove <serviceId>

Important

You must register your provider (halot provider register) before registering services. The CLI will error if no providerId is found in your config.