Skip to content

Leases API

Endpoints for managing compute leases, querying providers, and requesting timekeeper attestations.

List All Leases

GET /leases

Returns all leases known to the node.

Response

[
  {
    "lease_hash": "a5b6c7d8...",
    "consumer": "a1b2c3d4...",
    "provider": "e5f6a7b8...",
    "vcpus": 4,
    "memory_mb": 8192,
    "disk_gb": 100,
    "duration": 86400,
    "access_pub_key": "f1e2d3c4...",
    "cost": 4,
    "stake": 1,
    "start_time": 1709500180000000000,
    "certificate_hash": "69af25e6...",
    "settled": false
  }
]
Field Type Description
lease_hash string Lease block hash (unique identifier)
consumer string Consumer's account address
provider string Provider's account address
vcpus integer Virtual CPUs allocated
memory_mb integer Memory in megabytes
disk_gb integer Disk space in gigabytes
duration integer Lease duration in seconds
access_pub_key string Consumer's ed25519 public key for SSH access (hex)
cost integer XUSD paid by consumer
stake integer XUSD staked by provider
start_time integer When the lease was accepted (unix nanos)
certificate_hash string Provider's performance certificate hash
settled boolean Whether the lease has been settled

Example

curl http://localhost:8080/leases

Get Lease by Hash

GET /leases/{hash}

Returns a single lease by its block hash.

Path Parameters

Parameter Type Description
hash string Hex-encoded lease block hash

Response

Returns a single Lease object (same schema as the list response).

Errors

Status Description
404 Lease not found

Example

curl http://localhost:8080/leases/a5b6c7d8...

List Providers

GET /providers

Returns all registered providers and their resource capacity.

Response

[
  {
    "address": "e5f6a7b8...",
    "vcpus": 32,
    "memory_mb": 65536,
    "disk_gb": 1000,
    "active_leases": 3,
    "available_vcpus": 20,
    "available_memory_mb": 41984,
    "available_disk_gb": 700
  }
]
Field Type Description
address string Provider's account address
vcpus integer Total virtual CPUs
memory_mb integer Total memory in megabytes
disk_gb integer Total disk space in gigabytes
active_leases integer Number of currently active leases
available_vcpus integer Remaining available vCPUs
available_memory_mb integer Remaining available memory
available_disk_gb integer Remaining available disk

Example

curl http://localhost:8080/providers

Request Lease

POST /lease/request

Creates a lease on behalf of the node's account. The node creates the lease block, broadcasts it via gossip, and waits for a provider to accept. Returns the lease hash on success.

Request Body

{
  "vcpus": 1,
  "memory_mb": 1024,
  "disk_gb": 1,
  "duration": 120,
  "access_pub_key": "a1b2c3d4e5f6..."
}
Field Type Description
vcpus integer Virtual CPUs requested
memory_mb integer Memory in megabytes
disk_gb integer Disk space in gigabytes
duration integer Lease duration in seconds (min 60, max 31536000)
access_pub_key string Consumer's ed25519 public key as 64-char hex. Injected into the VM for SSH access.

At least one resource dimension must be non-zero. The cost is computed automatically using the cost model formula.

Response

{
  "lease_hash": "6226fb52501a9052..."
}

Errors

Status Description
400 Invalid request (missing fields, insufficient XUSD balance, no providers)

End-to-end flow

This endpoint handles the full lease creation flow: marketplace negotiation, lease block creation with PoW, and gossip broadcast. The access_pub_key is included in the on-chain lease block and used by the provider to configure SSH access to the VM. See Lease Lifecycle for details.

Request Timekeeper Attestation

POST /attestation/request

Requests an attestation from the node's configured timekeeper. Attestations are required for lease accept and lease settle blocks.

Request Body

{
  "lease_hash": "a5b6c7d8..."
}
Field Type Description
lease_hash string Hash of the lease block to attest

Response

{
  "public_key": "f1a2b3c4...",
  "timestamp": 1709500175000000000,
  "signature": "e6f7a8b9..."
}
Field Type Description
public_key string Timekeeper's hex-encoded ed25519 public key
timestamp integer Attestation timestamp (unix nanos)
signature string ed25519 signature over the lease hash + timestamp

Errors

Status Description
400 Invalid lease hash
404 Lease not found
503 Timekeeper unavailable

What is a timekeeper?

Timekeepers are trusted nodes authorised by DAO governance to attest to lease events. Their public keys are stored in the state chain. See Attestations for details.

List VMs

GET /vms

Returns all VMs managed by this node (both as provider and consumer). Provider-only: shows locally running VMs. Consumer: shows VMs where credentials have been received.

Response

[
  {
    "lease_hash": "6226fb52501a...",
    "status": "running",
    "resources": {
      "vcpus": 1,
      "memory_mb": 1024,
      "disk_gb": 5
    },
    "created_at": 1709500180000000000
  }
]

Get VM

GET /vms/{leaseHash}

Returns info about a specific VM by its lease hash.

Errors

Status Description
404 VM not found

Execute Command in VM

POST /vms/{leaseHash}/exec

Executes a shell command inside the VM. Provider-only — the command is run via limactl shell.

Request Body

{
  "command": "uname -a"
}

Response

{
  "exit_code": 0,
  "stdout": "Linux lima-xe-6226fb52501a 6.6.32-0-lts ...\n",
  "stderr": ""
}

Errors

Status Description
400 Missing command
404 VM not found

TCP Tunnel

POST /tunnel/{leaseHash}/tcp

Upgrades the HTTP connection to a raw TCP tunnel to the VM. Used for programmatic access to the VM's SSH port. The lease must exist and not be settled.

This endpoint hijacks the HTTP connection and proxies bytes bidirectionally to the provider's tunnel protocol.