Can I use CoinGecko as a CLI?

Yes. KosmoKrator exposes a CoinGecko CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose CoinGecko through MCP?

Yes. The KosmoKrator MCP gateway can expose selected CoinGecko tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are CoinGecko credentials stored?

CoinGecko credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for CoinGecko MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

data

CoinGecko Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the CoinGecko KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.coingecko.*. Use lua_read_doc("integrations.coingecko") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic CoinGecko workflow without starting an interactive agent session.

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.coingecko.api_get({path = "example_path", params = "example_params"}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("coingecko"))' --json
kosmo integrations:lua --eval 'print(docs.read("coingecko.api_get"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua

local coingecko = app.integrations.coingecko
local result = coingecko.api_get({path = "example_path", params = "example_params"})

dump(result)

Run the workflow

kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json

Namespace note. integrations:lua exposes app.integrations.coingecko, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.coingecko.default.* or app.integrations.coingecko.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need CoinGecko, use the narrower mcp:lua command.

MCP Lua command

# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

CoinGecko Lua Reference

CoinGecko tools expose API v3 market, exchange, category, asset-platform, and public treasury data. Use CoinGecko IDs (bitcoin, ethereum) rather than ticker symbols (BTC, ETH).

Common Discovery Flow

local search = app.integrations.coingecko.search_coins({ query = "solana" })
local coin_id = search.coins[1].id

local categories = app.integrations.coingecko.list_categories({})
local platforms = app.integrations.coingecko.list_asset_platforms({})

list_coins can return contract addresses when called with include_platform = "true":

local coins = app.integrations.coingecko.list_coins({
  params = { include_platform = "true" }
})

Prices And Markets

local price = app.integrations.coingecko.price({
  ids = "bitcoin,ethereum",
  currencies = "usd,eur"
})

local token_price = app.integrations.coingecko.simple_token_price({
  asset_platform_id = "ethereum",
  contract_addresses = "0x0000000000000000000000000000000000000000",
  currencies = "usd"
})

local markets = app.integrations.coingecko.markets({
  currency = "usd",
  category = "layer-1",
  per_page = "10",
  page = "1"
})

price and simple_token_price include market cap, 24h volume, 24h change, and last-updated fields where CoinGecko returns them.

Coin Detail And History

local info = app.integrations.coingecko.info({ id = "bitcoin" })
local tickers = app.integrations.coingecko.coin_tickers({
  id = "bitcoin",
  params = { page = 1 }
})

local history_date = app.integrations.coingecko.coin_history_date({
  id = "bitcoin",
  date = "30-12-2025"
})

local chart = app.integrations.coingecko.history({
  id = "bitcoin",
  currency = "usd",
  days = "30"
})

local ohlc = app.integrations.coingecko.ohlc({
  id = "bitcoin",
  currency = "usd",
  days = "30"
})

The existing info, markets, history, ohlc, search_coins, trending, and global tools return normalized summaries to keep agent output small. New endpoint-family tools return CoinGecko’s JSON shape directly.

Exchanges

local exchanges = app.integrations.coingecko.list_exchanges({
  params = { per_page = 25, page = 1 }
})

local exchange = app.integrations.coingecko.get_exchange({ id = "binance" })
local tickers = app.integrations.coingecko.get_exchange_tickers({
  id = "binance",
  params = { coin_ids = "bitcoin" }
})

local volume = app.integrations.coingecko.exchange_volume_chart({
  id = "binance",
  days = "30"
})

Use list_exchange_ids to discover exchange IDs before calling exchange-specific tools.

Categories, Rates, Global Data

local category_market = app.integrations.coingecko.categories_market_data({
  params = { order = "market_cap_desc" }
})

local rates = app.integrations.coingecko.exchange_rates({})
local trending = app.integrations.coingecko.trending({})
local global = app.integrations.coingecko.global({})
local defi = app.integrations.coingecko.global_defi({})

exchange_rates returns BTC-relative rates under rates.

Asset Platforms And Token Lists

