Quickstart

This page takes you from no key to a first answer in a few minutes. You need a hodlflow account: get access with your Google account first.

1. Make an API key.

   Open scope.hodlflow.app/settings/keys and choose Continue with Google. Create a key with a name and a lifetime of 30 days, 90 days or 1 year.

   The key starts with hf_ and is shown once. Copy it and store it somewhere only you can read, such as your OS credential store.

2. Put the key in an environment variable.

   The examples read it from HODLFLOW_API_KEY.

   macOS / Linux

   export HODLFLOW_API_KEY='hf_...'

   Windows PowerShell

   $env:HODLFLOW_API_KEY = 'hf_...'

3. Check coverage and your budget.

   GET /v1/meta returns the last block of each network, every command with its options, your limits and the budget left today. It costs no query time.

   curl -s https://api.hodlflow.app/v1/meta \
     -H "Authorization: Bearer $HODLFLOW_API_KEY" \
     -H "User-Agent: my-case-tool/1.0"

4. Run a query.

   Queries are POST /v1/{chain}/{command} with a JSON body. This one lists the 20 largest senders of USDT to a Tron address:

   curl

   curl -s https://api.hodlflow.app/v1/tron/topk \
     -H "Authorization: Bearer $HODLFLOW_API_KEY" \
     -H "User-Agent: my-case-tool/1.0" \
     -d '{"positional": ["TQtaugi3vfFuqxp8KCQUTyXDc6Smk1pYDJ"], "flags": {"dir": "in", "k": 20}}'

   Python

   import json, os, urllib.error, urllib.request
   
   def call(path, body=None):
       req = urllib.request.Request(
           "https://api.hodlflow.app" + path,
           data=None if body is None else json.dumps(body).encode(),
           headers={"Authorization": "Bearer " + os.environ["HODLFLOW_API_KEY"],
                    "User-Agent": "my-case-tool/1.0"})
       try:
           with urllib.request.urlopen(req, timeout=100) as r:
               return json.load(r)
       except urllib.error.HTTPError as e:
           return json.load(e)  # errors are JSON too
   
   top = call("/v1/tron/topk", {"positional": ["TQtaugi3vfFuqxp8KCQUTyXDc6Smk1pYDJ"],
                                "flags": {"dir": "in", "k": 20}})
   for row in top["rows"]:
       cp = row["counterparty"]
       print(cp["addr"], row["sum_f64"], row["symbol"], cp["entity"])

   JavaScript

   const res = await fetch("https://api.hodlflow.app/v1/tron/topk", {
     method: "POST",
     headers: {
       Authorization: `Bearer ${process.env.HODLFLOW_API_KEY}`,
       "User-Agent": "my-case-tool/1.0",
     },
     body: JSON.stringify({
       positional: ["TQtaugi3vfFuqxp8KCQUTyXDc6Smk1pYDJ"],
       flags: { dir: "in", k: 20 },
     }),
   });
   const top = await res.json();

5. Read the answer.

   Every answer starts with _meta. Keep request_id, dataset.max_block and labels.snapshot with any number you quote. Before quoting a total, check the completeness flags described in Reading results.

Why POST?

Queries only read data, but they use POST so that the addresses you investigate travel in the request body rather than in the URL, where proxies and logs would record them. A body also holds batches of up to 200 inputs and structured options that would not fit in a query string.

Next

• Tracing funds explains the trace methods and when to use each.
• Investigation workflow shows a typical sequence of calls and how to save budget.
• The API Reference lists every command and option.