API Reference¶
The XE node exposes an HTTP REST API for interacting with the block lattice, leases, state chain, directory, chat, and node management.
Server Configuration¶
| Parameter | Default | Description |
|---|---|---|
| Bind address | 127.0.0.1 |
Network interface to listen on (-api-bind flag) |
| Port | 8080 |
HTTP port (-api-port flag) |
| CORS origin | http://localhost:3000 |
Allowed origin for cross-origin requests (-cors-origin flag) |
Rate Limiting¶
All endpoints are rate-limited per source IP:
| Parameter | Value |
|---|---|
| Sustained rate | 100 requests/second |
| Burst capacity | 500 requests |
| Scope | Per IP address |
Requests exceeding the rate limit receive a 429 Too Many Requests response.
Common Conventions¶
Encoding. All request and response bodies use JSON. Set Content-Type: application/json on requests with bodies.
Hashes. Block hashes, signatures, and public keys are hex-encoded strings.
Timestamps. All timestamps are Unix nanoseconds (int64).
Errors. Error responses return an appropriate HTTP status code with a JSON body:
Endpoint Groups¶
| Group | Prefix | Description |
|---|---|---|
| Accounts | /accounts |
Account balances, chains, and frontiers |
| Blocks | /blocks, /pow |
Submit and query blocks, compute PoW |
| Leases | /leases, /providers, /lease, /attestation |
Lease management and provider discovery |
| State Chain | /statechain |
DAO governance state machine |
| Directory | /directory |
Account-to-peer registration |
| Chat | /chat |
Peer-to-peer messaging |
| Node | /node, /pending, /frontiers, /conflicts, /vms |
Node info, pending blocks, conflicts, VMs |
Quick Reference¶
Read Endpoints¶
| Method | Path | Description |
|---|---|---|
| GET | /accounts |
List all accounts |
| GET | /accounts/{address}/balance |
Get account balances |
| GET | /accounts/{address}/chain |
Get account block chain |
| GET | /blocks/{hash} |
Get block by hash |
| GET | /blocks/recent |
Get recent blocks |
| GET | /leases |
List all leases |
| GET | /leases/{hash} |
Get lease by hash |
| GET | /providers |
List providers |
| GET | /statechain/tip |
Get latest state chain block |
| GET | /statechain/blocks |
Get state chain block range |
| GET | /statechain/blocks/{index} |
Get state chain block by index |
| GET | /statechain/kv/{key} |
Get state value |
| GET | /statechain/kv |
Get all state KV entries |
| GET | /statechain/keyset |
Get DAO keyset |
| GET | /directory |
List all registrations |
| GET | /directory/{account} |
Lookup account registration |
| GET | /chat/messages |
Get messages |
| GET | /chat/contacts |
List chat contacts |
| GET | /chat/events |
SSE message stream |
| GET | /node |
Get node info |
| GET | /pending |
Get all pending sends |
| GET | /pending/{address} |
Get pending sends for account |
| GET | /frontiers |
Get all frontiers |
| GET | /conflicts |
Get all conflicts |
| GET | /conflicts/{account} |
Get conflicts for account |
| GET | /vms |
List VMs |
| GET | /vms/{lease} |
Get VM info |
Write Endpoints¶
| Method | Path | Description |
|---|---|---|
| POST | /blocks/send |
Submit send block |
| POST | /blocks/receive |
Submit receive block |
| POST | /blocks/claim |
Submit claim block |
| POST | /blocks/lease |
Submit lease block |
| POST | /blocks/lease_accept |
Submit lease accept block |
| POST | /blocks/lease_settle |
Submit lease settle block |
| POST | /pow |
Compute PoW nonce |
| POST | /lease/request |
Request compute resources |
| POST | /attestation/request |
Request timekeeper attestation |
| POST | /statechain/blocks |
Submit state chain block |
| POST | /directory/register |
Register in directory |
| POST | /chat/send |
Send chat message |
| POST | /vms/{lease}/exec |
Execute command in VM |