local platforms = app.integrations.coingecko.list_asset_platforms({})
local token_list = app.integrations.coingecko.token_list({
  asset_platform_id = "ethereum"
})

Use asset platform IDs for token-price and token-list calls.

Public Treasury

local entities = app.integrations.coingecko.list_entities({})

local by_coin = app.integrations.coingecko.public_treasury_by_coin({
  entity = "companies",
  coin_id = "bitcoin",
  params = { per_page = 25 }
})

local by_entity = app.integrations.coingecko.public_treasury_entity({
  entity_id = "strategy"
})

entity must be companies or governments for public_treasury_by_coin.

Long-Tail GET Endpoints

Use api_get only for read-only CoinGecko API v3 endpoints that do not yet have a first-class tool, for example derivatives or NFT endpoints:

local derivatives = app.integrations.coingecko.api_get({
  path = "/derivatives",
  params = {}
})

api_get accepts relative API paths only. It does not call external URLs.

Raw agent markdown

# CoinGecko Lua Reference

CoinGecko tools expose API v3 market, exchange, category, asset-platform, and public treasury data. Use CoinGecko IDs (`bitcoin`, `ethereum`) rather than ticker symbols (`BTC`, `ETH`).

## Common Discovery Flow

```lua
local search = app.integrations.coingecko.search_coins({ query = "solana" })
local coin_id = search.coins[1].id

local categories = app.integrations.coingecko.list_categories({})
local platforms = app.integrations.coingecko.list_asset_platforms({})
```

`list_coins` can return contract addresses when called with `include_platform = "true"`:

```lua
local coins = app.integrations.coingecko.list_coins({
  params = { include_platform = "true" }
})
```

## Prices And Markets

```lua
local price = app.integrations.coingecko.price({
  ids = "bitcoin,ethereum",
  currencies = "usd,eur"
})

local token_price = app.integrations.coingecko.simple_token_price({
  asset_platform_id = "ethereum",
  contract_addresses = "0x0000000000000000000000000000000000000000",
  currencies = "usd"
})

local markets = app.integrations.coingecko.markets({
  currency = "usd",
  category = "layer-1",
  per_page = "10",
  page = "1"
})
```

`price` and `simple_token_price` include market cap, 24h volume, 24h change, and last-updated fields where CoinGecko returns them.

## Coin Detail And History

```lua
local info = app.integrations.coingecko.info({ id = "bitcoin" })
local tickers = app.integrations.coingecko.coin_tickers({
  id = "bitcoin",
  params = { page = 1 }
})

local history_date = app.integrations.coingecko.coin_history_date({
  id = "bitcoin",
  date = "30-12-2025"
})

local chart = app.integrations.coingecko.history({
  id = "bitcoin",
  currency = "usd",
  days = "30"
})

local ohlc = app.integrations.coingecko.ohlc({
  id = "bitcoin",
  currency = "usd",
  days = "30"
})
```

The existing `info`, `markets`, `history`, `ohlc`, `search_coins`, `trending`, and `global` tools return normalized summaries to keep agent output small. New endpoint-family tools return CoinGecko's JSON shape directly.

## Exchanges

```lua
local exchanges = app.integrations.coingecko.list_exchanges({
  params = { per_page = 25, page = 1 }
})

local exchange = app.integrations.coingecko.get_exchange({ id = "binance" })
local tickers = app.integrations.coingecko.get_exchange_tickers({
  id = "binance",
  params = { coin_ids = "bitcoin" }
})

local volume = app.integrations.coingecko.exchange_volume_chart({
  id = "binance",
  days = "30"
})
```

Use `list_exchange_ids` to discover exchange IDs before calling exchange-specific tools.

## Categories, Rates, Global Data

```lua
local category_market = app.integrations.coingecko.categories_market_data({
  params = { order = "market_cap_desc" }
})

local rates = app.integrations.coingecko.exchange_rates({})
local trending = app.integrations.coingecko.trending({})
local global = app.integrations.coingecko.global({})
local defi = app.integrations.coingecko.global_defi({})
```

