Docs
v1

Reference

REST routes

Every HTTP route of the Tenrai node API and the Tenrai API, grouped by subject, with its parameters and what it returns.

On this page

All routes answer JSON. REST API explains the conventions, Errors the failures.

Node

MethodRouteReturns
GET/healthok while the service is up
GET/v1/node/infoVersion, network, chain ID, identity, storage mode, finalized cut
GET/v1/node/statusNetwork, chain ID, finalized cut, the rules of the next cut and the next scheduled upgrade
GET/v1/node/syncsynced, finalized_height, best_peer_height, behind_by, peers
GET/v1/node/peersConnected peers. Off on the Tenrai API
GET/v1/node/identityPublic key for checking signed answers
GET/v1/storageStorage mode and the oldest cut whose body is kept

Chain

MethodRouteReturns
GET/v1/chain/headFinalized head: height, cut ID, state root, validator set
GET/v1/chain/genesisThe genesis of this chain
GET/v1/chain/issuanceIssued supply
GET/v1/chain/epochCurrent epoch, its cuts, active validators and bonded stake
GET/v1/chain/daaDifficulty target and the controller's state
GET/v1/chain/ratesBlocks, transactions and cuts per second over 1, 10, 30 and 60 seconds, and the network hashrate
GET/v1/network/miningCurrent mining target, anchor and registration window
GET/v1/work/poolWork blocks the node holds and has queued

Economics and fees

MethodRouteReturns
GET/v1/economics/supplyMaximum, total and circulating supply, bonded, burned, reserves
GET/v1/economics/emissionSubsidy per cut and per interval, and the next reduction
GET/v1/economics/estimate/mining?hashes_per_second=Expected mining reward per day
GET/v1/economics/estimate/staking?amount=Expected staking reward per day for an amount in atoms
GET/v1/fees/quoteMinimum fee per mass and the largest transaction mass
GET/v1/fees/estimateFee suggestions for minimum, normal and priority

Cuts and blocks

MethodRouteReturns
GET/v1/cuts?before=&limit=Finalized cuts, newest first
GET/v1/cuts/{height}One cut
GET/v1/cuts/{height}/blocksThe work blocks it executed
GET/v1/cuts/{height}/transactions?cursor=&limit=The transactions it finalized
GET/v1/cuts/{height}/changes?cursor=&limit=Outputs it created and spent
GET/v1/cuts/{height}/addressesAddresses it changed
GET/v1/blocks/recent?limit=Newest work blocks
GET/v1/blocks/{id}One work block with its transactions and reward

Transactions

MethodRouteReturns
GET/v1/transactions/manifestRules for building a transaction: chain, limits, mass rules, minimum fee
POST/v1/transactionsSubmits {"api_version":1,"wire_hex":"…"}
GET/v1/transactions/{id}The transaction with inputs, outputs, payload and confirmations
GET/v1/transactions/{id}/statusLifecycle, work block, cuts, failure
POST/v1/transactions/statusStatus of up to 1,024 IDs: {"api_version":1,"transaction_ids":[…]}
GET/v1/transactions/recent?limit=Newest transactions the node has seen
GET/v1/mempoolMempool size and limits
GET/v1/mempool/transactions?limit=The transactions next in line
POST/v1/mempool/pendingUnconfirmed payments to up to 64 addresses

/v1/transactions/{id}, /v1/blocks/{id} and /v1/cuts/{height} carry confirmations, the finalized cuts since the record became final, counting that cut; work_confirmations, the work blocks registered in those cuts, up to 100,000; and finalized_at_millis.

Addresses

MethodRouteReturns
GET/v1/address/{address}/balanceFinalized balance and number of unspent outputs
GET/v1/address/{address}/utxos?cursor=&limit=Unspent outputs with the cut they are anchored to
GET/v1/address/{address}/history?cursor=&limit=Received and spent outputs, newest first
GET/v1/address/{address}/unbondingStake the address asked back and when it can be withdrawn
GET/v1/address/{address}/wordsThe six verification words
POST/v1/address/balancesBalances of up to 64 addresses
POST/v1/address/utxosUnspent outputs of up to 64 addresses
POST/v1/address/changesChanges of up to 64 addresses after a height
POST/v1/keys/registeredRegistered key references of up to 64 addresses
POST/v1/proofs/utxosMembership proofs for up to 8 outpoints at a finalized cut

The address batches take {"api_version":1,"addresses":[…]}; /v1/address/changes also takes "after_height".

Staking

MethodRouteReturns
GET/v1/staking/validators?cursor=&limit=Validators, total bonded, minimum delegation
GET/v1/staking/validators/{id}One validator
GET/v1/staking/validators/{id}/positions?cursor=&limit=Its positions, bonded total, self-bond, delegations and stakers
GET/v1/staking/uptimeHow many of the recent cuts each validator signed
GET/v1/staking/positions/{id}One stake position
POST/v1/staking/positions?cursor=&limit=Positions owned by, or paying rewards to, up to 64 addresses

Sockets

RouteCarries
/v1/wsRequests and subscriptions. Subprotocol tenrai.node-api.v1
/v1/eventsEvery finalized cut, resumable. Subprotocol tenrai.node-events.v1
/v1/transactions/{id}/status/streamOne transaction until it is final. Subprotocol tenrai.transaction-status.v1

See WebSocket events.

Tenrai API only

MethodRouteReturns
GET/v1/gateway/healthState of the service and its node
GET/v1/gateway/history?window=Network figures for charts; hour, day or week
GET/v1/gateway/priceTRAI price, its currency and when it was read; 0 without a source
GET/v1/gateway/price/historyThe price per minute for 10 minutes and per hour for 30 days
GET/v1/archive/statusArchived range, gaps and counts
GET/v1/archive/cuts?before=&limit=Archived cuts, newest first
GET/v1/archive/cuts/{height}One archived cut with its rewards

The archive routes exist while the service keeps an archive.

/v1/gateway/history returns the series height, blocks_per_second, transactions_per_second, hashes_per_second, cut_interval_millis, mempool_transactions, peers, difficulty, fee_per_mass, circulating_supply, bonded, cut_subsidy and active_validators.

WindowPointsStep
hour36010 s
day2885 min
week33630 min

Node only

Mining control runs on the node's loopback listener, port 28702. Tenrai API passes these two routes on only when it runs with --public-mining true: templates without transactions, one every 2 seconds and one found block per second for each client address.

MethodRouteUse
POST/v1/mining/templatesWork for a payout address
POST/v1/mining/candidatesSubmits a found block

Miners and pools reach these through tenrai-miner, the stratum bridge or the reference pool.

Type to search guides, concepts and reference pages.