API overview

Base URL: https://api.hodlflow.app. Any HTTP client works: curl, Python requests, httpx or urllib, JavaScript fetch, and the like.

Endpoints

Method and path	Key	Answer
GET /v1	No	The endpoint index (JSON).
GET /v1/health	No	{"ok": true, "api_version": "v1"}
GET /v1/meta	Yes	Coverage per network, every command with its options and defaults, your limits and budget.
GET /v1/guide	Yes	The usage rules for AI agents (Markdown).
POST /v1/{chain}/{command}	Yes	The command’s answer (JSON).

{chain} is bitcoin, ethereum, tron or zcash. The commands are listed under Bitcoin, Ethereum, Tron and Zcash. Headers are described in Authentication.

Request body

The POST body is one JSON object of at most 64 KiB. Any other key is refused, and an empty body counts as {}.

Key	Type	Meaning
positional	array of strings	The command’s input: addresses or ids, or edge ids. Bitcoin and Zcash tx and Ethereum annotate take ["<block>", "<tx_index>"].
targets	array of strings	Batch inputs, one answer each. Bitcoin and Zcash tx rows are "<block> <tx_index>". Never together with positional.
flags	object	Option name → value.

{"positional": ["TQtaugi3vfFuqxp8KCQUTyXDc6Smk1pYDJ"], "flags": {"dir": "in", "k": 50, "time-start": 1682899200}}

Option values:

• Numbers as JSON numbers or strings; choices as strings.
• Switches as true. false is the same as leaving the option out.
• Label lists and pin-addr as one comma-separated string: "cex,exchange,bridge".
• An unknown option is refused with unknown_field, and error.next lists the options the command takes.

Response

• Success is HTTP 200 with one JSON object: the command’s answer with _meta as its first key. See Response fields.
• A targets request answers with the batch envelope.
• Answers are UTF-8. Labels can contain non-ASCII text, so read saved answers as UTF-8.
• An answer can be up to 16 MiB; beyond that the request is refused with limit_exceeded.
• Errors use the error envelope, including an unknown path (404) and a wrong method (405, with an Allow header).
• A non-JSON error page comes from the network edge, not the API: a 403 page means the User-Agent was refused; a 429 page means too many requests from your address (wait about 10 seconds).

Timeouts

A query runs for at most 60 seconds and may first wait up to 5 seconds for a free slot. Set your client timeout to at least 90 seconds.

Server defaults

Values marked (server) in the command tables are filled in by the server when you leave the option out, to keep shared queries bounded. They appear in _meta.defaults_overridden as name=value; passing the option yourself removes it from that list.

Numbers outside the documented ranges are refused with limit_exceeded. Label lists hold 1–20 names, each up to 64 characters of letters, digits, space and . _ - ( ) & ' / + :.

GET /v1/meta always has the live ranges and defaults. When this site and meta disagree, meta is right.