Skip to content

Node API

Endpoints for node information, pending blocks, frontiers, conflicts, and VM management.

Get Node Info

GET /node

Returns information about the running node.

Response

{
  "id": "12D3KooWAbCdEfGhIjKlMnOpQrStUvWxYz...",
  "address": "a1b2c3d4...",
  "version": "xe/0.4.0-abc1234",
  "network_id": "testnet",
  "block_count": 1542,
  "accounts": 23,
  "peer_count": 7,
  "peers": [
    {
      "id": "12D3KooWZyXwVuTsRqPo...",
      "address": "e5f6a7b8...",
      "version": "0.1.0",
      "connected_at": 1709500000000000000
    }
  ]
}
Field Type Description
id string Node's libp2p peer ID
address string Node's account address (hex-encoded ed25519 public key)
version string Node software version
network_id string Network identifier (e.g. "testnet", "mainnet"). Included in all block hashes to prevent cross-network replay.
block_count integer Total blocks in the ledger
accounts integer Number of accounts with chains
peer_count integer Number of connected peers
peers array Connected peer details

Peer Object

Field Type Description
id string Peer's libp2p peer ID
address string Peer's account address
version string Peer's software version
connected_at integer Connection timestamp (unix nanos)

Example

curl http://localhost:8080/node

Get Pending Sends for Account

GET /pending/{address}

Returns pending (unreceived) sends destined for a specific account.

Path Parameters

Parameter Type Description
address string Hex-encoded ed25519 public key of the recipient

Response

[
  {
    "hash": "a5b6c7d8...",
    "from": "c9d0e1f2...",
    "amount": "100000",
    "asset": "XE",
    "timestamp": 1709500060000000000
  }
]
Field Type Description
hash string Hash of the send block
from string Sender's account address
amount string Amount sent (string-encoded integer)
asset string Asset name (XE or XUSD)
timestamp integer Send block timestamp (unix nanos)

Example

curl http://localhost:8080/pending/a1b2c3d4...

Get All Pending Sends

GET /pending

Returns all pending sends across all accounts.

Response

Returns an array of pending send objects (same schema as the per-account endpoint), grouped or listed flat.

Example

curl http://localhost:8080/pending

Get All Frontiers

GET /frontiers

Returns the frontier (latest block hash) for every account in the ledger.

Response

{
  "a1b2c3d4...": "f2a3b4c5...",
  "e5f6a7b8...": "c8d9e0f1..."
}

Returns a JSON object mapping account addresses to their frontier block hashes.

Frontier sync

Frontiers are used during peer synchronisation to determine which accounts need updating. A node compares its frontiers with a peer's frontiers to identify missing blocks.

Example

curl http://localhost:8080/frontiers

Get All Conflicts

GET /conflicts

Returns all active conflicts (equivocations) in the ledger.

Response

[
  {
    "account": "c9d0e1f2...",
    "blocks": [
      {
        "hash": "a1b2c3d4...",
        "votes": 3,
        "weight": "5000000"
      },
      {
        "hash": "e5f6a7b8...",
        "votes": 1,
        "weight": "2000000"
      }
    ],
    "status": "voting",
    "detected_at": 1709500060000000000
  }
]
Field Type Description
account string Account that equivocated
blocks array Conflicting blocks with vote tallies
status string Conflict status: voting, resolved
detected_at integer When the conflict was detected (unix nanos)

See Consensus for how conflicts are detected and resolved.

Example

curl http://localhost:8080/conflicts

Get Conflicts for Account

GET /conflicts/{account}

Returns conflicts for a specific account.

Path Parameters

Parameter Type Description
account string Hex-encoded ed25519 public key

Response

Same schema as the all-conflicts endpoint, filtered to the specified account.

Errors

Status Description
404 No conflicts found for account

Example

curl http://localhost:8080/conflicts/c9d0e1f2...

List VMs

GET /vms

Returns all VMs managed by this node. Only available on provider nodes.

Response

[
  {
    "lease": "a5b6c7d8...",
    "status": "running",
    "vcpus": 4,
    "memory_mb": 8192,
    "disk_gb": 100,
    "ip": "10.0.0.2",
    "created_at": 1709500180000000000
  }
]
Field Type Description
lease string Lease block hash this VM serves
status string VM status: creating, running, stopped, error
vcpus integer Allocated virtual CPUs
memory_mb integer Allocated memory in megabytes
disk_gb integer Allocated disk in gigabytes
ip string VM's internal IP address
created_at integer VM creation timestamp (unix nanos)

Provider-only endpoint

This endpoint is only available on nodes running in provider mode. Non-provider nodes return an empty array.

Example

curl http://localhost:8080/vms

Get VM Info

GET /vms/{lease}

Returns detailed information about a specific VM.

Path Parameters

Parameter Type Description
lease string Lease block hash

Response

Returns a single VM object (same schema as the list endpoint).

Errors

Status Description
404 VM not found

Example

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

Execute Command in VM

POST /vms/{lease}/exec

Executes a command inside a VM. This is a synchronous endpoint -- it blocks until the command completes or times out.

Path Parameters

Parameter Type Description
lease string Lease block hash

Request Body

{
  "command": "uname -a"
}
Field Type Description
command string Shell command to execute

Response

{
  "exit_code": 0,
  "stdout": "Linux xe-vm 5.15.0 #1 SMP x86_64 GNU/Linux\n",
  "stderr": ""
}
Field Type Description
exit_code integer Process exit code (0 = success)
stdout string Standard output
stderr string Standard error

Errors

Status Description
404 VM not found
408 Command timed out
500 Execution error

Security consideration

This endpoint executes arbitrary commands inside the VM. In production, access should be restricted to the consumer that owns the lease. Authentication and authorisation are handled at the transport level.

Example

curl -X POST http://localhost:8080/vms/a5b6c7d8.../exec \
  -H "Content-Type: application/json" \
  -d '{"command": "uname -a"}'