Optional /extended JSON
Clients that already call /extended keep that path. Same Postgres, off by default.
Subset, not a drop-in replica
Node RPC (/v2) is not this listener: no nonce. The full account /balances document (miner rewards, token offering, metadata) is not shipped. BNS reads are empty until BNS_DECODER_ENABLED=true. Missing fields (miner_txid, execution_cost_*, post_conditions, total_fees_sent) are omitted, never zeroed.
Only the value 1 enables it.
EXTENDED_VIEW=1
curl http://127.0.0.1:3999/extended/v1/status| Key | Default | Notes |
|---|---|---|
EXTENDED_VIEW | unset | Only 1 turns it on |
EXTENDED_PORT | 3999 | Positive integer |
Same process as /v1, second bind. Compose publishes 127.0.0.1:3999 and leaves the flag off, so the port refuses until you set it in .env.
{
"server_version": "secondlayer-extended/1.30.0",
"status": "ready",
"chain_tip": {
"block_height": 8054704,
"block_hash": "0xabc",
"index_block_hash": "0xdef",
"burn_block_height": 850000
}
}Empty chain omits chain_tip. status stays "ready".
These paths answer on :3999.
| Method | Path | Returns |
|---|---|---|
GET | /extended/v1/status | server_version, status, optional chain_tip |
GET | /extended/v1/block | List, height desc |
GET | /extended/v1/block/:hash | One block by hash or height. Includes txs |
GET | /extended/v1/tx | List. Optional from_height / to_height |
GET | /extended/v1/tx/:tx_id | One transaction |
GET | /extended/v1/tx/:tx_id/events | JSON array, event_index order |
GET | /extended/v1/address/:principal/transactions | Txs where sender is the principal |
GET | /extended/v1/address/:principal/stx | Decoded STX totals as strings. No nonce |
GET | /extended/v1/address/:principal/ft | Per-asset FT nets |
GET | /extended/v1/address/:principal/nft | Held { asset_identifier, value } |
GET | /extended/v1/tokens/nft/transfers | nft_transfer rows. Optional asset_identifier |
GET | /extended/v1/names | BNS by ?address=. Empty if the decoder is off |
GET | /extended/v1/names/:name | One FQN. {} if the decoder is off |
| Query | Default | Notes |
|---|---|---|
limit | 20 | Max 30 on block/tx lists; max 50 on nft transfers. Over → 400 |
offset | 0 | |
from_height, to_height | tx list only | |
asset_identifier | nft transfers only |
Lists use { limit, offset, total, results }, not the /v1 cursor envelope. /tx/:tx_id/events is a JSON array. cursor and from_cursor return 400.
/extended is not mounted on :3800. :3800/extended 404s with the /v1 body (code: "NOT_FOUND"). Errors on :3999 are { "error": "Not found" } with no code, path, or next_cursor.
| Bind | Reads |
|---|---|
| Loopback | Open, no token |
| Past loopback | INSTANCE_TOKEN |
Same rule as /v1. Tokens: Authentication.
Prefer Index unless you already have /extended clients.
| Surface | Port | Job |
|---|---|---|
/v1 | 3800 | Index, Streams, subgraphs. Envelope, cursors, signatures. |
/extended | 3999 | Optional JSON projection of Index rows. Off by default. |
Node RPC /v2 | 20443 | Nonce, call-read, broadcast. Point those at the node. |
No second Postgres. No extra API container.