`exchange_rates` returns BTC-relative rates under `rates`.

## Asset Platforms And Token Lists

```lua
local platforms = app.integrations.coingecko.list_asset_platforms({})
local token_list = app.integrations.coingecko.token_list({
  asset_platform_id = "ethereum"
})
```

Use asset platform IDs for token-price and token-list calls.

## Public Treasury

```lua
local entities = app.integrations.coingecko.list_entities({})

local by_coin = app.integrations.coingecko.public_treasury_by_coin({
  entity = "companies",
  coin_id = "bitcoin",
  params = { per_page = 25 }
})

local by_entity = app.integrations.coingecko.public_treasury_entity({
  entity_id = "strategy"
})
```

`entity` must be `companies` or `governments` for `public_treasury_by_coin`.

## Long-Tail GET Endpoints

Use `api_get` only for read-only CoinGecko API v3 endpoints that do not yet have a first-class tool, for example derivatives or NFT endpoints:

```lua
local derivatives = app.integrations.coingecko.api_get({
  path = "/derivatives",
  params = {}
})
```

`api_get` accepts relative API paths only. It does not call external URLs.

Metadata-derived Lua example

local result = app.integrations.coingecko.api_get({path = "example_path", params = "example_params"})
print(result)

Functions

api_get Read

Call any CoinGecko API v3 GET path not covered by a first-class tool, such as /derivatives or /nfts/list.

Lua path: app.integrations.coingecko.api_get
Full name: coingecko.coingecko_api_get

Parameter	Type	Required	Description
`path`	string	yes	CoinGecko API path, such as /derivatives or /nfts/list.
`params`	object	no	Query parameters.

categories_market_data Read

List CoinGecko categories with market cap, volume, and top coin data.

Lua path: app.integrations.coingecko.categories_market_data
Full name: coingecko.coingecko_categories_market_data

Parameter	Type	Required	Description
`params`	object	no	Optional query parameters such as order.

history_date Read

Get historical coin data for a calendar date in dd-mm-yyyy format.

Lua path: app.integrations.coingecko.history_date
Full name: coingecko.coingecko_coin_history_date

Parameter	Type	Required	Description
`id`	string	yes	CoinGecko coin ID.
`date`	string	yes	Date in dd-mm-yyyy format.
`params`	object	no	Optional query parameters such as localization.

tickers Read

Get centralized and decentralized exchange tickers for a CoinGecko coin ID.

Lua path: app.integrations.coingecko.tickers
Full name: coingecko.coingecko_coin_tickers

Parameter	Type	Required	Description
`id`	string	yes	CoinGecko coin ID.
`params`	object	no	Optional query parameters such as exchange_ids, page, depth, order.

exchange_rates Read

Get BTC-to-currency exchange rates for fiat and crypto units.

Lua path: app.integrations.coingecko.exchange_rates
Full name: coingecko.coingecko_exchange_rates

Parameter	Type	Required	Description
No parameters.

exchange_volume_chart Read

Get historical exchange volume chart data in BTC.

Lua path: app.integrations.coingecko.exchange_volume_chart
Full name: coingecko.coingecko_exchange_volume_chart

Parameter	Type	Required	Description
`id`	string	yes	CoinGecko exchange ID.
`days`	string	no	Number of days, default 30.

get_exchange Read

Get exchange profile data, volume, and tickers by CoinGecko exchange ID.

Lua path: app.integrations.coingecko.get_exchange
Full name: coingecko.coingecko_get_exchange

Parameter	Type	Required	Description
`id`	string	yes	CoinGecko exchange ID such as binance or gdax.

get_exchange_tickers Read

Get market tickers for a CoinGecko exchange ID.

Lua path: app.integrations.coingecko.get_exchange_tickers
Full name: coingecko.coingecko_get_exchange_tickers

Parameter	Type	Required	Description
`id`	string	yes	CoinGecko exchange ID.
`params`	object	no	Optional query parameters such as coin_ids, page, depth, order.

