The Lineage HTTP API lets you integrate with the network directly: read chain state, submit transactions, and query node metadata. None of the flows in this documentation require on-chain smart contracts. Use a plain HTTP client (curl, fetch, or your language of choice) against the endpoints listed under each subsystem.

Routes are grouped by node class. Each class is served from its own origin, so confirm which host a route belongs to before you call it, as sending a storage read to the mempool host (or vice versa) will not resolve.

Public service URLs

These are the public reference hosts used in every example below.

Request & response envelope

Operations are POST to a path named after the route (for example/fetch_balance on the mempool host). Read-only routes take an empty body; routes that need input take a JSON body documented per endpoint. Every request carries two headers:

• Content-Type: application/json
• x-cache-id: a 32-character idempotency key matching ^[a-z0-9]{32}$.

Every response uses the same envelope. Field semantics:

Error envelope

{"id": null,"status": "Error","reason": "Bad Request","route": null,"content": null}

API quick start

Pick a node class, point your HTTP client at its base URL, and verify connectivity with a read-only route before sending anything that writes. A good first call isstorage latest_block ormempool fetch_balance.

# 1 — check the chain head on the storage hostcurl -sS -X POST "https://storage.lineage.to/latest_block" \ -H "Content-Type: application/json" \ -H "x-cache-id: 0123456789abcdef0123456789abcdef"\ -d ''

Node types

Lineage separates three roles so that who assembles a block, who stores history, and who expends hashrate this round are independent jobs.Mempool nodes collect transactions and coordinate validation;miner nodes perform proof-of-work to produce block candidates and earn rewards; storage nodes retain full chain history and serve reads to clients. The split enables fast settlement, geographic resilience, and specialised hardware without forcing archival storage on every participant.

Mempool node

A bounded set of long-lived components that accept user transactions, batch them into blocks, and work with the mining network. Each round, the mempool set advances valid transactions, agrees on ordering within protocol rules, hands a candidate to miners, then validates the winner's block and forwards it to storage. Mempool and miner responsibilities are interdependent, and both must make progress for the chain to advance.

Storage node

Keeps full chain history, receives valid blocks (typically along the mempool path), and replicates them for durability and API consumers. Its core job is persisting blocks and building indices for header, transaction-id, and proof lookups. Distributed consensus between storage operators keeps replicas agreeing on the same head, and witness data is preserved so light clients and auditors can re-check proofs.

Miner node

Miners compete to extend the chain when it is their turn. They receive work units from the mempool, find valid proofs, and return them so the mempool declares a winner and forwards the block to storage. The protocol does not require every miner to grind on the same block simultaneously; a subset is selected each round, keeping energy use proportionate. Rewards follow the network's token rules once a block is accepted.

Block mining

Producing a block is a multi-step collaboration: (1) client transactions are queued by the mempool; (2) when a round starts, a block body is built from the queue and offered to selected miners; (3) miners produce proofs and return candidates; (4) the mempool picks a winner, validates the block, and sends it to storage. A single per-round randomness object (a UNiCORN), derived from agreed inputs such as the transactions, the eligible miner set, and prior-round metadata, drives who may mine and who wins.

Transactions

Lineage uses a UTXO model: a transaction spends one or more previous outputs and creates new outputs that a later spend can refer to. There is no global account balance in the contract layer; a balance is a view over unspent outputs. Each input points at a previous transaction hash and output index with a script proving spend authorisation; each output states a locked value and its script (for example pay-to-pubkey-hash). Transactions carry a version and optional application-specific data (such as DRUID or item metadata) that higher layers interpret.

Two-way transactions

A two-way transaction lets two parties each contribute compatible halves to a single block, so an exchange or payment clears atomically without a smart-contract runtime. It is the mechanism for flows where both sides must sign before either side's funds move. Wallets and SDKs hide most of the wiring.

UNiCORN randomness

A UNiCORN, an UN-COntestable Random Number, is a randomness-and-witness object generated so that no single participant can steer it toward anything but a random result. It depends on the transactions in the block, which miners are eligible, and recent chain state, so winner selection is hard to bias without breaking consensus. The protocol uses it to restrict which miners may attempt work in a round, to choose the winning valid proof, and to supply the data storage nodes re-check during validation.

SDKs & tutorials

Beyond the raw endpoint reference, Lineage ships official client libraries in three languages plus node tooling. The full walkthroughs and runnable code live in the published repositories; the cards below summarise each SDK and where it fits. All three wrap the same HTTP API documented above; configure each with a mempool base URL, a storage base URL, and a passphrase for local key encryption.

Install

Add the client for your stack. Confirm the published package name in each repository's README.

# JavaScript / TypeScriptnpm install @lineage/sdk-js# Pythonpip install git+https://github.com/lineage-foundation/sdk-python# PHPcomposer require lineage-foundation/sdk-php

First call

Create a Wallet, point it at a mempool host with a passphrase for local key encryption, and initialise a new keypair. initNew returns the generated seed phrase. Store it securely; it is the only way to recover the wallet.

import { Wallet } from '@lineage/sdk-js';const wallet = new Wallet();const CONFIG = {mempoolHost: 'https://mempool.lineage.to', passphrase: 'a secure passphrase',}; wallet.initNew(CONFIG).then((res) => {console.log(res.content.initNewResponse.seedphrase);});

Running a node

The fastest way to stand up a full Lineage stack (mempool, storage, and miner) is the lineage-foundation/fleet repository, which ships a Docker Compose stack and a from-source build. The steps below mirror its README.

Prerequisites

A recent Rust toolchain and the Linux build dependencies. On Ubuntu:

sudo apt-get update && sudo apt-get install -y \ build-essential m4 llvm libclang-dev clang cmake pkg-config \ git curl python3 libglfw3-dev libxrandr-dev libxinerama-dev \ libxcursor-dev libxi-dev

# install Rustcurl https://sh.rustup.rs -sSf | sh source "$HOME/.cargo/env"rustc --version

Docker Compose (recommended)

Build and start the full multi-node stack from the repo root:

docker compose build docker compose up

This brings up three services:

Node configuration is read from ./.docker/conf/node_settings.toml (mounted to /etc/node_settings.toml). Point at a different file with the NODE_SETTINGS override:

NODE_SETTINGS=/absolute/path/to/node_settings.toml docker compose up

On Apple Silicon, select the ARM platform (default is linux/amd64):

FLEET_COMPOSE_PLATFORM=linux/arm64 docker compose up

Rebuild a single service, or tear the stack down and remove volumes:

docker compose build mempool-node docker compose down -v

Build from source

cargo build --release cargo test

Or build just the container image (distroless cc-debian13, runs as nonroot; binary at /lineage/lineage):

docker build -t fleet-node:local --platform linux/amd64 .