{ "openapi": "3.1.0", "info": { "title": "XE Testnet node API", "version": "1.0.0", "summary": "JSON HTTP API exposed by every XE node; served publicly by the London testnet node.", "description": "Every XE node exposes the same JSON HTTP API (default `http://127.0.0.1:8080`, `--api-port`/`--api-bind` to change it). This document describes the public London testnet node (network `testnet-0005`), reachable through the versioned `https://test.network/api/v1` proxy, its unversioned alias `https://test.network/api`, or directly at `https://ldn.core.test.network`.\n\n**Versioning.** URL-path versioning: the major version is the first segment after /api (currently v1); every response carries `X-API-Version`. Changes within a major are additive only; a new major keeps the previous one alive for 180 days; deprecations are signalled with `deprecated: true` here and `Deprecation` (RFC 9745) + `Sunset` (RFC 8594) headers at least 90 days ahead. Full policy: https://test.network/developers#versioning and `x-versioning` below.\n\n**Amounts are micro-units.** 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight is an integer micro-unit count.\n\n**Authentication is per-endpoint.** Most reads are open. Four endpoints are operator-only (admin bearer token): `POST /lease/request`, `POST /lease/{hash}/renew`, and the parameterless `GET /chat/events` firehose and `GET /chat/contacts` listing. Reading a specific account's chat requires an ownership proof — see the `ownershipProof` security scheme.\n\n**Rate limits** are per client IP and request class: reads 1000 per 5s, writes 50 per 5s (the node's own 200/s and 10/s with bursts of 1,000 and 50). Every response carries `RateLimit-Policy` and `RateLimit` (draft-ietf-httpapi-ratelimit-headers) plus the legacy `RateLimit-Limit`/`RateLimit-Remaining`/`RateLimit-Reset`; a 429 adds `Retry-After`. Details: https://test.network/developers#rate-limits and `x-rate-limits` below.\n\n**Errors** are always JSON. Every 4xx/5xx from the proxy is the `Error` schema (`error.code`, `error.message`, `error.hint`, `error.docs`); the node's own JSON errors pass through unchanged.\n\n**Testnet state:** the ledger, the faucet (1,000 XE per account per day at https://faucet.test.network), chat, the state chain and every read endpoint work. Compute leasing is live — providers are advertising (`GET /providers`) and leases are being accepted, renewed and settled (`GET /leases`) — but it is paid in XUSD, which only the operators' `sys.minter` accounts issue and which testers cannot obtain yet: read the market and run a provider freely, but do not expect to fund a lease. There is no provider stake on this network and billing is per minute. The network can be wiped at any time, which resets identifiers but not this contract.\n\nHuman documentation: https://test.network/docs/api. Source: https://github.com/xeprotocol/xe (GPL-3.0).", "termsOfService": "https://test.network/about", "contact": { "name": "XE L1 Ltd.", "url": "https://test.network/contact", "email": "hello@xe.network" }, "license": { "name": "GNU General Public License v3.0", "identifier": "GPL-3.0-only" } }, "externalDocs": { "description": "XE Testnet documentation", "url": "https://test.network/docs" }, "servers": [ { "url": "https://test.network/api/v1", "description": "test.network proxy, versioned (v1) — pin this in integrations" }, { "url": "https://test.network/api", "description": "test.network proxy, unversioned alias of the current major version" }, { "url": "https://ldn.core.test.network", "description": "London testnet node, direct and unversioned; no RateLimit headers or JSON error wrapping" } ], "tags": [ { "name": "Accounts" }, { "name": "Blocks" }, { "name": "Leases" }, { "name": "State Chain" }, { "name": "Directory" }, { "name": "Chat" }, { "name": "Node" } ], "paths": { "/accounts": { "get": { "operationId": "listAccounts", "tags": [ "Accounts" ], "summary": "List all accounts", "description": "Returns accounts known by the node with balances and frontier hashes. Balances are micro-units (1 XE = 1 XUSD = 1,000,000 micro-units).", "parameters": [], "responses": { "200": { "description": "Every account the node knows.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountList" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/{address}/balance": { "get": { "operationId": "getAccountBalance", "tags": [ "Accounts" ], "summary": "Get account balance", "description": "Returns per-asset balances for one account, in micro-units. `balances` includes unfinalized inflows; `spendable` counts only finalized funds and is the settlement figure.", "parameters": [ { "name": "address", "in": "path", "required": true, "description": "Account address, 64 hex characters.", "schema": { "type": "string" }, "example": "26740934b57627b340fd881710fbca3ab70f662e18a20fd21d4773aa6c56c06b" } ], "responses": { "200": { "description": "Balances, spendable balances and the finalized height.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balances" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/{address}/chain": { "get": { "operationId": "getAccountChain", "tags": [ "Accounts" ], "summary": "Get account chain", "description": "Returns the account block chain from oldest to newest, paginated, with the full chain length in `total`. Each block carries a `finalized` flag; only the first block carries `pub_key`.", "parameters": [ { "name": "address", "in": "path", "required": true, "description": "Account address, 64 hex characters.", "schema": { "type": "string" }, "example": "26740934b57627b340fd881710fbca3ab70f662e18a20fd21d4773aa6c56c06b" }, { "name": "offset", "in": "query", "required": false, "description": "Number of entries to skip.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of entries to return.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Blocks, oldest first.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountChain" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/{address}/keyset": { "get": { "operationId": "getAccountKeyset", "tags": [ "Accounts" ], "summary": "Get multisig keyset", "description": "Returns the multisig keyset for an account when present (404 for a single-key account). `keys` are ed25519 public keys, not addresses.", "parameters": [ { "name": "address", "in": "path", "required": true, "description": "Account address, 64 hex characters.", "schema": { "type": "string" }, "example": "26740934b57627b340fd881710fbca3ab70f662e18a20fd21d4773aa6c56c06b" } ], "responses": { "200": { "description": "The account's current keyset.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Keyset" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/accounts/{address}/reputation": { "get": { "operationId": "getAccountReputation", "tags": [ "Accounts" ], "summary": "Get account reputation", "description": "Returns the reputation aggregate for one account, built from on-chain lease activity.", "parameters": [ { "name": "address", "in": "path", "required": true, "description": "Account address, 64 hex characters.", "schema": { "type": "string" }, "example": "26740934b57627b340fd881710fbca3ab70f662e18a20fd21d4773aa6c56c06b" } ], "responses": { "200": { "description": "Reputation aggregate.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reputation" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reputation": { "get": { "operationId": "listReputations", "tags": [ "Accounts" ], "summary": "All reputations", "description": "Returns reputation aggregates for every known account, keyed by address. Paginated.", "parameters": [ { "name": "offset", "in": "query", "required": false, "description": "Number of entries to skip.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of entries to return.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Address → aggregate.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReputationList" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/blocks/send": { "post": { "operationId": "submitSendBlock", "tags": [ "Blocks" ], "summary": "Submit send block", "description": "Submits a signed send block. Requires a valid signature, hash, post-block balance, and PoW nonce; the destination must differ from the sending account. Success is 201 echoing the stored block; a rejection carries a `retryable` flag (400 false / 503 true).", "parameters": [], "responses": { "200": { "description": "Block accepted.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResult" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendBlock" }, "example": { "type": "send", "account": "26740934b57627b340fd881710fbca3ab70f662e18a20fd21d4773aa6c56c06b", "previous": "", "balance": 0, "timestamp": 0, "asset": "XE", "destination": "8bc63438d2e9e59ef229865abb73520955da9f3c43b41ff50298884f78ab970d", "amount": 1, "signature": "", "hash": "", "pow_nonce": 0 } } } } } }, "/blocks/receive": { "post": { "operationId": "submitReceiveBlock", "tags": [ "Blocks" ], "summary": "Submit receive block", "description": "Submits a signed receive block. 'source' is the hash of the pending send block being received. An account's first block must also declare `pub_key`; every later block must not.", "parameters": [], "responses": { "200": { "description": "Block accepted.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResult" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiveBlock" }, "example": { "type": "receive", "account": "26740934b57627b340fd881710fbca3ab70f662e18a20fd21d4773aa6c56c06b", "previous": "0", "pub_key": "", "balance": 0, "timestamp": 0, "asset": "XE", "source": "", "signature": "", "hash": "", "pow_nonce": 0 } } } } } }, "/blocks/lease": { "post": { "operationId": "submitLeaseBlock", "tags": [ "Blocks" ], "summary": "Submit lease block", "description": "Submits a signed compute lease block: XUSD escrow to a provider plus the requested vcpus/memory_mb/disk_gb/duration, an access public key and the hash of the provider's current certificate. `amount` must equal the per-minute cost formula exactly.", "parameters": [], "responses": { "200": { "description": "Block accepted.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResult" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseBlock" }, "example": { "type": "lease", "account": "26740934b57627b340fd881710fbca3ab70f662e18a20fd21d4773aa6c56c06b", "previous": "", "balance": 0, "timestamp": 0, "asset": "XUSD", "destination": "", "amount": 0, "vcpus": 1, "memory_mb": 1024, "disk_gb": 10, "duration": 300, "access_pub_key": "", "certificate_hash": "", "signature": "", "hash": "", "pow_nonce": 0 } } } } } }, "/blocks/lease_accept": { "post": { "operationId": "submitLeaseAcceptBlock", "tags": [ "Blocks" ], "summary": "Submit lease accept", "description": "Submits a provider lease acceptance block referencing the lease block via 'source', pinning the certificate and locking the emission parameters, with timekeeper attestations.", "parameters": [], "responses": { "200": { "description": "Block accepted.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResult" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseAcceptBlock" }, "example": { "type": "lease_accept", "account": "", "previous": "", "balance": 0, "timestamp": 0, "asset": "XUSD", "source": "", "certificate_hash": "", "locked_r": 2000, "locked_payout_cap": 0, "locked_twap_milli": 0, "attestations": [ { "public_key": "", "timestamp": 0, "signature": "" } ], "signature": "", "hash": "", "pow_nonce": 0 } } } } } }, "/blocks/lease_renew": { "post": { "operationId": "submitLeaseRenewBlock", "tags": [ "Blocks" ], "summary": "Submit lease renew", "description": "Submits a consumer renewal block: additional XUSD escrow and duration for an accepted lease, attested before its effective expiry. The SDK's holdLease submits one of these a minute at a time.", "parameters": [], "responses": { "200": { "description": "Block accepted.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResult" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseRenewBlock" }, "example": { "type": "lease_renew", "account": "26740934b57627b340fd881710fbca3ab70f662e18a20fd21d4773aa6c56c06b", "previous": "", "balance": 0, "timestamp": 0, "asset": "XUSD", "source": "", "amount": 0, "duration": 60, "certificate_hash": "", "locked_r": 2000, "locked_payout_cap": 0, "locked_twap_milli": 0, "attestations": [ { "public_key": "", "timestamp": 0, "signature": "" } ], "signature": "", "hash": "", "pow_nonce": 0 } } } } } }, "/blocks/lease_settle": { "post": { "operationId": "submitLeaseSettleBlock", "tags": [ "Blocks" ], "summary": "Submit lease settle", "description": "Submits a provider lease settlement block referencing the lease block via 'source'. Asset is XE and `amount` is the emission summed over the base term and every renewal; the XUSD escrow is burnt.", "parameters": [], "responses": { "200": { "description": "Block accepted.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResult" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseSettleBlock" }, "example": { "type": "lease_settle", "account": "", "previous": "", "balance": 0, "timestamp": 0, "asset": "XE", "source": "", "amount": 0, "attestations": [ { "public_key": "", "timestamp": 0, "signature": "" } ], "signature": "", "hash": "", "pow_nonce": 0 } } } } } }, "/blocks/lease_cancel": { "post": { "operationId": "submitLeaseCancelBlock", "tags": [ "Blocks" ], "summary": "Submit lease cancel", "description": "Submits a consumer lease cancellation block. Only the consumer can cancel, and only before the lease is accepted.", "parameters": [], "responses": { "200": { "description": "Block accepted.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResult" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseCancelBlock" }, "example": { "type": "lease_cancel", "account": "26740934b57627b340fd881710fbca3ab70f662e18a20fd21d4773aa6c56c06b", "previous": "", "balance": 0, "timestamp": 0, "asset": "XUSD", "source": "", "signature": "", "hash": "", "pow_nonce": 0 } } } } } }, "/blocks/lease_force_settle": { "post": { "operationId": "submitLeaseForceSettleBlock", "tags": [ "Blocks" ], "summary": "Submit lease force settle", "description": "Submits a consumer force-settle block to recover the full escrow from a lease the provider never settled, once expiry + settle grace + force-settle gap has passed (GET /node → lease_timing) and before the escrow expiry closes the refund window.", "parameters": [], "responses": { "200": { "description": "Block accepted.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResult" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseForceSettleBlock" }, "example": { "type": "lease_force_settle", "account": "26740934b57627b340fd881710fbca3ab70f662e18a20fd21d4773aa6c56c06b", "previous": "", "balance": 0, "timestamp": 0, "asset": "XUSD", "source": "", "attestations": [ { "public_key": "", "timestamp": 0, "signature": "" } ], "signature": "", "hash": "", "pow_nonce": 0 } } } } } }, "/blocks/multisig_open": { "post": { "operationId": "submitMultisigOpenBlock", "tags": [ "Blocks" ], "summary": "Open multisig account", "description": "Submits a multisig account open block with a keyset {keys, threshold} (ed25519 public keys) and a signatures array in place of the single signature. The account address is the SHA-256 of the canonical keyset, so the block declares no `pub_key`.", "parameters": [], "responses": { "200": { "description": "Block accepted.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResult" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultisigOpenBlock" }, "example": { "type": "multisig_open", "account": "", "previous": "0", "balance": 0, "timestamp": 0, "asset": "XE", "keyset": { "keys": [ "", "" ], "threshold": 2 }, "signatures": [ { "public_key": "", "signature": "" }, { "public_key": "", "signature": "" } ], "hash": "", "pow_nonce": 0 } } } } } }, "/blocks/multisig_update": { "post": { "operationId": "submitMultisigUpdateBlock", "tags": [ "Blocks" ], "summary": "Update multisig keyset", "description": "Submits a multisig keyset update block signed by the current keyset's threshold.", "parameters": [], "responses": { "200": { "description": "Block accepted.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResult" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultisigUpdateBlock" }, "example": { "type": "multisig_update", "account": "", "previous": "", "balance": 0, "timestamp": 0, "asset": "XE", "keyset": { "keys": [ "", "" ], "threshold": 1 }, "signatures": [ { "public_key": "", "signature": "" }, { "public_key": "", "signature": "" } ], "hash": "", "pow_nonce": 0 } } } } } }, "/blocks/burn": { "post": { "operationId": "submitBurnBlock", "tags": [ "Blocks" ], "summary": "Submit burn block", "description": "Submits a signed burn block, permanently destroying XE (XE only).", "parameters": [], "responses": { "200": { "description": "Block accepted.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResult" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BurnBlock" }, "example": { "type": "burn", "account": "26740934b57627b340fd881710fbca3ab70f662e18a20fd21d4773aa6c56c06b", "previous": "", "balance": 0, "timestamp": 0, "asset": "XE", "amount": 1, "signature": "", "hash": "", "pow_nonce": 0 } } } } } }, "/blocks/mint": { "post": { "operationId": "submitMintBlock", "tags": [ "Blocks" ], "summary": "Submit mint block", "description": "Submits a signed XUSD mint block. Only accounts listed in the sys.minter state key are authorized; on the testnet those are operator accounts, and the faucet hands out XE, not XUSD.", "parameters": [], "responses": { "200": { "description": "Block accepted.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResult" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MintBlock" }, "example": { "type": "mint", "account": "", "previous": "", "balance": 0, "timestamp": 0, "asset": "XUSD", "amount": 1, "signature": "", "hash": "", "pow_nonce": 0 } } } } } }, "/blocks/{hash}": { "get": { "operationId": "getBlock", "tags": [ "Blocks" ], "summary": "Get block by hash", "description": "Returns a block by its hash, plus a `finalized` flag.", "parameters": [ { "name": "hash", "in": "path", "required": true, "description": "Block hash, 64 hex characters.", "schema": { "type": "string" }, "example": "dcd6d6d6fd63d8d7db14214787781da6a6a7018526e069f5c5f3be221cb824de" } ], "responses": { "200": { "description": "The block.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Block" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/blocks/recent": { "get": { "operationId": "listRecentBlocks", "tags": [ "Blocks" ], "summary": "Recent blocks", "description": "Returns the newest account-chain blocks across the lattice, newest first. Optional ?limit (default 100, max 1000) and ?since (unix nanoseconds, strictly newer). Served from a snapshot rebuilt at most once per second.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of blocks to return.", "schema": { "type": "integer" } }, { "name": "since", "in": "query", "required": false, "description": "Only blocks newer than this unix-nanosecond timestamp.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Newest blocks first.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockList" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/leases": { "get": { "operationId": "listLeases", "tags": [ "Leases" ], "summary": "List leases", "description": "Returns known compute leases, including every renewal applied. Filter with ?state=created|accepted|settled|cancelled|unfulfilled|expired; paginated.", "parameters": [ { "name": "state", "in": "query", "required": false, "description": "Only leases in this lifecycle state.", "schema": { "type": "string", "enum": [ "created", "accepted", "settled", "cancelled", "unfulfilled", "expired" ] } }, { "name": "offset", "in": "query", "required": false, "description": "Number of entries to skip.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of entries to return.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Leases known to the node; [] when there are none.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseList" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/leases/{hash}": { "get": { "operationId": "getLease", "tags": [ "Leases" ], "summary": "Get lease", "description": "Returns one lease by lease hash. Needs a real lease hash — list current ones with GET /leases (optionally ?state=accepted).", "parameters": [ { "name": "hash", "in": "path", "required": true, "description": "Lease block hash.", "schema": { "type": "string" }, "example": "0c7f76dc6c2eb33a02f559c77fa773c1eb90b3aee2179004dd9680adf0573c5a" } ], "responses": { "200": { "description": "The lease.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lease" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/providers": { "get": { "operationId": "listProviders", "tags": [ "Leases" ], "summary": "List providers", "description": "Returns advertised compute providers and their current utilization. `account` is the provider address to put in a lease block's `destination` and to look up with GET /certificate/{provider}. A lease still in `created` reserves nothing; capacity is decided at accept time.", "parameters": [], "responses": { "200": { "description": "Providers currently advertising; [] when none are online.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderList" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/certificate": { "get": { "operationId": "getNodeCertificate", "tags": [ "Leases" ], "summary": "Node perf certificate", "description": "Returns this node's performance certificate (provider mode only; 404 otherwise).", "parameters": [], "responses": { "200": { "description": "This node's certificate.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Certificate" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/certificate/{provider}": { "get": { "operationId": "getProviderCertificate", "tags": [ "Leases" ], "summary": "Provider perf certificate", "description": "Returns a provider's current, unexpired performance certificate — what a lease is priced and written against. Expired certificates are never returned here; use GET /certificate/hash/{hash} for those.", "parameters": [ { "name": "provider", "in": "path", "required": true, "description": "Provider account address (from GET /providers).", "schema": { "type": "string" }, "example": "26740934b57627b340fd881710fbca3ab70f662e18a20fd21d4773aa6c56c06b" } ], "responses": { "200": { "description": "The provider's certificate.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Certificate" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/certificate/hash/{hash}": { "get": { "operationId": "getCertificateByHash", "tags": [ "Leases" ], "summary": "Certificate by hash", "description": "Returns a retained performance certificate by its own hash, including expired ones — historical lease blocks pin the certificate that was current when they were written, so nodes keep serving them.", "parameters": [ { "name": "hash", "in": "path", "required": true, "description": "Performance certificate hash, 64 hex characters (the `hash` field of GET /certificate/{provider}).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The certificate.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Certificate" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/certificate/nonces/{hash}": { "get": { "operationId": "getCertificateNonces", "tags": [ "Leases" ], "summary": "Certificate CPU witness", "description": "Returns the solving nonces behind a certificate's chained proof-of-work phase (one per puzzle, ~8 KB). Only the node that issued the certificate holds them; other nodes answer 404. Verify with perf.VerifyCPUChain(seed, nonces, puzzles) against `cpu_hash`.", "parameters": [ { "name": "hash", "in": "path", "required": true, "description": "Performance certificate hash, 64 hex characters (the `hash` field of GET /certificate/{provider}).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The witness.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateNonces" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/certificate/attestations/{hash}": { "get": { "operationId": "getCertificateAttestations", "tags": [ "Leases" ], "summary": "Certificate attestations", "description": "Returns the full start and end timekeeper attestations behind a certificate's merkle roots, so a verifier can recompute the roots and check each signature. Held only by the issuing node.", "parameters": [ { "name": "hash", "in": "path", "required": true, "description": "Performance certificate hash, 64 hex characters (the `hash` field of GET /certificate/{provider}).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Start and end attestations.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateAttestations" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lease/request": { "post": { "operationId": "requestLease", "tags": [ "Leases" ], "summary": "Request lease", "description": "Asks the node to build, sign and PoW a lease block from its own wallet. At least one of vcpus/memory_mb/disk_gb must be ≥ 1; duration is required. Responds 201 with the new lease hash.\n\nOperator-only.\n\nOperator-only: requires Authorization: Bearer ; signs and escrows from the node operator's own wallet. Shown for reference.", "parameters": [], "responses": { "200": { "description": "The hash of the lease the node created.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseRequestResult" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing credentials for a gated endpoint. `error.code` is `unauthorized`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credentials present but not sufficient (wrong admin token, failed ownership proof). `error.code` is `forbidden`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseRequest" }, "example": { "vcpus": 1, "memory_mb": 1024, "disk_gb": 10, "duration": 300, "access_pub_key": "" } } } }, "security": [ { "adminToken": [] } ] } }, "/lease/{hash}/renew": { "post": { "operationId": "renewLease", "tags": [ "Leases" ], "summary": "Renew lease (operator)", "description": "Asks the node to extend an accepted lease in place from its own wallet: it prices the extra duration at the provider's current certificate, gathers attestations, signs and PoWs the lease_renew block. `xe lease renew ` calls this.\n\nOperator-only.\n\nOperator-only: requires Authorization: Bearer and the node's own wallet must be the lease's consumer. Shown for reference.", "parameters": [ { "name": "hash", "in": "path", "required": true, "description": "Lease block hash.", "schema": { "type": "string" }, "example": "0c7f76dc6c2eb33a02f559c77fa773c1eb90b3aee2179004dd9680adf0573c5a" } ], "responses": { "200": { "description": "The renewal block hash, cost and duration.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseRenewResult" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing credentials for a gated endpoint. `error.code` is `unauthorized`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credentials present but not sufficient (wrong admin token, failed ownership proof). `error.code` is `forbidden`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseRenewRequest" }, "example": { "additional_secs": 60 } } } }, "security": [ { "adminToken": [] } ] } }, "/attestation/request": { "post": { "operationId": "requestAttestation", "tags": [ "Leases" ], "summary": "Request attestation", "description": "Asks this node, as a timekeeper, to attest the current time for a lease: ed25519 over sha256(lease_hash || timestamp). Rate limited to one per lease per client IP every 15 s (a rejected request does not consume the window). Needs a real lease hash — list current ones with GET /leases (optionally ?state=accepted).", "parameters": [], "responses": { "200": { "description": "The attestation.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attestation" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttestationRequest" }, "example": { "lease_hash": "0c7f76dc6c2eb33a02f559c77fa773c1eb90b3aee2179004dd9680adf0573c5a" } } } } } }, "/vms": { "get": { "operationId": "listVms", "tags": [ "Leases" ], "summary": "List VMs", "description": "Returns VM records known to the provider.", "parameters": [], "responses": { "200": { "description": "VM records.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmList" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vms/{lease}": { "get": { "operationId": "getVm", "tags": [ "Leases" ], "summary": "Get VM", "description": "Returns VM details for a lease. Needs a real lease hash — list current ones with GET /leases (optionally ?state=accepted).", "parameters": [ { "name": "lease", "in": "path", "required": true, "description": "Lease block hash.", "schema": { "type": "string" }, "example": "0c7f76dc6c2eb33a02f559c77fa773c1eb90b3aee2179004dd9680adf0573c5a" } ], "responses": { "200": { "description": "The VM record.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vm" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tunnel/{leaseHash}/tcp": { "post": { "operationId": "openTcpTunnel", "tags": [ "Leases" ], "summary": "TCP tunnel", "description": "Opens a raw TCP tunnel into a leased VM. Takes no JSON body: authentication is an X-Signature header (ed25519 signature over the 32 decoded lease-hash bytes with the lease's access key), after which the HTTP connection is hijacked into a byte stream.\n\nNot runnable from the browser: the response is a hijacked raw TCP stream, and the required X-Signature header needs the lease access key. Use the xe CLI or curl instead. Needs a real lease hash — list current ones with GET /leases (optionally ?state=accepted).", "parameters": [ { "name": "leaseHash", "in": "path", "required": true, "description": "Lease block hash.", "schema": { "type": "string" }, "example": "0c7f76dc6c2eb33a02f559c77fa773c1eb90b3aee2179004dd9680adf0573c5a" } ], "responses": { "200": { "description": "The connection is hijacked into a raw TCP byte stream.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/octet-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing credentials for a gated endpoint. `error.code` is `unauthorized`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credentials present but not sufficient (wrong admin token, failed ownership proof). `error.code` is `forbidden`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "leaseAccessSignature": [] } ] } }, "/statechain/tip": { "get": { "operationId": "getStateChainTip", "tags": [ "State Chain" ], "summary": "State chain tip", "description": "Returns the latest state chain block.", "parameters": [], "responses": { "200": { "description": "The newest state block.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StateBlock" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/statechain/blocks/{index}": { "get": { "operationId": "getStateBlock", "tags": [ "State Chain" ], "summary": "State block by index", "description": "Returns a state chain block by index.", "parameters": [ { "name": "index", "in": "path", "required": true, "description": "Zero-based block index.", "schema": { "type": "string" }, "example": "0" } ], "responses": { "200": { "description": "The state block.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StateBlock" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/statechain/blocks": { "get": { "operationId": "listStateBlocks", "tags": [ "State Chain" ], "summary": "State blocks", "description": "Returns state chain blocks and block count. Optional ?start and ?limit.", "parameters": [ { "name": "start", "in": "query", "required": false, "description": "First block index to return.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of blocks to return.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "A page of state blocks.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StateBlockPage" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "submitStateBlock", "tags": [ "State Chain" ], "summary": "Submit state block", "description": "Submits a state chain block signed by the DAO keyset threshold.", "parameters": [], "responses": { "200": { "description": "The appended state block.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StateBlock" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StateBlockSubmission" }, "example": { "ops": [ { "action": "set", "key": "demo.key", "value": "demo" } ], "signatures": [] } } } } } }, "/statechain/kv/{key}": { "get": { "operationId": "getStateValue", "tags": [ "State Chain" ], "summary": "State value", "description": "Returns one state chain key-value entry by full key (dots and slashes allowed).", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "State key, e.g. sys.network_id, sys.minter, epoch.0.", "schema": { "type": "string" }, "example": "sys.network_id" } ], "responses": { "200": { "description": "The entry.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StateValue" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/statechain/kv": { "get": { "operationId": "listStateValues", "tags": [ "State Chain" ], "summary": "All state values", "description": "Returns state chain key-value entries. Optional ?prefix filter plus ?offset/?limit pagination.", "parameters": [ { "name": "prefix", "in": "query", "required": false, "description": "Only keys starting with this prefix.", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "description": "Number of entries to skip.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of entries to return.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Entries.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StateValueList" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/statechain/keyset": { "get": { "operationId": "getDaoKeyset", "tags": [ "State Chain" ], "summary": "DAO keyset", "description": "Returns the current DAO keyset (`sys.dao_keyset`): M-of-N ed25519 public keys that sign state-chain blocks.", "parameters": [], "responses": { "200": { "description": "The DAO keyset.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Keyset" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/directory/register": { "post": { "operationId": "registerDirectoryEntry", "tags": [ "Directory" ], "summary": "Register directory entry", "description": "Registers an account-to-peer mapping, signed by the account key over the registration payload.", "parameters": [], "responses": { "200": { "description": "The stored registration.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryEntry" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryRegistration" }, "example": { "account": "26740934b57627b340fd881710fbca3ab70f662e18a20fd21d4773aa6c56c06b", "pub_key": "", "node_peer": "", "timestamp": 0, "signature": "" } } } } } }, "/directory": { "get": { "operationId": "listDirectory", "tags": [ "Directory" ], "summary": "List directory", "description": "Returns account-to-peer registrations, paginated.", "parameters": [ { "name": "offset", "in": "query", "required": false, "description": "Number of entries to skip.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of entries to return.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Registrations.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryEntryList" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/directory/{account}": { "get": { "operationId": "getDirectoryEntry", "tags": [ "Directory" ], "summary": "Lookup directory entry", "description": "Returns the registration for one account (404 if the account has not registered or its entry expired).", "parameters": [ { "name": "account", "in": "path", "required": true, "description": "Account address, 64 hex characters.", "schema": { "type": "string" }, "example": "26740934b57627b340fd881710fbca3ab70f662e18a20fd21d4773aa6c56c06b" } ], "responses": { "200": { "description": "The registration.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryEntry" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chat/send": { "post": { "operationId": "sendChatMessage", "tags": [ "Chat" ], "summary": "Send chat message", "description": "Sends a peer-to-peer chat message. Requires a full pre-signed envelope (from, pub_key, signature over the envelope id) — the node never signs on behalf of callers. Timestamps must be within ±5 minutes of node time; messages are capped at 8 KB. Delivery is over encrypted libp2p transport; the payload itself is not end-to-end encrypted.", "parameters": [], "responses": { "200": { "description": "{ ok: true } once the envelope is stored and relayed.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSendResult" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatMessage" }, "example": { "from": "26740934b57627b340fd881710fbca3ab70f662e18a20fd21d4773aa6c56c06b", "pub_key": "", "to": "8bc63438d2e9e59ef229865abb73520955da9f3c43b41ff50298884f78ab970d", "message": "hello testnet", "timestamp": 0, "signature": "", "pow_nonce": 0 } } } } } }, "/chat/auth/challenge": { "get": { "operationId": "getChatAuthChallenge", "tags": [ "Chat" ], "summary": "Chat auth challenge", "description": "Issues a single-use challenge valid for 120 seconds. Sign it with your account key (ed25519 over the raw challenge bytes) and pass account, challenge, and sig to the chat read endpoints as ownership proof.", "parameters": [], "responses": { "200": { "description": "A fresh challenge.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatChallenge" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chat/messages": { "get": { "operationId": "listChatMessages", "tags": [ "Chat" ], "summary": "Chat messages", "description": "Returns stored chat messages for an account. Requires an ownership proof: get a challenge from /chat/auth/challenge, sign it, and pass account, challenge, and sig. Optional ?since (unix nanoseconds).", "parameters": [ { "name": "account", "in": "query", "required": true, "description": "Account address, 64 hex characters.", "schema": { "type": "string" }, "example": "26740934b57627b340fd881710fbca3ab70f662e18a20fd21d4773aa6c56c06b" }, { "name": "pub_key", "in": "query", "required": true, "description": "Hex ed25519 public key of `account`. Required: an address is a hash of the key and cannot verify a signature on its own.", "schema": { "type": "string" } }, { "name": "challenge", "in": "query", "required": true, "description": "Single-use challenge from GET /chat/auth/challenge.", "schema": { "type": "string" } }, { "name": "sig", "in": "query", "required": true, "description": "ed25519 signature over sha256(\"xe/chat-read-auth/v1\\0\" || challenge) by the account key, hex.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only messages newer than this unix-nanosecond timestamp.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Stored messages.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatMessageList" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing credentials for a gated endpoint. `error.code` is `unauthorized`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credentials present but not sufficient (wrong admin token, failed ownership proof). `error.code` is `forbidden`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ownershipProof": [] } ] } }, "/chat/contacts": { "get": { "operationId": "listChatContacts", "tags": [ "Chat" ], "summary": "Chat contacts", "description": "Returns the addresses an account has exchanged messages with. A named account requires an ownership proof (account, challenge, sig); with no account it lists every account with stored chat history, which is operator-only and returns 403 without the admin token.", "parameters": [ { "name": "account", "in": "query", "required": false, "description": "Account address, 64 hex characters.", "schema": { "type": "string" }, "example": "26740934b57627b340fd881710fbca3ab70f662e18a20fd21d4773aa6c56c06b" }, { "name": "pub_key", "in": "query", "required": false, "description": "Hex ed25519 public key of `account`. Required: an address is a hash of the key and cannot verify a signature on its own.", "schema": { "type": "string" } }, { "name": "challenge", "in": "query", "required": false, "description": "Single-use challenge from GET /chat/auth/challenge.", "schema": { "type": "string" } }, { "name": "sig", "in": "query", "required": false, "description": "ed25519 signature over sha256(\"xe/chat-read-auth/v1\\0\" || challenge) by the account key, hex.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Contact addresses.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatContactList" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing credentials for a gated endpoint. `error.code` is `unauthorized`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credentials present but not sufficient (wrong admin token, failed ownership proof). `error.code` is `forbidden`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ownershipProof": [] } ] } }, "/chat/events": { "get": { "operationId": "streamChatEvents", "tags": [ "Chat" ], "summary": "Chat event stream", "description": "SSE stream of new messages. A named account requires an ownership proof (account, challenge, sig); with no account it is the unfiltered firehose, which is operator-only and returns 403 without the admin token.", "parameters": [ { "name": "account", "in": "query", "required": false, "description": "Account address, 64 hex characters.", "schema": { "type": "string" }, "example": "26740934b57627b340fd881710fbca3ab70f662e18a20fd21d4773aa6c56c06b" }, { "name": "pub_key", "in": "query", "required": false, "description": "Hex ed25519 public key of `account`. Required: an address is a hash of the key and cannot verify a signature on its own.", "schema": { "type": "string" } }, { "name": "challenge", "in": "query", "required": false, "description": "Single-use challenge from GET /chat/auth/challenge.", "schema": { "type": "string" } }, { "name": "sig", "in": "query", "required": false, "description": "ed25519 signature over sha256(\"xe/chat-read-auth/v1\\0\" || challenge) by the account key, hex.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Server-sent events, one `ChatMessage` JSON object per event.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing credentials for a gated endpoint. `error.code` is `unauthorized`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credentials present but not sufficient (wrong admin token, failed ownership proof). `error.code` is `forbidden`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ownershipProof": [] } ] } }, "/node": { "get": { "operationId": "getNodeInfo", "tags": [ "Node" ], "summary": "Node info", "description": "Returns node identity, build version, network id, peer count, genesis hashes, the active lease timing windows (`lease_timing`) and, in provider mode, the current performance certificate summary.", "parameters": [], "responses": { "200": { "description": "Node info.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NodeInfo" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/health": { "get": { "operationId": "getHealth", "tags": [ "Node" ], "summary": "Health (liveness)", "description": "Liveness: the process is up and its internal loops (vote, sync, discovery) are running. Says nothing about consensus. Returns 503 with `ok: false` when a loop has stalled.", "parameters": [], "responses": { "200": { "description": "Liveness report.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthReport" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ready": { "get": { "operationId": "getReadiness", "tags": [ "Node" ], "summary": "Ready (readiness)", "description": "Readiness: synced, peered (≥ --ready-min-peers, default 1), delegated vote weight present, quorum reachable and finality advancing (stall threshold --ready-finality-stall, default 180 s). Returns 503 with the failing checks when not ready — the probe load balancers and systemd should use.", "parameters": [], "responses": { "200": { "description": "Readiness report.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadyReport" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/supply": { "get": { "operationId": "getSupply", "tags": [ "Node" ], "summary": "Supply", "description": "Aggregate supply per asset in micro-units and the conservation identity the node checks: balances + in_flight + locked_stake + burned + escrow_burned + stake_forfeited == genesis + minted + emitted. `genesis_supply` is the authority for the 42,000,000 XE figure; treat `stable: false` as retry.", "parameters": [], "responses": { "200": { "description": "Supply per asset.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplyReport" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/network/activations": { "get": { "operationId": "getNetworkActivations", "tags": [ "Node" ], "summary": "Feature activations", "description": "`sys.activations` as of the state-chain tip (activated features and protocol version), plus the feature set this build implements. Features listed as active but not implemented mean the node must upgrade.", "parameters": [], "responses": { "200": { "description": "Activation state.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivationsReport" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/network/readiness": { "get": { "operationId": "getNetworkReadiness", "tags": [ "Node" ], "summary": "Upgrade readiness", "description": "Delegated vote weight grouped by advertised node version and supported feature — the gate the DAO reads before signing a `sys.activations` update.", "parameters": [], "responses": { "200": { "description": "Weight by version and feature.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkReadiness" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pending/{address}": { "get": { "operationId": "listPendingForAccount", "tags": [ "Node" ], "summary": "Pending for account", "description": "Returns finalized sends addressed to an account that it has not yet received — what the account's next receive blocks should reference as `source`.", "parameters": [ { "name": "address", "in": "path", "required": true, "description": "Account address, 64 hex characters.", "schema": { "type": "string" }, "example": "26740934b57627b340fd881710fbca3ab70f662e18a20fd21d4773aa6c56c06b" } ], "responses": { "200": { "description": "Unreceived sends to the account.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingForAccount" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pending": { "get": { "operationId": "listPending", "tags": [ "Node" ], "summary": "All pending sends", "description": "Returns every unreceived send known to the node, across all accounts.", "parameters": [], "responses": { "200": { "description": "All unreceived sends.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingSendList" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/frontiers": { "get": { "operationId": "listFrontiers", "tags": [ "Node" ], "summary": "Frontiers", "description": "Returns the frontier (head block) of every known account chain — hash, block type, timestamp, block count and representative — sorted by address and paginated.", "parameters": [ { "name": "offset", "in": "query", "required": false, "description": "Number of entries to skip.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of entries to return.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Frontier per account.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Frontiers" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/delegation": { "get": { "operationId": "getDelegation", "tags": [ "Node" ], "summary": "Delegation weights", "description": "Returns representative vote weights in micro-XE (final XE balances summed per representative), the quorum total, and any weight held by representatives excluded by a `sys.representatives` allowlist.", "parameters": [], "responses": { "200": { "description": "Representative → weight.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Delegation" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conflicts": { "get": { "operationId": "listConflicts", "tags": [ "Node" ], "summary": "Conflicts", "description": "Returns open account-chain conflicts: two or more blocks claiming the same `previous`, with the vote weight snapshot each has received so far. Paginated.", "parameters": [ { "name": "offset", "in": "query", "required": false, "description": "Number of entries to skip.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of entries to return.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Conflicts.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictList" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conflicts/{account}": { "get": { "operationId": "listConflictsForAccount", "tags": [ "Node" ], "summary": "Conflicts for account", "description": "Returns conflicts scoped to one account.", "parameters": [ { "name": "account", "in": "path", "required": true, "description": "Account address, 64 hex characters.", "schema": { "type": "string" }, "example": "26740934b57627b340fd881710fbca3ab70f662e18a20fd21d4773aa6c56c06b" } ], "responses": { "200": { "description": "Conflicts on that account chain.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictList" } } } }, "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "description": "Structured error returned by the test.network API proxy when the upstream node did not itself answer with JSON, or when the proxy rejected or could not complete the request. Upstream JSON error bodies are passed through unchanged.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "status", "message", "hint", "docs" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code, snake_case.", "examples": [ "not_found", "bad_request", "upstream_unavailable", "upstream_error" ] }, "status": { "type": "integer", "description": "HTTP status code, repeated in the body." }, "message": { "type": "string", "description": "Human-readable summary." }, "hint": { "type": "string", "description": "What to try next: the fix, the right endpoint, or where the answer lives." }, "docs": { "type": "string", "format": "uri", "description": "Link to the relevant documentation." }, "openapi": { "type": "string", "format": "uri", "description": "Link to this OpenAPI document." }, "upstream": { "type": "object", "description": "Present when the node answered with a non-JSON error: its status and body.", "properties": { "status": { "type": "integer" }, "body": { "type": "string" } } } } } } }, "Address": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "Hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "32 bytes, lower-case hex (64 characters)." }, "MicroUnits": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "Asset": { "type": "string", "enum": [ "XE", "XUSD" ], "description": "Asset code. XE is the native asset and the only one that carries vote weight; XUSD prices compute leases and is minted only by the operators' sys.minter accounts on the testnet." }, "Keyset": { "type": "object", "description": "A multisig keyset. `keys` are ed25519 public keys, not addresses; the account's address is the SHA-256 digest of the canonical keyset.", "required": [ "keys", "threshold" ], "properties": { "keys": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "ed25519 public key, lower-case hex. A credential, not an address." }, "minItems": 1 }, "threshold": { "type": "integer", "minimum": 1 } } }, "Account": { "type": "object", "description": "An account known to the node.", "required": [ "address" ], "properties": { "address": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "balances": { "type": "object", "description": "Per-asset balance in micro-units, including unfinalized inflows.", "additionalProperties": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." } }, "balance": { "type": "integer", "minimum": 0, "description": "Legacy single-asset field; prefer `balances`." }, "block_count": { "type": "integer", "description": "Number of blocks on the account chain." }, "frontier": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Hash of the newest block on the chain." }, "last_block_timestamp": { "type": "integer", "description": "unix nanoseconds" } }, "additionalProperties": true }, "AccountList": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } }, "Balances": { "type": "object", "description": "Per-asset balances for one account. `balances` includes unfinalized inflows; `spendable` counts only finalized (irreversible) funds and is the settlement figure.", "required": [ "address", "balances", "spendable", "final_height" ], "properties": { "address": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "balances": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." } }, "spendable": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." } }, "final_height": { "type": "integer", "description": "The account's finalized-block watermark." } } }, "Block": { "type": "object", "description": "An account-chain block. `type` selects the block kind; the remaining fields are those of the matching submission schema. Blocks read back from the node carry an added `finalized` flag.", "required": [ "type", "account", "hash" ], "properties": { "type": { "type": "string", "enum": [ "send", "receive", "lease", "lease_accept", "lease_settle", "lease_cancel", "lease_force_settle", "lease_renew", "multisig_open", "multisig_update", "burn", "mint", "genesis" ] }, "account": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "previous": { "type": "string", "description": "Hash of the previous block on this account chain, or \"0\" for the first block." }, "pub_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The account's ed25519 public key. Required on a single-key chain's first block (previous == \"0\"), where the node checks sha256(\"xe/account/v1\" || pub_key) == account; forbidden on every later block and on multisig blocks. Bound into the hash through the aux input." }, "representative": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Optional delegate address for vote weight; empty keeps the current delegation." }, "balance": { "type": "integer", "minimum": 0, "description": "Post-block balance of `asset` on this account, in micro-units." }, "timestamp": { "type": "integer", "description": "Block time as unix nanoseconds." }, "asset": { "type": "string", "enum": [ "XE", "XUSD" ], "description": "Asset code. XE is the native asset and the only one that carries vote weight; XUSD prices compute leases and is minted only by the operators' sys.minter accounts on the testnet." }, "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "sha256 of the block content, hex." }, "pow_nonce": { "type": "integer", "description": "Proof-of-work nonce satisfying the block difficulty (DefaultDifficulty 0xfffff80000000000, roughly one second of work)." }, "finalized": { "type": "boolean", "description": "Whether representatives have finalized this block." } }, "additionalProperties": true }, "BlockList": { "type": "array", "items": { "$ref": "#/components/schemas/Block" } }, "AccountChain": { "type": "object", "description": "An account's block chain, oldest first, with the full chain length.", "required": [ "address", "total", "blocks" ], "properties": { "address": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "total": { "type": "integer", "description": "Full chain length, so a page can be told from the whole." }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/Block" } } } }, "SubmitResult": { "type": "object", "description": "The stored block, echoed back on 201. A rejection carries `error` plus a `retryable` flag: 400 + false for a deterministically invalid block, 503 + true for a dependency this node has not synced yet.", "properties": { "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "32 bytes, lower-case hex (64 characters)." }, "finalized": { "type": "boolean" } }, "additionalProperties": true }, "Reputation": { "type": "object", "description": "Reputation aggregate for one account, built from on-chain lease activity. Eventually consistent across nodes.", "properties": { "version": { "type": "integer" }, "leases_accepted_as_provider": { "type": "integer" }, "leases_settled_as_provider": { "type": "integer" }, "lease_hours_settled_as_provider": { "type": "integer" }, "leases_unfulfilled_as_provider": { "type": "integer" }, "leases_accepted_as_consumer": { "type": "integer" }, "leases_settled_as_consumer": { "type": "integer" }, "leases_cancelled_as_consumer": { "type": "integer" }, "lease_hours_settled_as_consumer": { "type": "integer" }, "leases_unfulfilled_as_consumer": { "type": "integer" }, "first_activity_at": { "type": "integer", "description": "unix nanoseconds" }, "last_activity_at": { "type": "integer", "description": "unix nanoseconds" } }, "additionalProperties": true }, "ReputationList": { "type": "object", "description": "Reputation aggregates keyed by account address.", "additionalProperties": { "$ref": "#/components/schemas/Reputation" } }, "LeaseSegment": { "type": "object", "description": "One renewal of a lease: additional escrow and duration at the R locked for that segment.", "properties": { "cost": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "duration": { "type": "integer", "description": "Additional seconds." }, "certificate_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "32 bytes, lower-case hex (64 characters)." }, "locked_r": { "type": "integer", "description": "Emission rate R (×1000) locked from the oracle epoch at the attested time." }, "locked_payout_cap": { "type": "integer", "description": "Hermite payout cap locked with R; 0 when none." }, "locked_twap_milli": { "type": "integer", "description": "Epoch TWAP (milli-USD) locked with R; 0 when none." } }, "additionalProperties": true }, "Lease": { "type": "object", "description": "A compute lease and its lifecycle state. `stake` is 0 on the current network (no provider stake); `renewals` lists every lease_renew applied so far.", "properties": { "lease_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Hash of the lease block; the lease's identifier." }, "state": { "type": "string", "enum": [ "created", "accepted", "settled", "cancelled", "unfulfilled", "expired" ] }, "consumer": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "provider": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "cost": { "type": "integer", "minimum": 0, "description": "XUSD escrowed for the base term, in micro-units." }, "stake": { "type": "integer", "minimum": 0, "description": "Provider stake; 0 on the current network." }, "start_time": { "type": "integer", "description": "unix nanoseconds; set at acceptance" }, "settled": { "type": "boolean" }, "certificate_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "32 bytes, lower-case hex (64 characters)." }, "locked_r": { "type": "integer", "description": "Emission rate R (×1000) locked from the oracle epoch at the attested time." }, "locked_payout_cap": { "type": "integer", "description": "Hermite payout cap locked with R; 0 when none." }, "locked_twap_milli": { "type": "integer", "description": "Epoch TWAP (milli-USD) locked with R; 0 when none." }, "renewals": { "type": "array", "items": { "$ref": "#/components/schemas/LeaseSegment" } }, "vcpus": { "type": "integer", "minimum": 1 }, "memory_mb": { "type": "integer", "minimum": 1 }, "disk_gb": { "type": "integer", "minimum": 1 }, "duration": { "type": "integer", "minimum": 1, "description": "Lease duration in seconds." }, "access_pub_key": { "type": "string", "description": "Hex ed25519 public key used to authenticate VM access (SSH, TCP tunnel)." } }, "additionalProperties": true }, "LeaseList": { "type": "array", "items": { "$ref": "#/components/schemas/Lease" } }, "Provider": { "type": "object", "description": "A compute provider and its current utilization. `used_*` and `active_leases` count accepted, unfinished leases only.", "properties": { "account": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Provider address: the `destination` of a lease block." }, "vcpus": { "type": "integer" }, "memory_mb": { "type": "integer" }, "disk_gb": { "type": "integer" }, "max_concurrent_leases": { "type": "integer" }, "used_vcpus": { "type": "integer" }, "used_memory_mb": { "type": "integer" }, "used_disk_gb": { "type": "integer" }, "active_leases": { "type": "integer" }, "total_leases": { "type": "integer" }, "timestamp": { "type": "integer", "description": "unix nanoseconds of the advertisement" } }, "additionalProperties": true }, "ProviderList": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } }, "Certificate": { "type": "object", "description": "A provider performance certificate: the benchmark a lease is priced against. Valid for 7 days from `issued_at`.", "properties": { "provider": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "provider_pub_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "ed25519 public key, lower-case hex. A credential, not an address." }, "seed": { "type": "string" }, "workload_version": { "type": "integer", "examples": [ 4 ] }, "puzzles": { "type": "integer", "examples": [ 1024 ] }, "work_proof": { "type": "string" }, "cpu_hash": { "type": "string" }, "score": { "type": "number", "description": "1 / elapsed seconds." }, "start_attestation_root": { "type": "string" }, "end_attestation_root": { "type": "string" }, "start_median": { "type": "integer" }, "end_median": { "type": "integer" }, "issued_at": { "type": "integer", "description": "unix nanoseconds" }, "expires_at": { "type": "integer", "description": "unix nanoseconds" }, "price_multiplier_milli": { "type": "integer", "minimum": 500, "maximum": 10000, "description": "Provider price multiplier ×1000; 1000 is baseline." }, "signature": { "type": "string" }, "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "32 bytes, lower-case hex (64 characters)." } }, "additionalProperties": true }, "CertificateNonces": { "type": "object", "description": "The CPU-phase witness for a certificate: one solving nonce per chained puzzle, in chain order. Only the issuing node holds it.", "properties": { "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "32 bytes, lower-case hex (64 characters)." }, "seed": { "type": "string" }, "puzzles": { "type": "integer" }, "cpu_hash": { "type": "string" }, "nonces": { "type": "array", "items": { "type": "integer" } } } }, "CertificateAttestations": { "type": "object", "description": "The full start and end timekeeper attestations behind a certificate's merkle roots.", "properties": { "start": { "type": "array", "items": { "$ref": "#/components/schemas/Attestation" } }, "end": { "type": "array", "items": { "$ref": "#/components/schemas/Attestation" } } } }, "Vm": { "type": "object", "description": "A VM record held by a provider for a lease.", "properties": { "lease_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "32 bytes, lower-case hex (64 characters)." }, "status": { "type": "string", "examples": [ "running" ] }, "resources": { "type": "object", "properties": { "vcpus": { "type": "integer" }, "memory_mb": { "type": "integer" }, "disk_gb": { "type": "integer" } } }, "created_at": { "type": "integer", "description": "unix nanoseconds" } }, "additionalProperties": true }, "VmList": { "type": "array", "items": { "$ref": "#/components/schemas/Vm" } }, "StateBlock": { "type": "object", "description": "A state-chain op block signed by the DAO keyset.", "properties": { "index": { "type": "integer", "minimum": 0 }, "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "32 bytes, lower-case hex (64 characters)." }, "ops": { "$ref": "#/components/schemas/StateOps" } }, "additionalProperties": true }, "StateBlockPage": { "type": "object", "description": "A page of state-chain blocks with the total block count.", "properties": { "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/StateBlock" } }, "count": { "type": "integer" } }, "additionalProperties": true }, "StateOps": { "type": "array", "items": { "type": "object", "required": [ "action", "key" ], "properties": { "action": { "type": "string", "enum": [ "set", "delete" ] }, "key": { "type": "string", "examples": [ "sys.network_id", "sys.minter" ] }, "value": { "type": "string" } } } }, "StateBlockSubmission": { "type": "object", "description": "A state-chain block signed by the current DAO keyset threshold.", "required": [ "ops", "signatures" ], "properties": { "ops": { "$ref": "#/components/schemas/StateOps" }, "signatures": { "type": "array", "description": "One entry per signing key; at least `threshold` are required.", "items": { "type": "object", "required": [ "public_key", "signature" ], "properties": { "public_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "ed25519 public key, lower-case hex. A credential, not an address." }, "signature": { "type": "string", "description": "ed25519 signature over the block hash, hex." } } } } } }, "StateValue": { "type": "object", "description": "One state-chain key/value entry.", "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": true }, "StateValueList": { "type": "array", "items": { "$ref": "#/components/schemas/StateValue" } }, "DirectoryEntry": { "type": "object", "description": "A signed account-to-libp2p-peer registration. Entries expire 30 minutes after `timestamp` unless refreshed.", "properties": { "account": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "pub_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "ed25519 public key, lower-case hex. A credential, not an address." }, "node_peer": { "type": "string", "description": "libp2p peer id, e.g. 12D3KooW…" }, "timestamp": { "type": "integer", "description": "unix nanoseconds" }, "signature": { "type": "string" } }, "additionalProperties": true }, "DirectoryEntryList": { "type": "array", "items": { "$ref": "#/components/schemas/DirectoryEntry" } }, "DirectoryRegistration": { "type": "object", "description": "Self-certifying registration: the node checks sha256(\"xe/account/v1\" || pub_key) == account before verifying the signature over sha256(\"xe/directory-registration/v1\\0\" || len‖network_id ‖ len‖account ‖ len‖pub_key ‖ len‖node_peer ‖ len‖timestamp), each length an 8-byte big-endian prefix.", "required": [ "account", "pub_key", "node_peer", "timestamp", "signature" ], "properties": { "account": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "pub_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The account's ed25519 public key; required because an address cannot verify its own signature." }, "node_peer": { "type": "string", "description": "Your libp2p peer id, e.g. 12D3KooW…" }, "timestamp": { "type": "integer", "description": "unix nanoseconds; decimal string in the signed payload" }, "signature": { "type": "string", "description": "ed25519 signature by the account key over the registration payload, hex." } } }, "ChatMessage": { "type": "object", "description": "A pre-signed, PoW-solved chat envelope. The node never signs on a caller's behalf. The envelope id is sha256(f(from) || f(pub_key) || f(to) || f(message) || u64be(timestamp)) with f(x) a 4-byte big-endian length prefix; the signature and the proof of work are both over that id, and each id is accepted once.", "required": [ "from", "pub_key", "to", "message", "timestamp", "signature" ], "properties": { "from": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "pub_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The sender's ed25519 public key; must derive `from`." }, "to": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Recipient address; must currently be registered in the directory." }, "message": { "type": "string" }, "timestamp": { "type": "integer", "description": "unix nanoseconds; within ±5 minutes of the node's clock" }, "signature": { "type": "string", "description": "ed25519 signature by `from` over the envelope id, hex." }, "pow_nonce": { "type": "integer", "description": "Nonce solving the node's `chat_pow_difficulty` over the envelope id. Required when that difficulty is non-zero." }, "id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Envelope id; computed by the node on ingest and present on stored envelopes." } } }, "ChatMessageList": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" } }, "ChatSendResult": { "type": "object", "description": "Acknowledgement of an accepted envelope.", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true } } }, "ChatChallenge": { "type": "object", "description": "A single-use challenge, valid for 120 seconds and bound to the issuing node. Sign sha256(\"xe/chat-read-auth/v1\\0\" || challenge_bytes) with the account key and pass account, pub_key, challenge and sig to the chat read endpoints.", "required": [ "challenge", "expires_at" ], "properties": { "challenge": { "type": "string", "description": "hex" }, "expires_at": { "type": "integer", "description": "unix nanoseconds" } } }, "ChatContactList": { "type": "array", "description": "Addresses the account has exchanged messages with, deduplicated and sorted.", "items": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." } }, "NodeInfo": { "type": "object", "description": "Node identity, version, network, consensus liveness and the lease timing in force. `address` is the node's ledger account; `public_key` its verifying key. Health gates must assert total_delegated_weight > 0 AND finality_advances rising.", "required": [ "id", "address", "version", "network_id" ], "properties": { "id": { "type": "string", "description": "libp2p peer id.", "examples": [ "12D3KooWJg4PQYGSfNCupBWZdEWbKj7pgdp5MmmUXbPdBcp6YDtT" ] }, "address": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The node's own account address." }, "public_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The node's ed25519 public key, hex." }, "version": { "type": "string", "examples": [ "xe/805d279" ] }, "network_id": { "type": "string", "description": "Network identifier; changes on every testnet wipe.", "examples": [ "testnet-0005" ] }, "peers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "address": { "type": "string" }, "version": { "type": "string" }, "connected_at": { "type": "integer" } }, "additionalProperties": true } }, "peer_count": { "type": "integer" }, "accounts": { "type": "integer", "description": "Accounts known to the node." }, "block_count": { "type": "integer" }, "total_delegated_weight": { "type": "integer", "minimum": 0, "description": "Total delegated vote weight in micro-XE. Zero means nothing can finalize." }, "representatives": { "type": "integer" }, "finality_advances": { "type": "integer", "description": "Final-height watermark advances since process start." }, "last_finality_ns": { "type": "integer", "description": "unix nanoseconds; 0 until the first advance" }, "pow_difficulty": { "type": "string", "description": "Block proof-of-work target, hex.", "examples": [ "fffff80000000000" ] }, "chat_pow_difficulty": { "type": "string", "description": "Chat proof-of-work target, hex.", "examples": [ "ffffc00000000000" ] }, "lease_timing": { "type": "object", "description": "Lease lifecycle timings in force on this network, set by its genesis.", "properties": { "min_duration_secs": { "type": "integer", "examples": [ 5 ] }, "settle_grace_ns": { "type": "integer", "examples": [ 120000000000 ] }, "force_settle_gap_ns": { "type": "integer", "examples": [ 300000000000 ] }, "escrow_expiry_ns": { "type": "integer", "examples": [ 3600000000000 ] }, "archive_gap_ns": { "type": "integer", "examples": [ 600000000000 ] }, "max_attestation_skew_ns": { "type": "integer", "examples": [ 60000000000 ] } } }, "certificate": { "type": "object", "description": "This node's own performance certificate. A provider reporting valid=false cannot be leased from.", "properties": { "valid": { "type": "boolean" }, "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "32 bytes, lower-case hex (64 characters)." }, "expires_at": { "type": "integer" } } } }, "additionalProperties": true }, "HealthReport": { "type": "object", "description": "Liveness only: the process is up and its loops run. Says nothing about consensus — a node with zero delegated weight finalizes nothing and still reports healthy here. 200 when live, 503 when not.", "required": [ "status", "ok", "checks" ], "properties": { "status": { "type": "string", "enum": [ "ok", "unhealthy" ] }, "ok": { "type": "boolean" }, "version": { "type": "string" }, "network_id": { "type": "string" }, "node_id": { "type": "string" }, "uptime_seconds": { "type": "number" }, "checks": { "$ref": "#/components/schemas/CheckList" }, "note": { "type": "string" } }, "additionalProperties": true }, "ReadyReport": { "type": "object", "description": "Readiness: can this node serve a correct answer? Synced, peered, delegated weight present, quorum reachable, finality advancing. 200 when ready, 503 when not, same body either way. Safe to drain a load balancer on; never wire a supervisor restart to it.", "required": [ "status", "ready", "checks" ], "properties": { "status": { "type": "string", "enum": [ "ready", "not_ready" ] }, "ready": { "type": "boolean" }, "checks": { "$ref": "#/components/schemas/CheckList" }, "peer_count": { "type": "integer" }, "delegated_weight_micro_xe": { "type": "integer" }, "active_representative_weight_micro_xe": { "type": "integer" }, "representatives": { "type": "integer" }, "active_representatives": { "type": "integer" }, "quorum_margin_ratio": { "type": "number", "description": "active ÷ total − 0.67; below 0 finality halts." }, "finality_stall_seconds": { "type": "number" }, "finality_advances": { "type": "integer" }, "unfinalized_positions": { "type": "integer" }, "conflicts_open": { "type": "integer" }, "frontier_fingerprint": { "type": "string", "description": "Parity digest; equal across agreeing nodes." }, "sample_age_seconds": { "type": "number" } }, "additionalProperties": true }, "CheckList": { "type": "array", "items": { "type": "object", "required": [ "name", "ok", "evaluated" ], "properties": { "name": { "type": "string" }, "ok": { "type": "boolean" }, "evaluated": { "type": "boolean", "description": "Always true today; exists so a check that cannot answer must say so." }, "detail": { "type": "string" } } } }, "AssetSupply": { "type": "object", "description": "Both sides of the conservation identity for one asset, in micro-units: balances + in_flight + locked_stake + burned + escrow_burned + stake_forfeited == genesis + minted + emitted.", "properties": { "genesis": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "minted": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "emitted": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "created": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "burned": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "escrow_burned": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "stake_forfeited": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "destroyed": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "locked_stake": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "balances": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "in_flight": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "observed": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "accounted": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "discrepancy": { "type": "integer", "description": "Signed accounted − created; zero iff conserved." }, "conserved": { "type": "boolean" } }, "additionalProperties": true }, "SupplyReport": { "type": "object", "description": "Aggregate supply per asset with the conservation identity checked. `genesis_supply` is the authority for the 42,000,000 XE figure; `stable: false` means retry, not pass.", "required": [ "genesis_supply", "assets", "conserved", "stable" ], "properties": { "genesis_supply": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count.", "examples": [ 42000000000000 ] }, "assets": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/AssetSupply" } }, "accounts": { "type": "integer" }, "blocks": { "type": "integer" }, "leases": { "type": "integer" }, "pending": { "type": "integer" }, "conserved": { "type": "boolean", "description": "AND over every asset; false whenever any term could not be computed." }, "notes": { "type": "array", "items": { "type": "string" } }, "stable": { "type": "boolean", "description": "Frontier set identical before and after the walk." }, "attempts": { "type": "integer" }, "computed_at": { "type": "integer", "description": "unix nanoseconds" }, "duration_ms": { "type": "integer" } }, "additionalProperties": true }, "ActivationsReport": { "type": "object", "description": "The sys.activations registry rendered against this node's state-chain tip, plus what this binary implements. Alert on a non-empty `unsupported_active`.", "properties": { "tip_index": { "type": "integer" }, "tip_timestamp": { "type": "integer" }, "features": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "at_index": { "type": "integer" }, "not_before_ns": { "type": "integer" }, "active": { "type": "boolean" }, "known_to_binary": { "type": "boolean" } } } }, "known_features": { "type": "array", "items": { "type": "string" } }, "gated_block_types": { "type": "object", "additionalProperties": { "type": "string" } }, "unsupported_active": { "type": [ "array", "null" ], "items": { "type": "string" } }, "unsupported_pending": { "type": [ "array", "null" ], "items": { "type": "string" } }, "min_protocol_version": { "type": [ "string", "null" ] }, "protocol_version": { "type": "string", "examples": [ "1.0.0" ] } }, "additionalProperties": true }, "NetworkReadiness": { "type": "object", "description": "Delegated vote weight behind each advertised protocol version and feature — what an activation is gated on (≥ 90% for 7 days). Count `unknown_weight` as not ready.", "properties": { "total_weight": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "feature_weight": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." } }, "feature_ready_milli": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Per-thousand; the 90% gate reads as >= 900." }, "version_weight": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string" }, "weight": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." } } } }, "unknown_weight": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "resolved_reps": { "type": "integer" }, "total_reps": { "type": "integer" } }, "additionalProperties": true }, "PendingSend": { "type": "object", "description": "A send whose receive has not yet been published.", "properties": { "SendHash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "32 bytes, lower-case hex (64 characters)." }, "Source": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "Destination": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "Amount": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "Asset": { "type": "string", "enum": [ "XE", "XUSD" ], "description": "Asset code. XE is the native asset and the only one that carries vote weight; XUSD prices compute leases and is minted only by the operators' sys.minter accounts on the testnet." }, "Timestamp": { "type": "integer", "description": "unix nanoseconds; present on GET /pending only" } }, "additionalProperties": true }, "PendingSendList": { "type": "array", "description": "Sends whose receive has not yet been published.", "items": { "$ref": "#/components/schemas/PendingSend" } }, "PendingForAccount": { "type": "object", "required": [ "address", "pending" ], "properties": { "address": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "pending": { "type": "array", "items": { "$ref": "#/components/schemas/PendingSend" } } } }, "Frontier": { "type": "object", "description": "The newest block on one account chain.", "properties": { "account": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "frontier": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "32 bytes, lower-case hex (64 characters)." }, "block_type": { "type": "string" }, "timestamp": { "type": "integer" }, "block_count": { "type": "integer" }, "representative": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." } }, "additionalProperties": true }, "Frontiers": { "type": "array", "items": { "$ref": "#/components/schemas/Frontier" } }, "Delegation": { "type": "object", "description": "Representative vote weights in micro-XE, split by quorum eligibility. `total_weight` is the quorum denominator. Keys are representative addresses.", "properties": { "weights": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." } }, "total_weight": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "ineligible_weights": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." } }, "ineligible_weight": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "eligibility_restricted": { "type": "boolean", "description": "A sys.representatives allowlist is in force." }, "eligibility_failed_open": { "type": "boolean", "description": "An allowlist is published but matched zero weight and is being ignored. Should always be false." } }, "additionalProperties": true }, "Conflict": { "type": "object", "description": "Two or more blocks claiming the same `previous` on one account chain, awaiting representative-weighted resolution.", "properties": { "account_address": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "previous_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "32 bytes, lower-case hex (64 characters)." }, "block_hashes": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "32 bytes, lower-case hex (64 characters)." }, "maxItems": 10 }, "detected_at": { "type": "string", "format": "date-time" }, "weight_snapshot": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." } }, "total_weight": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." } }, "additionalProperties": true }, "ConflictList": { "type": "array", "items": { "$ref": "#/components/schemas/Conflict" } }, "LeaseRequest": { "type": "object", "description": "Operator-only: asks the node to build, sign and PoW a lease from its own wallet. At least one of vcpus/memory_mb/disk_gb must be ≥ 1; duration is required.", "required": [ "duration" ], "properties": { "vcpus": { "type": "integer", "minimum": 1 }, "memory_mb": { "type": "integer", "minimum": 1 }, "disk_gb": { "type": "integer", "minimum": 1 }, "duration": { "type": "integer", "minimum": 1, "description": "Lease duration in seconds." }, "access_pub_key": { "type": "string", "description": "Hex ed25519 public key used to authenticate VM access (SSH, TCP tunnel)." } } }, "LeaseRequestResult": { "type": "object", "required": [ "lease_hash" ], "properties": { "lease_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "32 bytes, lower-case hex (64 characters)." } } }, "LeaseRenewRequest": { "type": "object", "description": "Operator-only: renew an accepted lease from the node's own wallet.", "required": [ "additional_secs" ], "properties": { "additional_secs": { "type": "integer", "minimum": 1, "description": "Additional seconds; the cost is priced at the provider's current certificate." } } }, "LeaseRenewResult": { "type": "object", "required": [ "renew_hash", "lease_hash", "cost", "duration" ], "properties": { "renew_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Hash of the stored lease_renew block." }, "lease_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "32 bytes, lower-case hex (64 characters)." }, "cost": { "type": "integer", "minimum": 0, "description": "Additional XUSD escrowed." }, "duration": { "type": "integer", "description": "Additional seconds." } } }, "AttestationRequest": { "type": "object", "required": [ "lease_hash" ], "properties": { "lease_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Hash of the lease block to attest timing for." } } }, "Attestation": { "type": "object", "description": "A timekeeper attestation: ed25519 over sha256(lease_hash || timestamp). `public_key` is a raw key matched against sys.timekeepers, not an address. Rate limited to one per lease per client every 15 s.", "required": [ "public_key", "timestamp", "signature" ], "properties": { "public_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "ed25519 public key, lower-case hex. A credential, not an address." }, "timestamp": { "type": "integer", "description": "unix nanoseconds" }, "signature": { "type": "string" } } }, "SendBlock": { "type": "object", "description": "Moves `amount` of `asset` from `account` to `destination`. The destination must differ from the sending account. Optional `memo` of up to 64 UTF-8 bytes is part of the signed content.", "required": [ "type", "account", "previous", "balance", "timestamp", "asset", "hash", "pow_nonce", "signature", "destination", "amount" ], "properties": { "type": { "type": "string", "const": "send" }, "account": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "previous": { "type": "string", "description": "Hash of the previous block on this account chain, or \"0\" for the first block." }, "pub_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The account's ed25519 public key. Required on a single-key chain's first block (previous == \"0\"), where the node checks sha256(\"xe/account/v1\" || pub_key) == account; forbidden on every later block and on multisig blocks. Bound into the hash through the aux input." }, "representative": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Optional delegate address for vote weight; empty keeps the current delegation." }, "balance": { "type": "integer", "minimum": 0, "description": "Post-block balance of `asset` on this account, in micro-units." }, "timestamp": { "type": "integer", "description": "Block time as unix nanoseconds." }, "asset": { "type": "string", "enum": [ "XE", "XUSD" ], "description": "Asset code. XE is the native asset and the only one that carries vote weight; XUSD prices compute leases and is minted only by the operators' sys.minter accounts on the testnet." }, "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "sha256 of the block content, hex." }, "pow_nonce": { "type": "integer", "description": "Proof-of-work nonce satisfying the block difficulty (DefaultDifficulty 0xfffff80000000000, roughly one second of work)." }, "destination": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Receiving account address." }, "amount": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "signature": { "type": "string", "description": "ed25519 signature over the block hash, hex." } } }, "ReceiveBlock": { "type": "object", "description": "Claims a pending send. `source` is the hash of the send block being received. When this is the account's first block (previous == \"0\") it must also declare `pub_key`.", "required": [ "type", "account", "previous", "balance", "timestamp", "asset", "hash", "pow_nonce", "signature", "source" ], "properties": { "type": { "type": "string", "const": "receive" }, "account": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "previous": { "type": "string", "description": "Hash of the previous block on this account chain, or \"0\" for the first block." }, "pub_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The account's ed25519 public key. Required on a single-key chain's first block (previous == \"0\"), where the node checks sha256(\"xe/account/v1\" || pub_key) == account; forbidden on every later block and on multisig blocks. Bound into the hash through the aux input." }, "representative": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Optional delegate address for vote weight; empty keeps the current delegation." }, "balance": { "type": "integer", "minimum": 0, "description": "Post-block balance of `asset` on this account, in micro-units." }, "timestamp": { "type": "integer", "description": "Block time as unix nanoseconds." }, "asset": { "type": "string", "enum": [ "XE", "XUSD" ], "description": "Asset code. XE is the native asset and the only one that carries vote weight; XUSD prices compute leases and is minted only by the operators' sys.minter accounts on the testnet." }, "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "sha256 of the block content, hex." }, "pow_nonce": { "type": "integer", "description": "Proof-of-work nonce satisfying the block difficulty (DefaultDifficulty 0xfffff80000000000, roughly one second of work)." }, "source": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Hash of the pending send block." }, "signature": { "type": "string", "description": "ed25519 signature over the block hash, hex." } } }, "LeaseBlock": { "type": "object", "description": "Consumer-signed. Escrows XUSD to a provider for a VM with the requested resources. `amount` must equal core.LeaseCost(vcpus, memory_mb, disk_gb, duration, provider certificate multiplier) exactly — per-minute billing, see /docs/compute.", "required": [ "type", "account", "previous", "balance", "timestamp", "asset", "hash", "pow_nonce", "signature", "destination", "amount", "certificate_hash", "vcpus", "memory_mb", "disk_gb", "duration", "access_pub_key" ], "properties": { "type": { "type": "string", "const": "lease" }, "account": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "previous": { "type": "string", "description": "Hash of the previous block on this account chain, or \"0\" for the first block." }, "pub_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The account's ed25519 public key. Required on a single-key chain's first block (previous == \"0\"), where the node checks sha256(\"xe/account/v1\" || pub_key) == account; forbidden on every later block and on multisig blocks. Bound into the hash through the aux input." }, "representative": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Optional delegate address for vote weight; empty keeps the current delegation." }, "balance": { "type": "integer", "minimum": 0, "description": "Post-block balance of `asset` on this account, in micro-units." }, "timestamp": { "type": "integer", "description": "Block time as unix nanoseconds." }, "asset": { "type": "string", "enum": [ "XE", "XUSD" ], "description": "Asset code. XE is the native asset and the only one that carries vote weight; XUSD prices compute leases and is minted only by the operators' sys.minter accounts on the testnet." }, "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "sha256 of the block content, hex." }, "pow_nonce": { "type": "integer", "description": "Proof-of-work nonce satisfying the block difficulty (DefaultDifficulty 0xfffff80000000000, roughly one second of work)." }, "destination": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Provider address." }, "amount": { "type": "integer", "minimum": 0, "description": "XUSD escrowed for the lease, in micro-units." }, "certificate_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Hash of the provider's current performance certificate (GET /certificate/{provider}); the lease is priced against its multiplier." }, "vcpus": { "type": "integer", "minimum": 1 }, "memory_mb": { "type": "integer", "minimum": 1 }, "disk_gb": { "type": "integer", "minimum": 1 }, "duration": { "type": "integer", "minimum": 1, "description": "Lease duration in seconds." }, "access_pub_key": { "type": "string", "description": "Hex ed25519 public key used to authenticate VM access (SSH, TCP tunnel)." }, "signature": { "type": "string", "description": "ed25519 signature over the block hash, hex." } } }, "LeaseAcceptBlock": { "type": "object", "description": "Provider-signed. Accepts a lease, pinning the provider's current performance certificate and locking the emission parameters from the epoch at the attested time. No stake is moved on the current network.", "required": [ "type", "account", "previous", "balance", "timestamp", "asset", "hash", "pow_nonce", "signature", "source", "certificate_hash", "locked_r", "locked_payout_cap", "locked_twap_milli", "attestations" ], "properties": { "type": { "type": "string", "const": "lease_accept" }, "account": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "previous": { "type": "string", "description": "Hash of the previous block on this account chain, or \"0\" for the first block." }, "pub_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The account's ed25519 public key. Required on a single-key chain's first block (previous == \"0\"), where the node checks sha256(\"xe/account/v1\" || pub_key) == account; forbidden on every later block and on multisig blocks. Bound into the hash through the aux input." }, "representative": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Optional delegate address for vote weight; empty keeps the current delegation." }, "balance": { "type": "integer", "minimum": 0, "description": "Post-block balance of `asset` on this account, in micro-units." }, "timestamp": { "type": "integer", "description": "Block time as unix nanoseconds." }, "asset": { "type": "string", "enum": [ "XE", "XUSD" ], "description": "Asset code. XE is the native asset and the only one that carries vote weight; XUSD prices compute leases and is minted only by the operators' sys.minter accounts on the testnet." }, "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "sha256 of the block content, hex." }, "pow_nonce": { "type": "integer", "description": "Proof-of-work nonce satisfying the block difficulty (DefaultDifficulty 0xfffff80000000000, roughly one second of work)." }, "source": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Hash of the lease block this block refers to." }, "certificate_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Hash of the provider's current, unexpired performance certificate." }, "locked_r": { "type": "integer", "description": "Emission rate R (×1000) locked from the oracle epoch at the attested time." }, "locked_payout_cap": { "type": "integer", "description": "Hermite payout cap locked with R; 0 when none." }, "locked_twap_milli": { "type": "integer", "description": "Epoch TWAP (milli-USD) locked with R; 0 when none." }, "attestations": { "type": "array", "description": "Timekeeper attestations over sha256(lease_hash || timestamp); the median timestamp is the block's attested time. At most 20.", "maxItems": 20, "items": { "$ref": "#/components/schemas/Attestation" } }, "signature": { "type": "string", "description": "ed25519 signature over the block hash, hex." } } }, "LeaseRenewBlock": { "type": "object", "description": "Consumer-signed. Extends an accepted lease in place: `amount` is the additional XUSD (priced at the provider's current certificate for `duration` more seconds), attested before the lease's effective expiry. Cumulative duration may not exceed 365 days.", "required": [ "type", "account", "previous", "balance", "timestamp", "asset", "hash", "pow_nonce", "signature", "source", "amount", "duration", "certificate_hash", "locked_r", "locked_payout_cap", "locked_twap_milli", "attestations" ], "properties": { "type": { "type": "string", "const": "lease_renew" }, "account": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "previous": { "type": "string", "description": "Hash of the previous block on this account chain, or \"0\" for the first block." }, "pub_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The account's ed25519 public key. Required on a single-key chain's first block (previous == \"0\"), where the node checks sha256(\"xe/account/v1\" || pub_key) == account; forbidden on every later block and on multisig blocks. Bound into the hash through the aux input." }, "representative": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Optional delegate address for vote weight; empty keeps the current delegation." }, "balance": { "type": "integer", "minimum": 0, "description": "Post-block balance of `asset` on this account, in micro-units." }, "timestamp": { "type": "integer", "description": "Block time as unix nanoseconds." }, "asset": { "type": "string", "enum": [ "XE", "XUSD" ], "description": "Asset code. XE is the native asset and the only one that carries vote weight; XUSD prices compute leases and is minted only by the operators' sys.minter accounts on the testnet." }, "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "sha256 of the block content, hex." }, "pow_nonce": { "type": "integer", "description": "Proof-of-work nonce satisfying the block difficulty (DefaultDifficulty 0xfffff80000000000, roughly one second of work)." }, "source": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Hash of the lease block this block refers to." }, "amount": { "type": "integer", "minimum": 0, "description": "Additional XUSD escrowed, in micro-units." }, "duration": { "type": "integer", "minimum": 1, "description": "Additional seconds." }, "certificate_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Hash of the provider's current performance certificate." }, "locked_r": { "type": "integer", "description": "Emission rate R (×1000) locked from the oracle epoch at the attested time." }, "locked_payout_cap": { "type": "integer", "description": "Hermite payout cap locked with R; 0 when none." }, "locked_twap_milli": { "type": "integer", "description": "Epoch TWAP (milli-USD) locked with R; 0 when none." }, "attestations": { "type": "array", "description": "Timekeeper attestations over sha256(lease_hash || timestamp); the median timestamp is the block's attested time. At most 20.", "maxItems": 20, "items": { "$ref": "#/components/schemas/Attestation" } }, "signature": { "type": "string", "description": "ed25519 signature over the block hash, hex." } } }, "LeaseSettleBlock": { "type": "object", "description": "Provider-signed. Settles an expired lease within the settle grace: mints the XE emission summed over the base term and every renewal, and burns the XUSD escrow. `amount` is the XE emitted.", "required": [ "type", "account", "previous", "balance", "timestamp", "asset", "hash", "pow_nonce", "signature", "source", "amount", "attestations" ], "properties": { "type": { "type": "string", "const": "lease_settle" }, "account": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "previous": { "type": "string", "description": "Hash of the previous block on this account chain, or \"0\" for the first block." }, "pub_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The account's ed25519 public key. Required on a single-key chain's first block (previous == \"0\"), where the node checks sha256(\"xe/account/v1\" || pub_key) == account; forbidden on every later block and on multisig blocks. Bound into the hash through the aux input." }, "representative": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Optional delegate address for vote weight; empty keeps the current delegation." }, "balance": { "type": "integer", "minimum": 0, "description": "Post-block balance of `asset` on this account, in micro-units." }, "timestamp": { "type": "integer", "description": "Block time as unix nanoseconds." }, "asset": { "type": "string", "enum": [ "XE", "XUSD" ], "description": "Asset code. XE is the native asset and the only one that carries vote weight; XUSD prices compute leases and is minted only by the operators' sys.minter accounts on the testnet." }, "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "sha256 of the block content, hex." }, "pow_nonce": { "type": "integer", "description": "Proof-of-work nonce satisfying the block difficulty (DefaultDifficulty 0xfffff80000000000, roughly one second of work)." }, "source": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Hash of the lease block this block refers to." }, "amount": { "type": "integer", "minimum": 0, "description": "XE emission, in micro-units." }, "attestations": { "type": "array", "description": "Timekeeper attestations over sha256(lease_hash || timestamp); the median timestamp is the block's attested time. At most 20.", "maxItems": 20, "items": { "$ref": "#/components/schemas/Attestation" } }, "signature": { "type": "string", "description": "ed25519 signature over the block hash, hex." } } }, "LeaseCancelBlock": { "type": "object", "description": "Consumer cancels a lease. Only the consumer can cancel, and only before the lease is accepted; the escrow is refunded in full.", "required": [ "type", "account", "previous", "balance", "timestamp", "asset", "hash", "pow_nonce", "signature", "source" ], "properties": { "type": { "type": "string", "const": "lease_cancel" }, "account": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "previous": { "type": "string", "description": "Hash of the previous block on this account chain, or \"0\" for the first block." }, "pub_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The account's ed25519 public key. Required on a single-key chain's first block (previous == \"0\"), where the node checks sha256(\"xe/account/v1\" || pub_key) == account; forbidden on every later block and on multisig blocks. Bound into the hash through the aux input." }, "representative": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Optional delegate address for vote weight; empty keeps the current delegation." }, "balance": { "type": "integer", "minimum": 0, "description": "Post-block balance of `asset` on this account, in micro-units." }, "timestamp": { "type": "integer", "description": "Block time as unix nanoseconds." }, "asset": { "type": "string", "enum": [ "XE", "XUSD" ], "description": "Asset code. XE is the native asset and the only one that carries vote weight; XUSD prices compute leases and is minted only by the operators' sys.minter accounts on the testnet." }, "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "sha256 of the block content, hex." }, "pow_nonce": { "type": "integer", "description": "Proof-of-work nonce satisfying the block difficulty (DefaultDifficulty 0xfffff80000000000, roughly one second of work)." }, "source": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Hash of the lease block this block refers to." }, "signature": { "type": "string", "description": "ed25519 signature over the block hash, hex." } } }, "LeaseForceSettleBlock": { "type": "object", "description": "Consumer recovers the full escrow from a lease the provider never settled, once expiry + settle grace + force-settle gap has passed and before the escrow expiry closes the refund window.", "required": [ "type", "account", "previous", "balance", "timestamp", "asset", "hash", "pow_nonce", "signature", "source", "attestations" ], "properties": { "type": { "type": "string", "const": "lease_force_settle" }, "account": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "previous": { "type": "string", "description": "Hash of the previous block on this account chain, or \"0\" for the first block." }, "pub_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The account's ed25519 public key. Required on a single-key chain's first block (previous == \"0\"), where the node checks sha256(\"xe/account/v1\" || pub_key) == account; forbidden on every later block and on multisig blocks. Bound into the hash through the aux input." }, "representative": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Optional delegate address for vote weight; empty keeps the current delegation." }, "balance": { "type": "integer", "minimum": 0, "description": "Post-block balance of `asset` on this account, in micro-units." }, "timestamp": { "type": "integer", "description": "Block time as unix nanoseconds." }, "asset": { "type": "string", "enum": [ "XE", "XUSD" ], "description": "Asset code. XE is the native asset and the only one that carries vote weight; XUSD prices compute leases and is minted only by the operators' sys.minter accounts on the testnet." }, "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "sha256 of the block content, hex." }, "pow_nonce": { "type": "integer", "description": "Proof-of-work nonce satisfying the block difficulty (DefaultDifficulty 0xfffff80000000000, roughly one second of work)." }, "source": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Hash of the lease block this block refers to." }, "attestations": { "type": "array", "description": "Timekeeper attestations over sha256(lease_hash || timestamp); the median timestamp is the block's attested time. At most 20.", "maxItems": 20, "items": { "$ref": "#/components/schemas/Attestation" } }, "signature": { "type": "string", "description": "ed25519 signature over the block hash, hex." } } }, "MultisigOpenBlock": { "type": "object", "description": "Opens a multisig account. `signatures` replaces the single `signature`.", "required": [ "type", "account", "previous", "balance", "timestamp", "asset", "hash", "pow_nonce", "signatures", "keyset" ], "properties": { "type": { "type": "string", "const": "multisig_open" }, "account": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "previous": { "type": "string", "description": "Hash of the previous block on this account chain, or \"0\" for the first block." }, "pub_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The account's ed25519 public key. Required on a single-key chain's first block (previous == \"0\"), where the node checks sha256(\"xe/account/v1\" || pub_key) == account; forbidden on every later block and on multisig blocks. Bound into the hash through the aux input." }, "representative": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Optional delegate address for vote weight; empty keeps the current delegation." }, "balance": { "type": "integer", "minimum": 0, "description": "Post-block balance of `asset` on this account, in micro-units." }, "timestamp": { "type": "integer", "description": "Block time as unix nanoseconds." }, "asset": { "type": "string", "enum": [ "XE", "XUSD" ], "description": "Asset code. XE is the native asset and the only one that carries vote weight; XUSD prices compute leases and is minted only by the operators' sys.minter accounts on the testnet." }, "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "sha256 of the block content, hex." }, "pow_nonce": { "type": "integer", "description": "Proof-of-work nonce satisfying the block difficulty (DefaultDifficulty 0xfffff80000000000, roughly one second of work)." }, "keyset": { "type": "object", "description": "A multisig keyset. `keys` are ed25519 public keys, not addresses; the account's address is the SHA-256 digest of the canonical keyset.", "required": [ "keys", "threshold" ], "properties": { "keys": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "ed25519 public key, lower-case hex. A credential, not an address." }, "minItems": 1 }, "threshold": { "type": "integer", "minimum": 1 } } }, "signatures": { "type": "array", "description": "One entry per signing key; at least `threshold` are required.", "items": { "type": "object", "required": [ "public_key", "signature" ], "properties": { "public_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "ed25519 public key, lower-case hex. A credential, not an address." }, "signature": { "type": "string", "description": "ed25519 signature over the block hash, hex." } } } } } }, "MultisigUpdateBlock": { "type": "object", "description": "Rotates a multisig keyset; signed by the current keyset's threshold.", "required": [ "type", "account", "previous", "balance", "timestamp", "asset", "hash", "pow_nonce", "signatures", "keyset" ], "properties": { "type": { "type": "string", "const": "multisig_update" }, "account": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "previous": { "type": "string", "description": "Hash of the previous block on this account chain, or \"0\" for the first block." }, "pub_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The account's ed25519 public key. Required on a single-key chain's first block (previous == \"0\"), where the node checks sha256(\"xe/account/v1\" || pub_key) == account; forbidden on every later block and on multisig blocks. Bound into the hash through the aux input." }, "representative": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Optional delegate address for vote weight; empty keeps the current delegation." }, "balance": { "type": "integer", "minimum": 0, "description": "Post-block balance of `asset` on this account, in micro-units." }, "timestamp": { "type": "integer", "description": "Block time as unix nanoseconds." }, "asset": { "type": "string", "enum": [ "XE", "XUSD" ], "description": "Asset code. XE is the native asset and the only one that carries vote weight; XUSD prices compute leases and is minted only by the operators' sys.minter accounts on the testnet." }, "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "sha256 of the block content, hex." }, "pow_nonce": { "type": "integer", "description": "Proof-of-work nonce satisfying the block difficulty (DefaultDifficulty 0xfffff80000000000, roughly one second of work)." }, "keyset": { "type": "object", "description": "A multisig keyset. `keys` are ed25519 public keys, not addresses; the account's address is the SHA-256 digest of the canonical keyset.", "required": [ "keys", "threshold" ], "properties": { "keys": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "ed25519 public key, lower-case hex. A credential, not an address." }, "minItems": 1 }, "threshold": { "type": "integer", "minimum": 1 } } }, "signatures": { "type": "array", "description": "One entry per signing key; at least `threshold` are required.", "items": { "type": "object", "required": [ "public_key", "signature" ], "properties": { "public_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "ed25519 public key, lower-case hex. A credential, not an address." }, "signature": { "type": "string", "description": "ed25519 signature over the block hash, hex." } } } } } }, "BurnBlock": { "type": "object", "description": "Permanently destroys `amount` of XE (XE only).", "required": [ "type", "account", "previous", "balance", "timestamp", "asset", "hash", "pow_nonce", "signature", "amount" ], "properties": { "type": { "type": "string", "const": "burn" }, "account": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "previous": { "type": "string", "description": "Hash of the previous block on this account chain, or \"0\" for the first block." }, "pub_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The account's ed25519 public key. Required on a single-key chain's first block (previous == \"0\"), where the node checks sha256(\"xe/account/v1\" || pub_key) == account; forbidden on every later block and on multisig blocks. Bound into the hash through the aux input." }, "representative": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Optional delegate address for vote weight; empty keeps the current delegation." }, "balance": { "type": "integer", "minimum": 0, "description": "Post-block balance of `asset` on this account, in micro-units." }, "timestamp": { "type": "integer", "description": "Block time as unix nanoseconds." }, "asset": { "type": "string", "enum": [ "XE", "XUSD" ], "description": "Asset code. XE is the native asset and the only one that carries vote weight; XUSD prices compute leases and is minted only by the operators' sys.minter accounts on the testnet." }, "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "sha256 of the block content, hex." }, "pow_nonce": { "type": "integer", "description": "Proof-of-work nonce satisfying the block difficulty (DefaultDifficulty 0xfffff80000000000, roughly one second of work)." }, "amount": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "signature": { "type": "string", "description": "ed25519 signature over the block hash, hex." } } }, "MintBlock": { "type": "object", "description": "Mints XUSD. Only accounts listed under the state chain's `sys.minter` key are authorized; on the testnet those are operator accounts.", "required": [ "type", "account", "previous", "balance", "timestamp", "asset", "hash", "pow_nonce", "signature", "amount" ], "properties": { "type": { "type": "string", "const": "mint" }, "account": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Account address: sha256(\"xe/account/v1\" || ed25519 public key), lower-case hex." }, "previous": { "type": "string", "description": "Hash of the previous block on this account chain, or \"0\" for the first block." }, "pub_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The account's ed25519 public key. Required on a single-key chain's first block (previous == \"0\"), where the node checks sha256(\"xe/account/v1\" || pub_key) == account; forbidden on every later block and on multisig blocks. Bound into the hash through the aux input." }, "representative": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Optional delegate address for vote weight; empty keeps the current delegation." }, "balance": { "type": "integer", "minimum": 0, "description": "Post-block balance of `asset` on this account, in micro-units." }, "timestamp": { "type": "integer", "description": "Block time as unix nanoseconds." }, "asset": { "type": "string", "enum": [ "XE", "XUSD" ], "description": "Asset code. XE is the native asset and the only one that carries vote weight; XUSD prices compute leases and is minted only by the operators' sys.minter accounts on the testnet." }, "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "sha256 of the block content, hex." }, "pow_nonce": { "type": "integer", "description": "Proof-of-work nonce satisfying the block difficulty (DefaultDifficulty 0xfffff80000000000, roughly one second of work)." }, "amount": { "type": "integer", "minimum": 0, "description": "Amount in micro-units. 1 XE = 1 XUSD = 1,000,000 micro-units; every amount, balance and weight in the API is an integer micro-unit count." }, "signature": { "type": "string", "description": "ed25519 signature over the block hash, hex." } } } }, "headers": { "X-API-Version": { "description": "Major API version that served the request (currently 1). Unversioned /api paths report the version they resolved to.", "schema": { "type": "integer", "example": 1 } }, "RateLimit-Policy": { "description": "Rate-limit policy in force for this request class (draft-ietf-httpapi-ratelimit-headers): \"name\";q=;w=.", "schema": { "type": "string", "example": "\"read\";q=1000;w=5" } }, "RateLimit": { "description": "Current quota state (draft-ietf-httpapi-ratelimit-headers): \"name\";r=;t=. Throttle when r approaches 0.", "schema": { "type": "string", "example": "\"read\";r=998;t=4" } }, "RateLimit-Limit": { "description": "Quota for the window (legacy RateLimit-* form of RateLimit-Policy q).", "schema": { "type": "integer", "example": 1000 } }, "RateLimit-Remaining": { "description": "Requests remaining in the window (legacy form of RateLimit r).", "schema": { "type": "integer", "example": 998 } }, "RateLimit-Reset": { "description": "Seconds until the window resets (legacy form of RateLimit t).", "schema": { "type": "integer", "example": 4 } }, "Retry-After": { "description": "Seconds to wait before retrying. Sent with every 429.", "schema": { "type": "integer", "example": 4 } }, "Deprecation": { "description": "Present only on deprecated endpoints or versions (RFC 9745): the date deprecation took effect, as @. Accompanied by Sunset and a Link rel=\"deprecation\".", "schema": { "type": "string", "example": "@1767225600" } }, "Sunset": { "description": "Present only on deprecated endpoints or versions (RFC 8594): the HTTP-date after which the endpoint is removed, at least 90 days after Deprecation.", "schema": { "type": "string", "example": "Wed, 01 Apr 2026 00:00:00 GMT" } } }, "responses": { "400": { "description": "Bad request: malformed JSON, a body that fails the operation's schema, or an unsigned/invalid block. `error.code` is `bad_request`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing credentials for a gated endpoint. `error.code` is `unauthorized`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credentials present but not sufficient (wrong admin token, failed ownership proof). `error.code` is `forbidden`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such route or object (unknown path, unknown account, or a lease hash the node does not know). `error.code` is `not_found`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded for the request class. Back off for Retry-After seconds; RateLimit reports the window. Policies: read 1000/5s, write 50/5s. `error.code` is `rate_limited`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The node failed while handling the request. `error.code` is `upstream_error`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The node could not be reached or answered with a non-HTTP error. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The node is temporarily unavailable. `error.code` is `upstream_unavailable`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The node did not answer in time. `error.code` is `upstream_timeout`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other error. The node's own JSON error bodies pass through unchanged; every non-JSON error is wrapped in the `Error` shape by the test.network proxy, so a 4xx/5xx body is always JSON with a machine-readable `error.code`.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "securitySchemes": { "adminToken": { "type": "http", "scheme": "bearer", "description": "Operator-only endpoints take `Authorization: Bearer `. The token belongs to the node operator; the public London node does not hand it out." }, "ownershipProof": { "type": "apiKey", "in": "query", "name": "sig", "description": "Chat reads prove account ownership with query parameters: `account`, `pub_key`, a single-use `challenge` from GET /chat/auth/challenge, and `sig` = ed25519 signature over sha256(\"xe/chat-read-auth/v1\\0\" || challenge) by the account key." }, "leaseAccessSignature": { "type": "apiKey", "in": "header", "name": "X-Signature", "description": "ed25519 signature over the 32 decoded lease-hash bytes with the lease's access key." } } }, "x-versioning": { "scheme": "url-path", "current": "v1", "versionedBase": "https://test.network/api/v1", "unversionedBase": "https://test.network/api", "docs": "https://test.network/developers#versioning", "rules": [ "The version is the first path segment after /api: https://test.network/api/v1/node. Every response also carries X-API-Version: 1.", "Unversioned paths (https://test.network/api/node) are an alias for the current major version and follow it when it changes; integrations that must not move pin the versioned path.", "Within a major version changes are additive only: new endpoints, new optional fields, new enum values. Clients must ignore fields they do not know. Removing or renaming a field, changing a type, or changing an endpoint's meaning happens only in a new major version.", "When a new major version ships, the previous one keeps working for at least 180 days.", "Deprecated endpoints and versions are announced in the OpenAPI document (`deprecated: true`) and on every response with a Deprecation header (RFC 9745, `Deprecation: @`), a Sunset header (RFC 8594, HTTP-date of removal) and a `Link: ; rel=\"deprecation\"` pointing at the migration notes. Sunset is never less than 90 days after the Deprecation date.", "Testnet wipes reset ledger state, not the API: identifiers change, the contract does not.", "The direct node endpoint https://ldn.core.test.network is unversioned and tracks the node release; the versioned contract is the https://test.network/api surface described by https://test.network/openapi.json." ] }, "x-rate-limits": { "docs": "https://test.network/developers#rate-limits", "scope": "per client IP, per request class", "policies": [ { "name": "read", "quota": 1000, "windowSeconds": 5, "description": "GET and HEAD requests: 1,000 per 5 seconds per client IP (200/s sustained)." }, { "name": "write", "quota": 50, "windowSeconds": 5, "description": "POST, PUT, PATCH and DELETE requests: 50 per 5 seconds per client IP (10/s sustained)." } ], "headers": [ "RateLimit-Policy", "RateLimit", "RateLimit-Limit", "RateLimit-Remaining", "RateLimit-Reset" ], "onExceeded": "429 with Retry-After and an Error body (code rate_limited)" } }