Hylon AI API

Overview

The Hylon AI product runs on the OrbNET platform under /api/v1/hylon/*. The surface splits into four groups:

• Public reads: pricing and the plan catalog, no auth.
• User endpoints: entitlement, usage, checkout, API keys, and the node-owner endpoints. Authenticated by an OrbNET JWT session or a Hylon API key (Authorization: Bearer hyl_sk_...).
• Node-agent endpoints: the task plane spoken by the Hylon node binary. Authenticated by X-Node-UUID and X-Node-Key headers, never a JWT.
• Internal: metered usage ingest, reachable only with the server-to-server internal API key.

All endpoints share the standard OrbNET response envelope:

{ "success": true, "data": { } }

Base URL: https://api.orbai.world

Pricing

curl https://api.orbai.world/api/v1/hylon/pricing

{
  "success": true,
  "data": {
    "models": [
      {
        "model": "Qwen/Qwen2.5-3B-Instruct",
        "input_credits_per_mtok": 20,
        "output_credits_per_mtok": 60,
        "cached_input_credits_per_mtok": 0,
        "is_active": true
      }
    ]
  }
}

Plans

Each plan carries id, slug, name, tier (pro, pro_max, max), price_cents, duration_days, checkout_enabled, and a features block (included_mtok_month, models, max_effort, concurrent_sessions).

Me (entitlement)

A paid tier comes from an active Hylon subscription; otherwise the account resolves to the free tier. The response also reports how the call was authenticated (authenticated_via: session or api_key, plus api_key_id for key calls) so integrations can attribute usage.

{
  "success": true,
  "data": {
    "user_id": 12345,
    "tier": "free",
    "plan_id": 0,
    "plan_slug": "",
    "status": "FREE",
    "is_paid": false,
    "models": null,
    "max_effort": "",
    "concurrent_sessions": 0,
    "included_mtok_month": 0,
    "included_tokens_used": 0,
    "free_daily_tokens": 100000,
    "credit_balance": 0,
    "expires_at": null,
    "authenticated_via": "session",
    "api_key_id": null
  }
}

Usage

Each event records the model, input/output/cached token counts, cost_credits, the charge_source (free, included_quota, or credits), and the balance before and after.

Checkout

Fail-closed: answers 503 when Stripe is not configured on the deployment and 400 for an invalid or non-Hylon plan.

API keys

Key format: hyl_sk_<8 hex chars>_<secret body>. The stored record keeps only a SHA-256 hash; verification is constant-time.

Node program (owner side)

Session-only, like API-key creation: calls authenticated with a Hylon API key are refused (403). Returns the code, its expiry, the paste-ready command, and the program's beta status and honesty note.

{
  "success": true,
  "data": {
    "nodes": [
      {
        "id": 8,
        "name": "my-mac",
        "device_type": "desktop",
        "deployment_type": "HOME",
        "tier": "server",
        "status": "online",
        "last_seen": "2026-07-28T10:00:00Z",
        "points": 6,
        "contributions": {
          "tasks_completed": 6,
          "compute_units": 0,
          "inference_requests": 0
        }
      }
    ],
    "program_status": "beta",
    "note": "Beta: nodes run verification and benchmark tasks. Rewards are points in the node-program ledger; no token payouts are made or promised."
  }
}

Node-agent task plane

These endpoints are spoken by the node binary. See the operator guide: Run a Hylon Node.

Returns node_id, node_uuid, node_key (returned exactly once; only its hash is stored), and the derived tier. An unknown, expired, or already-used code gets 401 setup_code_invalid.

Authentication: X-Node-UUID and X-Node-Key headers, validated constant-time and fail-closed against the node record. A lease call also refreshes the node's heartbeat. Each leased task carries id, kind (verify.recompute or bench.cpu), a payload (seed, rounds), and lease_expires_at.

Responds with accepted and points_awarded. Points are awarded once per task ever (idempotent), and only when the server's own recomputation matches.

Internal: usage ingest

Protected by the internal API key (X-API-Key); unauthenticated calls get 401. Idempotent per request_id. Settlement charges in the order free daily allowance, included monthly quota, prepaid credits, and answers 402 insufficient_credits or 422 model_not_priced when it cannot settle.

Honesty guarantees baked into the API

• Node rewards are points in a ledger, never token amounts. Every node-program response repeats this in program_status and note fields.
• Contribution counters report only work that actually happened; compute and inference counters stay at zero until those workloads ship.
• Billing fails closed: unpriced models are rejected, balances never go negative, and unauthenticated settlement is refused.