global Read

Get overall crypto market statistics — total market cap, BTC dominance, active cryptocurrencies, trading volume, and more.

Lua path: app.integrations.coingecko.global
Full name: coingecko.coingecko_global

Parameter	Type	Required	Description
No parameters.

global_defi Read

Get global DeFi market cap, volume, dominance, and related aggregate metrics.

Lua path: app.integrations.coingecko.global_defi
Full name: coingecko.coingecko_global_defi

Parameter	Type	Required	Description
No parameters.

history Read

Get historical price, volume, and market cap chart data for a cryptocurrency over a time period. Returns timestamped data points with summary statistics.

Lua path: app.integrations.coingecko.history
Full name: coingecko.coingecko_history

Parameter	Type	Required	Description
`id`	string	yes	CoinGecko coin ID (e.g. "bitcoin", "ethereum", "solana"). Use coingecko_search_coins to find IDs.
`currency`	string	no	Target currency (default: "usd").
`days`	string	no	Number of days of history (default: "30"). Common values: 1, 7, 14, 30, 90, 365.

info Read

Get a full coin profile — description, categories, links (website, whitepaper, social), and current market data snapshot. Use `coingecko_search_coins` first to find the coin ID.

Lua path: app.integrations.coingecko.info
Full name: coingecko.coingecko_info

Parameter	Type	Required	Description
`id`	string	yes	CoinGecko coin ID (e.g. "bitcoin", "ethereum", "solana"). Use coingecko_search_coins to find IDs.

list_asset_platforms Read

List asset platform IDs and chain metadata used by token-price and token-list endpoints.

Lua path: app.integrations.coingecko.list_asset_platforms
Full name: coingecko.coingecko_list_asset_platforms

Parameter	Type	Required	Description
`params`	object	no	Optional query parameters such as filter=nft.

list_categories Read

List CoinGecko category IDs for filtering market data.

Lua path: app.integrations.coingecko.list_categories
Full name: coingecko.coingecko_list_categories

Parameter	Type	Required	Description
No parameters.

list Read

List supported CoinGecko coin IDs, symbols, names, and optional asset-platform contract addresses.

Lua path: app.integrations.coingecko.list
Full name: coingecko.coingecko_list_coins

Parameter	Type	Required	Description
`params`	object	no	Optional query parameters: include_platform, status.

list_entities Read

List public companies and governments supported by CoinGecko public treasury endpoints.

Lua path: app.integrations.coingecko.list_entities
Full name: coingecko.coingecko_list_entities

Parameter	Type	Required	Description
No parameters.

list_exchange_ids Read

List exchange IDs and names for exchange-specific tools.

Lua path: app.integrations.coingecko.list_exchange_ids
Full name: coingecko.coingecko_list_exchange_ids

Parameter	Type	Required	Description
No parameters.

list_exchanges Read

List active exchanges with country, trust score, and 24-hour BTC volume data.

Lua path: app.integrations.coingecko.list_exchanges
Full name: coingecko.coingecko_list_exchanges

Parameter	Type	Required	Description
`params`	object	no	Optional query parameters: per_page, page.

markets Read

Get top cryptocurrencies ranked by market cap with full market data (price, volume, ATH, supply, price changes). Supports filtering by category or specific coin IDs.

Lua path: app.integrations.coingecko.markets
Full name: coingecko.coingecko_markets

Parameter	Type	Required	Description
`ids`	string	no	Comma-separated CoinGecko coin IDs to filter to specific coins (e.g. "bitcoin,ethereum,solana").
`currency`	string	no	Target currency (default: "usd"). Common: usd, eur, gbp, btc.
`category`	string	no	Filter by category (e.g. "decentralized-finance-defi", "layer-1"). Use coingecko_search_coins to find category IDs.
`per_page`	string	no	Number of results per page (default: "20", max: 100).
`page`	string	no	Page number for pagination (default: "1").
`price_change_percentage`	string	no	Comma-separated price change timeframes (default: "24h,7d"). Options: 1h, 24h, 7d, 14d, 30d, 200d, 1y.

