The node API

Every ZooBC node serves one public HTTP API. It is how wallets, explorers, the command-line tools and any web page read the chain and submit transactions. Reading needs no key, no account and no API key, and the API answers pages hosted anywhere. Writing needs only a transaction signed by its sender.

The basics

• Where: plain HTTP/1.1 on port 8080 by default, with more than a hundred routes under /api/v1/. The node also serves the web wallet at / and /wallet.
• No TLS on the node: public sites reach the API over HTTPS through a gateway, which also puts an archival service in front for deep history.
• Open to every page: every response carries Access-Control-Allow-Origin: *, and the browser's OPTIONS check is answered at once, so a page on any domain can call the API (building an app as one HTML page).
• Mostly reads: all but eight routes are reads that need no authentication. Posting a transaction needs no API key, because the transaction carries its own signature.
• Limits per client address: 300 write requests a minute by default (beyond that the node answers 429 with a Retry-After header); reads are unlimited unless the operator sets a limit.

What you can read

All paths in the second column are under /api/v1/. /movements lists every change to an account's balance with its cause, including rent paid and rewards won. /pubkey returns a native account's public key from its address alone. Since version 0.5.8, chain routes report the finalized_height and each transaction a finalized flag, set once a co-signed spine block covers its block (finality and rollback).

Anyone can look up any address this way. The chain records keys, not names, so privacy on ZooBC comes from how addresses are used, not from hidden balances (accounts and addresses).

Submitting a transaction

A client builds the transaction's bytes, signs the chain-bound digest with the sender's key, using the genesis_hash read from /api/v1/node/info (signing a transaction), and posts the result to POST /api/v1/transactions. No SDK is needed: Ed25519, SHA3-256 and the genesis hash are enough.

The node answers HTTP 202, which means "accepted", not "done", and returns the transaction's hash. The client then polls /api/v1/transactions/<hash>/status, which moves through:

1. staging, then mempool, while the transaction waits for a block;
2. confirmed, with the block height, once a block includes it;
3. or rejected, with the reason and the stage, if it is refused; not_found (404) if the node does not know it.

At one block every 15 seconds, polling every couple of seconds is plenty. Before releasing goods against a payment, wait for confirmation, and preferably for the finalized flag.

If a reply is lost, resend the identical signed bytes. The hash is computed from those bytes, so a node that already holds the transaction, even one already included in a block, answers 202 again, marked as a duplicate, and it is executed only once. Signing again with a new timestamp creates a different transaction, which is how double payments happen.

Signed requests and cancellation

A few requests carry a signature of their own: an Ed25519 signature over METHOD:PATH:TIMESTAMP:BODY, valid for 300 seconds. A client that fails 20 signed authentications within 5 minutes is locked out for 300 seconds. A pending transaction can be withdrawn from one node's pool with a signed DELETE request (signed and encrypted messages).

Other interfaces of a node

• Port 8001: the peer-to-peer network between nodes.
• Port 8545: an Ethereum-style JSON-RPC adapter, on the node's own machine by default, used by MetaMask.
• Port 8332: a Bitcoin Core-style RPC adapter, off by default, that needs the operator's own credentials.

See also

• Building an app as one HTML page
• Command-line tools
• Gateways
• Signing a transaction
• The explorer and archival nodes