# Cosmos-SDK LCD Extractor (`datamule/cosmos-lcd-extractor`) Actor

Point at ANY Cosmos-SDK chain's LCD (REST) endpoint and extract validators, governance proposals, token supply, account balances, delegations, or inflation. Chain-agnostic across the Cosmos ecosystem; opaque next\_key pagination, gov v1/v1beta1 fallback, big-int amounts kept as strings.

- **URL**: https://apify.com/datamule/cosmos-lcd-extractor.md
- **Developed by:** [Datamule](https://apify.com/datamule) (community)
- **Categories:** Developer tools, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.35 / 1,000 chain records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Cosmos-SDK LCD Extractor

Point at **any** Cosmos-SDK chain's public **LCD** (REST / gRPC-gateway) endpoint and pull
structured data out of its core modules — no per-chain scraper, no RPC node to run. One actor
reads the whole ~60-chain Cosmos ecosystem because every Cosmos-SDK chain exposes the identical
`/cosmos/<module>/<version>/…` REST surface.

### What it does

Give it a chain's LCD base URL (e.g. `https://cosmos-rest.publicnode.com`, or
`https://rest.cosmos.directory/<chain>` — swap `<chain>` for `cosmoshub`, `osmosis`, `juno`,
`celestia`, `injective`, …) and pick a **module**:

| Module | Endpoint | One row per |
|---|---|---|
| `validators` | `/cosmos/staking/v1beta1/validators` | validator (moniker, tokens, commission, status, jailed, self-delegation) |
| `proposals` | `/cosmos/gov/v1/proposals` (auto-falls back to `v1beta1`) | governance proposal (title, status, tally, deposit, type) |
| `supply` | `/cosmos/bank/v1beta1/supply` | supply denom + amount |
| `balances` | `/cosmos/bank/v1beta1/balances/{address}` | account balance denom + amount |
| `delegations` | `/cosmos/staking/v1beta1/delegations/{address}` | delegation (validator, shares, balance) |
| `inflation` | `/cosmos/mint/v1beta1/inflation` | the chain's current annual inflation (single value) |

`balances` and `delegations` require an `address` (a bech32 account for the target chain).

### Why a generic runner works — and the gotchas it handles

Every Cosmos-SDK chain speaks the same module contract, but the **server** decides several
details that break naive clients:

- **Pagination is opaque `pagination.next_key` (base64), not an offset.** And `pagination.total`
  is very often `"0"` because chains disable the count for performance — so it is never used as a
  terminator. This actor loops purely on `next_key` (with a looping-cursor guard).
- **Governance version drift.** Newer chains serve `gov/v1` (`yes_count`, top-level `title`);
  older chains only serve `gov/v1beta1` (`yes`, `proposal_id`, title nested under `content`). The
  actor tries v1, falls back to v1beta1, and normalises both into one row shape.
- **Amounts are big-integer strings.** `tokens`, `delegator_shares`, supply/balance amounts and
  tally counts routinely exceed float precision, so they are kept verbatim as strings.
- **Pruned / non-Cosmos hosts fail loud.** An HTML/nginx error, a `501 not implemented` for a
  module the chain doesn't run, or a body missing the expected key → fail-fast (exit 91), never a
  fabricated empty result. A reachable, valid, genuinely-empty response (un-staked account, no
  open proposals) is an honest success with 0 rows.

### Output

One flat row per record with a lossless `_raw` copy of the source object and
`_module` / `_restUrl` / `_endpoint` / `_rowIndex` provenance. All source-derived fields are
nullable, so the six record types share one schema and render cleanly in a table view.

### Pricing

Pay-per-event: **$0.0005 per record** (one validator / proposal / supply denom / balance /
delegation), with a subscription-tier volume discount.

### Example input

```json
{
  "restUrl": "https://cosmos-rest.publicnode.com",
  "module": "validators",
  "status": "BOND_STATUS_BONDED",
  "maxRecords": 200
}
````

# Actor input Schema

## `restUrl` (type: `string`):

Base URL of ANY Cosmos-SDK chain's public LCD / REST (gRPC-gateway) endpoint. The module path is appended automatically. Examples: https://cosmos-rest.publicnode.com (Cosmos Hub) · https://rest.cosmos.directory/cosmoshub (the chain-registry proxy — swap the last segment for osmosis, juno, celestia, injective, …) · https://cosmos-api.polkachu.com. Every Cosmos-SDK chain exposes the same /cosmos/<module>/… REST, so one actor reads the whole ecosystem.

## `module` (type: `string`):

Which Cosmos-SDK module to read. validators = the staking validator set; proposals = governance proposals (auto-falls back from gov v1 to v1beta1 on older chains); supply = total token supply per denom; balances = an account's balances (requires address); delegations = an account's delegations (requires address); inflation = the chain's current annual inflation rate (single value).

## `address` (type: `string`):

Required for the 'balances' and 'delegations' modules: a bech32 account address for the target chain (e.g. cosmos1fl48vsnmsdzcv85q5d2q4z5ajdha8yu34mf0eh on Cosmos Hub, osmo1… on Osmosis). Ignored by the other modules.

## `status` (type: `string`):

Only for the 'validators' module: restrict to one bond status. Leave as 'Any' to return all validators (bonded, unbonding, and unbonded).

## `maxRecords` (type: `integer`):

Stop after emitting this many rows. Pagination through pagination.next\_key halts early once reached. Each emitted record (one validator / proposal / supply denom / balance / delegation) is billed as one record.

## `pageLimit` (type: `integer`):

How many items to request per page via pagination.limit. Cosmos LCD nodes typically cap this around 100; larger values may be silently reduced by the server.

## `userAgent` (type: `string`):

Override the default descriptive User-Agent header. Public LCD nodes are shared community infrastructure — please keep a descriptive agent and reasonable request rates.

## `timeoutSecs` (type: `integer`):

Per-request timeout in seconds for each LCD page fetch.

## Actor input object example

```json
{
  "restUrl": "https://cosmos-rest.publicnode.com",
  "module": "validators",
  "status": "",
  "maxRecords": 2000,
  "pageLimit": 100,
  "timeoutSecs": 60
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "restUrl": "https://cosmos-rest.publicnode.com"
};

