fetch_balance

Returns balance information for one or more addresses. Request with application/json and a body that lists the addresses to query.

Endpoint

POST https://mempool.lineage.to/fetch_balance

Headers

Header	Type	Description
`x-cache-id`	string	Idempotency / cache key. Must match the documented pattern (32 lowercase hex characters, e.g. `^[a-z0-9]{32}$`). The response `id` matches this value.

Request body

JSON array of address strings. At least one address is required in typical usage.

["<address-1>", "<address-2>"]

Example

curl -sS -X POST "https://mempool.lineage.to/fetch_balance" \
  -H "Content-Type: application/json" \
  -H "x-cache-id: 0123456789abcdef0123456789abcdef" \
  -d '["<address-1>"]'

Responses

200 on success, 400 if the call could not be processed. The payload uses the standard envelope, with a structured content that includes per-token and per-address data; the exact nesting and asset names may differ by release.

Envelope fields (typical)

id — idempotency id (matches x-cache-id).
status — one of Success, Error, or Pending.
reason — human-readable detail; especially useful for errors.
route — logical route name for the call.
content — payload; shape depends on the operation.

Example success payload

{
  "id": "0123456789abcdef0123456789abcdef",
  "status": "Success",
  "reason": "Balances returned",
  "route": "fetch_balance",
  "content": {
    "balances": [
      {
        "address": "<address>",
        "assets": [
          { "name": "Token", "value": 1000 },
          { "name": "Item", "value": 0, "id": null }
        ]
      }
    ]
  }
}

Example error envelope (typical 400)

{
  "id": null,
  "status": "Error",
  "reason": "Bad Request",
  "route": null,
  "content": null
}