new Read

List the latest coins recently added to CoinGecko.

Lua path: app.integrations.coingecko.new
Full name: coingecko.coingecko_new_coins

Parameter	Type	Required	Description
No parameters.

ohlc Read

Get OHLC (Open/High/Low/Close) candlestick data for a cryptocurrency for technical analysis.

Lua path: app.integrations.coingecko.ohlc
Full name: coingecko.coingecko_ohlc

Parameter	Type	Required	Description
`id`	string	yes	CoinGecko coin ID (e.g. "bitcoin", "ethereum", "solana"). Use coingecko_search_coins to find IDs.
`currency`	string	no	Target currency (default: "usd").
`days`	string	no	Number of days of OHLC data (default: "30"). Common values: 1, 7, 14, 30, 90, 365.

price Read

Get current price for one or more cryptocurrencies (by CoinGecko ID). Includes 24h change, volume, and market cap. Use `coingecko_search_coins` first to find coin IDs.

Lua path: app.integrations.coingecko.price
Full name: coingecko.coingecko_price

Parameter	Type	Required	Description
`ids`	string	yes	Comma-separated CoinGecko coin IDs (e.g. "bitcoin,ethereum,solana"). Use coingecko_search_coins to find IDs.
`currencies`	string	no	Comma-separated target currencies (default: "usd"). E.g. "usd,eur,btc".

public_treasury_by Read

Get public company or government crypto treasury holdings by CoinGecko coin ID.

Lua path: app.integrations.coingecko.public_treasury_by
Full name: coingecko.coingecko_public_treasury_by_coin

Parameter	Type	Required	Description
`entity`	string	yes	companies or governments.
`coin_id`	string	yes	CoinGecko coin ID, such as bitcoin.
`params`	object	no	Optional query parameters: per_page, page, order.

public_treasury_entity Read

Get public treasury holdings for a public company or government entity ID.

Lua path: app.integrations.coingecko.public_treasury_entity
Full name: coingecko.coingecko_public_treasury_entity

Parameter	Type	Required	Description
`entity_id`	string	yes	Public treasury entity ID from coingecko_list_entities.
`params`	object	no	Optional holding_amount_change and holding_change_percentage query parameters.

search Read

Find cryptocurrencies by name or ticker symbol (e.g. "bitcoin", "ETH", "solana"). Returns matching coin IDs which are needed for other CoinGecko tools.

Lua path: app.integrations.coingecko.search
Full name: coingecko.coingecko_search_coins

Parameter	Type	Required	Description
`query`	string	yes	Search query — coin name or ticker symbol (e.g. "bitcoin", "ETH").

simple_token_price Read

Get token prices by asset platform ID and token contract address.

Lua path: app.integrations.coingecko.simple_token_price
Full name: coingecko.coingecko_simple_token_price

Parameter	Type	Required	Description
`asset_platform_id`	string	yes	Asset platform ID such as ethereum, polygon-pos, or solana.
`contract_addresses`	string	yes	Comma-separated token contract addresses.
`currencies`	string	no	Comma-separated target currencies, default usd.

token_list Read

Get the token list for an asset platform, such as ethereum or polygon-pos.

Lua path: app.integrations.coingecko.token_list
Full name: coingecko.coingecko_token_list

Parameter	Type	Required	Description
`asset_platform_id`	string	yes	Asset platform ID.

top_gainers_losers Read

Get top gainers and losers for a target currency and time duration.

Lua path: app.integrations.coingecko.top_gainers_losers
Full name: coingecko.coingecko_top_gainers_losers

Parameter	Type	Required	Description
`currency`	string	no	Target currency, default usd.
`params`	object	no	Optional query parameters such as duration and top_coins.

trending Read

Get the top trending cryptocurrencies in the last 24 hours based on search activity on CoinGecko.

Lua path: app.integrations.coingecko.trending
Full name: coingecko.coingecko_trending

Parameter	Type	Required	Description
No parameters.