// Run the Actor and wait for it to finish
const run = await client.actor("datamule/cosmos-lcd-extractor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "restUrl": "https://cosmos-rest.publicnode.com" }

# Run the Actor and wait for it to finish
run = client.actor("datamule/cosmos-lcd-extractor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "restUrl": "https://cosmos-rest.publicnode.com"
}' |
apify call datamule/cosmos-lcd-extractor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=datamule/cosmos-lcd-extractor",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Cosmos-SDK LCD Extractor",
        "description": "Point at ANY Cosmos-SDK chain's LCD (REST) endpoint and extract validators, governance proposals, token supply, account balances, delegations, or inflation. Chain-agnostic across the Cosmos ecosystem; opaque next_key pagination, gov v1/v1beta1 fallback, big-int amounts kept as strings.",
        "version": "0.1",
        "x-build-id": "JFTLUYlVJHPz7oMDg"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/datamule~cosmos-lcd-extractor/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-datamule-cosmos-lcd-extractor",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/datamule~cosmos-lcd-extractor/runs": {
            "post": {
                "operationId": "runs-sync-datamule-cosmos-lcd-extractor",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/datamule~cosmos-lcd-extractor/run-sync": {
            "post": {
                "operationId": "run-sync-datamule-cosmos-lcd-extractor",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "restUrl"
                ],
                "properties": {
                    "restUrl": {
                        "title": "Chain LCD (REST) base URL",
                        "type": "string",
                        "description": "Base URL of ANY Cosmos-SDK chain's public LCD / REST (gRPC-gateway) endpoint. The module path is appended automatically. Examples: https://cosmos-rest.publicnode.com (Cosmos Hub) · https://rest.cosmos.directory/cosmoshub (the chain-registry proxy — swap the last segment for osmosis, juno, celestia, injective, …) · https://cosmos-api.polkachu.com. Every Cosmos-SDK chain exposes the same /cosmos/<module>/… REST, so one actor reads the whole ecosystem."
                    },
                    "module": {
                        "title": "Module",
                        "enum": [
                            "validators",
                            "proposals",
                            "supply",
                            "balances",
                            "delegations",
                            "inflation"
                        ],
                        "type": "string",
                        "description": "Which Cosmos-SDK module to read. validators = the staking validator set; proposals = governance proposals (auto-falls back from gov v1 to v1beta1 on older chains); supply = total token supply per denom; balances = an account's balances (requires address); delegations = an account's delegations (requires address); inflation = the chain's current annual inflation rate (single value).",
                        "default": "validators"
                    },
                    "address": {
                        "title": "Account address (bech32)",
                        "type": "string",
                        "description": "Required for the 'balances' and 'delegations' modules: a bech32 account address for the target chain (e.g. cosmos1fl48vsnmsdzcv85q5d2q4z5ajdha8yu34mf0eh on Cosmos Hub, osmo1… on Osmosis). Ignored by the other modules."
                    },
                    "status": {
                        "title": "Validator bond status filter (optional)",
                        "enum": [
                            "",
                            "BOND_STATUS_BONDED",
                            "BOND_STATUS_UNBONDING",
                            "BOND_STATUS_UNBONDED"
                        ],
                        "type": "string",
                        "description": "Only for the 'validators' module: restrict to one bond status. Leave as 'Any' to return all validators (bonded, unbonding, and unbonded).",
                        "default": ""
                    },
                    "maxRecords": {
                        "title": "Max records",
                        "minimum": 1,
                        "type": "integer",
                        "description": "Stop after emitting this many rows. Pagination through pagination.next_key halts early once reached. Each emitted record (one validator / proposal / supply denom / balance / delegation) is billed as one record.",
                        "default": 2000
                    },
                    "pageLimit": {
                        "title": "Page size",
                        "minimum": 1,
                        "maximum": 1000,
                        "type": "integer",
                        "description": "How many items to request per page via pagination.limit. Cosmos LCD nodes typically cap this around 100; larger values may be silently reduced by the server.",
                        "default": 100
                    },
                    "userAgent": {
                        "title": "User-Agent (optional)",
                        "type": "string",
                        "description": "Override the default descriptive User-Agent header. Public LCD nodes are shared community infrastructure — please keep a descriptive agent and reasonable request rates."
                    },
                    "timeoutSecs": {
                        "title": "Request timeout (seconds)",
                        "minimum": 5,
                        "type": "integer",
                        "description": "Per-request timeout in seconds for each LCD page fetch.",
                        "default": 60
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```