# Koios

> Read Cardano blockchain data through Koios, Cardano's community-run public API: ADA balances, transactions and tokens of an address or a whole wallet, staking rewards and delegation, transactions and their confirmations, blocks and epochs, native tokens and NFTs with their holders, stake pools and their history, the ADA supply, and governance proposals. A trigger runs on each new transaction of an address or wallet. No account or API key required.

App · 20 actions. Web page: https://docs.lodol.com/docs/integrations/koios

## Actions

### Get ADA supply

Get how much ADA has been issued, how much is in circulation, in the treasury and in the reserves, and the unclaimed rewards, as of the start of an epoch (the current one by default).

**Inputs**

- Epoch (`epoch`, number): The epoch to read the figures at. Leave empty for the current one. From 0 to 100000.

**Outputs**

- `circulation_ada` (number): ADA held in wallets (outputs), in ADA.
- `drep_deposits_ada` (number): ADA held as DRep registration deposits.
- `epoch_no` (number): The epoch these figures are for (taken as it began).
- `fees_ada` (number): Fees collected in the epoch before, in ADA.
- `proposal_deposits_ada` (number): ADA held as governance proposal deposits.
- `reserves_ada` (number): ADA still in the reserves, paid out over time as rewards.
- `rewards_ada` (number): Rewards earned and not yet withdrawn, in ADA.
- `stake_deposits_ada` (number): ADA held as stake address deposits.
- `supply_ada` (number): ADA issued so far: the 45 billion maximum less the reserves still to be paid out.
- `treasury_ada` (number): ADA in the treasury, spent by governance votes.

**Example output**

```json
{
  "circulation_ada": 36823860963.22488,
  "drep_deposits_ada": 525000.0,
  "epoch_no": 665,
  "fees_ada": 42320.144798,
  "proposal_deposits_ada": 400000.0,
  "reserves_ada": 6029414056.16776,
  "rewards_ada": 748493211.199794,
  "stake_deposits_ada": 4367474.0,
  "supply_ada": 38970585943.83224,
  "treasury_ada": 1392896975.262771
}
```

### Get address

Get a Cardano address's ADA balance, the stake address of the wallet it belongs to, whether a smart contract controls it, and how many outputs and kinds of token it holds. An address never used comes back with a zero balance rather than failing.

**Inputs**

- Address (`address`, text, required): A Cardano address, starting addr1 (or a Byron address starting Ae2 or DdzFF).

**Outputs**

- `address` (text): The address.
- `balance_ada` (number): The ADA the address holds, in ADA.
- `balance_lovelace` (text): The ADA the address holds, exactly, in lovelace (1 ADA is 1,000,000 lovelace).
- `found` (true/false): True when the address has been used on chain. An unused address comes back with found false and a zero balance.
- `script_address` (true/false): True when a smart contract (script) controls it.
- `stake_address` (text): The stake address of the wallet it belongs to; empty when it has none.
- `token_count` (number): How many different native tokens and NFTs it holds.
- `utxo_count` (number): How many unspent outputs (UTxOs) it holds.

**Example output**

```json
{
  "address": "addr1qynpqguauxmgjryewdhzv7jdwl30p0v64uszz2vxtdpwtnp5gyaqvds507nhq7pkzvcgytmufau7xhsqv2gt4h24skkq946shd",
  "balance_ada": 2.55152,
  "balance_lovelace": "2551520",
  "found": true,
  "script_address": false,
  "stake_address": "stake1uy6yzwsxxc28lfms0qmpxvyz9a7y770rtcqx9y96m42cttqwvp4m5",
  "token_count": 8,
  "utxo_count": 1
}
```

### Get block

Get a Cardano block by its hash or number: when it was made, by which pool, its fees and output, its confirmations, the blocks either side, and the hashes of its transactions.

**Inputs**

- Block (`block`, text, required): The block's hash (64 characters) or its number (height).

**Outputs**

- `absolute_slot` (number): Its slot since the chain began.
- `block_height` (number): The block's number (height) in the chain.
- `block_time` (text): When it was made, ISO 8601 UTC.
- `block_time_unix` (number): When it was made, as Unix seconds.
- `confirmations` (number): How many blocks have been added since, counting itself.
- `epoch_no` (number): The epoch it is in.
- `epoch_slot` (number): Its slot within the epoch.
- `era` (text): The ledger era, e.g. Conway.
- `hash` (text): The block's hash.
- `next_hash` (text): The hash of the block after it; empty for the newest.
- `pool` (text): The pool ID of the stake pool that made it.
- `previous_hash` (text): The hash of the block before it.
- `protocol_version` (text): The protocol version it was made under, e.g. 10.0.
- `size_bytes` (number): Its size in bytes.
- `total_fees_ada` (number): Fees paid in its transactions, in ADA.
- `total_output_ada` (number): ADA sent in its transactions, outputs summed.
- `transaction_count` (number): How many transactions it holds.
- `transactions` (list): The hashes of the transactions in it, in block order.

**Example output**

```json
{
  "absolute_slot": 176409707,
  "block_height": 12887221,
  "block_time": "2026-01-09T16:26:38Z",
  "block_time_unix": 1767975998,
  "confirmations": 1260439,
  "epoch_no": 605,
  "epoch_slot": 412907,
  "era": "Conway",
  "hash": "0b05f93c6bb31058dae6fc09953f84cca3d5d3a5a8c7b9ad10b887c66d464d15",
  "next_hash": "56fe9d1c7552a1b422d4d8c2fc91268bf8b776c1e3be26914b7eec096bcd07a6",
  "pool": "pool1cyq3v3v43hu7spwlfxdm6vq9djpsjjueerhlu5qr2rvd57vqk84",
  "previous_hash": "6a6f3e275f8446bf3bba0e7019e173f3c70b3168483d18837ee00a0022a44a9c",
  "protocol_version": "10.3",
  "size_bytes": 49499,
  "total_fees_ada": 9.992786,
  "total_output_ada": 20980129.020998,
  "transaction_count": 35,
  "transactions": [
    "0f3125e2e7d777785e951d1fc5db03222568a6fa9e148dc64eb617f839c28928",
    "7cf8a89fdea122d5d7a62665ed2fe9906152544d43dcc902fb4f5e8df53bb16f",
    "4686cd0652c2596b10277f739df2415f0cbfd1e8b19e9ced72185d202b5d1422"
  ]
}
```

### Get epoch

Get one of Cardano's five-day epochs, or the current one: when it starts and ends, its blocks, transactions and fees, the ADA staked, and the rewards paid for it.

**Inputs**

- Epoch (`epoch`, number): The epoch's number. Leave empty for the current one. From 0 to 100000.

**Outputs**

- `active_stake_ada` (number): ADA staked with pools and counted for this epoch's block production.
- `average_block_reward_ada` (number): Average reward per block made, in ADA. Empty until rewards are worked out.
- `block_count` (number): Blocks made in the epoch so far.
- `end_time` (text): When the epoch ends, ISO 8601 UTC.
- `end_time_unix` (number): When the epoch ends, as Unix seconds.
- `epoch_no` (number): The epoch's number.
- `era` (text): The ledger era during the epoch, e.g. Conway.
- `fees_ada` (number): Transaction fees paid in the epoch, in ADA.
- `first_block_time` (text): When its first block was made, ISO 8601 UTC.
- `in_progress` (true/false): True while the epoch is still running.
- `last_block_time` (text): When its latest block was made, ISO 8601 UTC.
- `start_time` (text): When the epoch starts, ISO 8601 UTC.
- `start_time_unix` (number): When the epoch starts, as Unix seconds.
- `total_output_ada` (number): ADA sent in all of its transactions, outputs summed.
- `total_rewards_ada` (number): Staking rewards paid for the epoch, in ADA. Empty until they are worked out, two epochs after it ends.
- `transaction_count` (number): Transactions made in the epoch so far.

**Example output**

```json
{
  "active_stake_ada": 21266994047.499493,
  "average_block_reward_ada": 293.029609,
  "block_count": 21243,
  "end_time": "2026-10-11T21:44:51Z",
  "end_time_unix": 1791755091,
  "epoch_no": 660,
  "era": "Conway",
  "fees_ada": 337719.996235,
  "first_block_time": "2026-10-06T21:45:45Z",
  "in_progress": false,
  "last_block_time": "2026-10-11T21:44:46Z",
  "start_time": "2026-10-06T21:44:51Z",
  "start_time_unix": 1791323091,
  "total_output_ada": 46707198832.07933,
  "total_rewards_ada": 6224827.984859,
  "transaction_count": 1780896
}
```

### Get latest block

Get Cardano's newest block: its number, hash, epoch and slot, when it was made and how many seconds ago.

**Inputs**: None.

**Outputs**

- `absolute_slot` (number): Its slot since the chain began.
- `block_hash` (text): The newest block's hash.
- `block_height` (number): The newest block's number (height) in the chain.
- `block_time` (text): When the newest block was made, ISO 8601 UTC.
- `block_time_unix` (number): When the newest block was made, as Unix seconds.
- `epoch_no` (number): The epoch it is in. A Cardano epoch lasts five days.
- `epoch_slot` (number): Its slot within the epoch (one slot is one second).
- `era` (text): The ledger era, e.g. Conway.
- `seconds_since_block` (number): How many seconds ago the newest block was made. Blocks come about every 20 seconds, so a large number means Koios has fallen behind.

**Example output**

```json
{
  "absolute_slot": 202040840,
  "block_hash": "aa4615be6bd7871168b64300e7db108e297b570d505af860de41bdc355d73c58",
  "block_height": 14147659,
  "block_time": "2026-11-02T08:12:11Z",
  "block_time_unix": 1793607131,
  "epoch_no": 665,
  "epoch_slot": 124040,
  "era": "Conway",
  "seconds_since_block": 42
}
```

### Get stake account

Get a Cardano wallet's stake account: everything it holds, the rewards it can withdraw, the stake pool it delegates to and the DRep it delegates its vote to. Give its stake address or any of its addresses.

**Inputs**

- Stake address (`stake_address`, text, required): The wallet's stake address (stake1...). Any of the wallet's addresses (addr1...) works too: its stake address is read from it.

**Outputs**

- `delegated_drep` (text): The DRep it delegates its vote to (a drep1... ID, or drep_always_abstain or drep_always_no_confidence); empty when none.
- `delegated_pool` (text): The pool ID it delegates to; empty when none.
- `deposit_ada` (number): The deposit paid to register it, in ADA.
- `found` (true/false): True when Koios knows the stake address. One never used comes back with found false and zero balances.
- `rewards_available_ada` (number): Rewards earned and not yet withdrawn, in ADA.
- `rewards_available_lovelace` (text): Rewards earned and not yet withdrawn, exactly, in lovelace (1 ADA is 1,000,000 lovelace).
- `stake_address` (text): The stake address.
- `status` (text): registered, or not registered (no longer, or never, staking).
- `total_balance_ada` (number): Everything the wallet holds, rewards included, in ADA.
- `total_balance_lovelace` (text): Everything the wallet holds, rewards included, exactly, in lovelace (1 ADA is 1,000,000 lovelace).
- `total_rewards_ada` (number): All the rewards it has ever earned, in ADA.
- `total_withdrawals_ada` (number): All the rewards it has withdrawn, in ADA.
- `utxo_balance_ada` (number): The ADA held in its addresses, in ADA.

**Example output**

```json
{
  "delegated_drep": "drep_always_abstain",
  "delegated_pool": "pool1mxqjlrfskhd5kql9kak06fpdh8xjwc76gec76p3taqy2qmfzs5z",
  "deposit_ada": 2.0,
  "found": true,
  "rewards_available_ada": 332070.431104,
  "rewards_available_lovelace": "332070431104",
  "stake_address": "stake1uy6yzwsxxc28lfms0qmpxvyz9a7y770rtcqx9y96m42cttqwvp4m5",
  "status": "registered",
  "total_balance_ada": 332072.982624,
  "total_balance_lovelace": "332072982624",
  "total_rewards_ada": 81924713.131142,
  "total_withdrawals_ada": 81592642.700038,
  "utxo_balance_ada": 2.55152
}
```

### Get stake pool

Get a Cardano stake pool: its name and homepage, status, margin, fixed cost and pledge, its stake and delegators now, how saturated it is, the blocks it has made, its relays and its voting power.

**Inputs**

- Stake pool (`pool`, text, required): The pool, picked by ticker, or its pool ID (pool1...) pasted in. Retired pools aren't in the list but can be pasted.

**Outputs**

- `active_stake_ada` (number): ADA staked with it for the current epoch.
- `block_count` (number): Blocks it has made in its lifetime.
- `description` (text): The pool's description, from its published metadata.
- `fixed_cost_ada` (number): The fixed fee it takes from rewards each epoch, in ADA.
- `homepage` (text): The pool's website, from its published metadata.
- `live_delegators` (number): How many stake addresses delegate to it now.
- `live_pledge_ada` (number): ADA its owners actually have staked with it now.
- `live_saturation_percent` (number): How full it is: above 100, delegators earn less.
- `live_stake_ada` (number): ADA staked with it right now, for future epochs.
- `margin_percent` (number): The share of rewards it keeps, as a percentage.
- `metadata_url` (text): Where its name, ticker and homepage are published.
- `name` (text): The pool's name, from its published metadata.
- `owners` (list): The stake addresses of its owners.
- `pledge_ada` (number): ADA its owners promise to keep staked with it.
- `pool_id` (text): The pool's ID (pool1...).
- `pool_id_hex` (text): The pool's ID as hex.
- `relays` (list): Its relays' host names or IP addresses, with port.
- `retiring_epoch` (number): The epoch it retires in; empty when it isn't retiring.
- `reward_address` (text): The stake address its operator's rewards go to.
- `status` (text): registered, retiring or retired.
- `ticker` (text): The pool's ticker, e.g. IOG1. Tickers are not unique.
- `voting_power_ada` (number): Its voting power in governance votes, in ADA.

**Example output**

```json
{
  "active_stake_ada": 9759448.579343,
  "block_count": 19674,
  "description": "Our mission is to provide economic identity to the billions of people who lack it. IOHK will not use the IOHK ticker.",
  "fixed_cost_ada": 340.0,
  "homepage": "https://iohk.io",
  "live_delegators": 1017,
  "live_pledge_ada": 5000558.043187,
  "live_saturation_percent": 12.51,
  "live_stake_ada": 9753045.880186,
  "margin_percent": 7.0,
  "metadata_url": "https://iog1.cardano.iog.io/metadata.json",
  "name": "Input Output Global (IOHK) - 1",
  "owners": [
    "stake1u8tr20zqh6xhl02kkvyrsnmyh73du4ywu5fhxe2yq7q96rg94spt0"
  ],
  "pledge_ada": 5000000.0,
  "pool_id": "pool1mxqjlrfskhd5kql9kak06fpdh8xjwc76gec76p3taqy2qmfzs5z",
  "pool_id_hex": "d9812f8d30b5db4b03e5b76cfd242db9cd2763da4671ed062be808a0",
  "relays": [
    "iog1-relays.cardano.iog.io:3001"
  ],
  "retiring_epoch": null,
  "reward_address": "stake1uy6yzwsxxc28lfms0qmpxvyz9a7y770rtcqx9y96m42cttqwvp4m5",
  "status": "registered",
  "ticker": "IOG1",
  "voting_power_ada": 9753550.717445
}
```

### Get token

Get a Cardano native token or NFT: its name, ticker, description and decimals from the token registry, how much exists, how often it was minted and burned, when it was created, and the metadata it was minted with.

**Inputs**

- Token (`asset`, text, required): The token's fingerprint (asset1..., as wallets and explorers show it), or its policy ID followed by its name in hex.

**Outputs**

- `asset_name` (text): Its name as hex, as it is on chain.
- `asset_name_text` (text): Its name as text (e.g. SNEK), when the name is text.
- `burn_count` (number): How many times some has been burned.
- `cip68_metadata` (object): Its CIP-68 metadata, for tokens that use that standard.
- `created_at` (text): When it was first minted, ISO 8601 UTC.
- `created_at_unix` (number): When it was first minted, as Unix seconds.
- `decimals` (number): How many decimal places it uses (0 for an NFT).
- `description` (text): Its description in the token registry.
- `fingerprint` (text): Its fingerprint (asset1...), as wallets show it.
- `mint_count` (number): How many times it has been minted.
- `minting_metadata` (object): The metadata written when it was minted (CIP-25 for most NFTs), by label.
- `minting_tx_hash` (text): The transaction that first minted it.
- `name` (text): Its name in the token registry or its own metadata.
- `policy_id` (text): The policy ID that minted it.
- `ticker` (text): Its ticker in Cardano's token registry, e.g. SNEK.
- `total_supply` (text): How much exists now, exactly, before decimals.
- `total_supply_amount` (number): How much exists now, with decimals applied.
- `unit` (text): The policy ID and hex name together.
- `url` (text): Its website in the token registry.

**Example output**

```json
{
  "asset_name": "534e454b",
  "asset_name_text": "SNEK",
  "burn_count": 0,
  "cip68_metadata": null,
  "created_at": "2023-04-26T03:40:13Z",
  "created_at_unix": 1682480413,
  "decimals": 0,
  "description": "A meme, and a memecoin",
  "fingerprint": "asset108xu02ckwrfc8qs9d97mgyh4kn8gdu9w8f5sxk",
  "mint_count": 1,
  "minting_metadata": {
    "721": {
      "279c909f348e533da5808898f87f9a14bb2c3dfbbacccd631d927a3f": {
        "SNEK": {
          "description": "In Snek We Trust",
          "files": [
            {
              "mediaType": "image/png",
              "name": "SNEK",
              "src": "ipfs://QmaPe6g9NPTTkJ87CF2MjN9fS8Mbfwv8Ue6DwZyyUyXUQF"
            }
          ],
          "image": "ipfs://QmaPe6g9NPTTkJ87CF2MjN9fS8Mbfwv8Ue6DwZyyUyXUQF",
          "mediaType": "image/png",
          "minting": {
            "blockchain": "cardano",
            "mintedBeforeSlotNumber": 90915881,
            "type": "time-lock-policy"
          },
          "name": "Snek",
          "symbol": "SNEK",
          "tokenType": "token",
          "totalSupply": 76715880000
        }
      },
      "version": "1.0"
    }
  },
  "minting_tx_hash": "bda114e910c35292c8941a902b0d8854f1998f5c557b3f124ebf15e25d26fadf",
  "name": "Snek",
  "policy_id": "279c909f348e533da5808898f87f9a14bb2c3dfbbacccd631d927a3f",
  "ticker": "SNEK",
  "total_supply": "76715880000",
  "total_supply_amount": 76715880000.0,
  "unit": "279c909f348e533da5808898f87f9a14bb2c3dfbbacccd631d927a3f534e454b",
  "url": "https://www.snek.com/"
}
```

### Get transaction

Get a Cardano transaction: when and in which block it was made, its fee, what it spent and where the ADA and tokens went, tokens minted or burned, rewards withdrawn, its certificates, and its message and metadata.

**Inputs**

- Transaction hash (`transaction_hash`, text, required): The transaction's hash: 64 characters, 0-9 and a-f.

**Outputs**

- `absolute_slot` (number): Its slot since the chain began.
- `block_hash` (text): The hash of the block it is in.
- `block_height` (number): The number of the block it is in.
- `block_index` (number): Its position in the block.
- `block_time` (text): When it was made, ISO 8601 UTC.
- `block_time_unix` (number): When it was made, as Unix seconds.
- `certificate_types` (list): What each certificate in it does, e.g. stake_delegation or stake_registration.
- `deposit_ada` (number): Deposits paid (positive) or refunded (negative) for registrations, in ADA.
- `epoch_no` (number): The epoch it was made in.
- `fee_ada` (number): The fee paid, in ADA.
- `fee_lovelace` (text): The fee paid, exactly, in lovelace (1 ADA is 1,000,000 lovelace).
- `input_count` (number): How many inputs it spent.
- `inputs` (list): What it spent: the outputs of earlier transactions.
- `message` (text): The message attached to it (CIP-20 metadata, label 674), the way wallets show a memo; empty when there is none.
- `metadata` (object): Everything attached as metadata, by label, as it was written on chain.
- `output_count` (number): How many outputs it made.
- `outputs` (list): Where the ADA and tokens went.
- `size_bytes` (number): Its size in bytes.
- `tokens_minted` (list): Tokens minted (positive amounts) or burned (negative).
- `total_output_ada` (number): The ADA in all its outputs, in ADA.
- `total_output_lovelace` (text): The ADA in all its outputs, exactly, in lovelace (1 ADA is 1,000,000 lovelace).
- `treasury_donation_ada` (number): ADA given to the treasury, in ADA.
- `tx_hash` (text): The transaction's hash.
- `withdrawals` (list): Staking rewards withdrawn in it.

**Example output**

```json
{
  "absolute_slot": 176409707,
  "block_hash": "0b05f93c6bb31058dae6fc09953f84cca3d5d3a5a8c7b9ad10b887c66d464d15",
  "block_height": 12887221,
  "block_index": 21,
  "block_time": "2026-01-09T16:26:38Z",
  "block_time_unix": 1767975998,
  "certificate_types": [],
  "deposit_ada": 0.0,
  "epoch_no": 605,
  "fee_ada": 0.21,
  "fee_lovelace": "210000",
  "input_count": 1,
  "inputs": [
    {
      "address": "addr1qynpqguauxmgjryewdhzv7jdwl30p0v64uszz2vxtdpwtnp5gyaqvds507nhq7pkzvcgytmufau7xhsqv2gt4h24skkq946shd",
      "stake_address": "stake1uy6yzwsxxc28lfms0qmpxvyz9a7y770rtcqx9y96m42cttqwvp4m5",
      "tokens": [],
      "tx_hash": "d45cbe6dde003dc722f3c3edfe225b76d22fbc58427c124c44defa119860dbc6",
      "tx_index": 0,
      "value_ada": 10.0,
      "value_lovelace": "10000000"
    }
  ],
  "message": null,
  "metadata": null,
  "output_count": 1,
  "outputs": [
    {
      "address": "addr1qxrz6c2cen8856ft2q90fzd82d24ttglz93l3fwhe6k25pyx94s43nxw0f5jk5q27jy6w5642kk37ytrlzja0n4v4gzqeu2lq2",
      "stake_address": "stake1uxrz6c2cen8856ft2q90fzd82d24ttglz93l3fwhe6k25pqzek6t9",
      "tokens": [],
      "tx_hash": "f26d2aee874f5c192475c035bc06595d600654692f6ef966b795be30acefe354",
      "tx_index": 0,
      "value_ada": 1925317.213576,
      "value_lovelace": "1925317213576"
    }
  ],
  "size_bytes": 377,
  "tokens_minted": [],
  "total_output_ada": 1925317.213576,
  "total_output_lovelace": "1925317213576",
  "treasury_donation_ada": 0.0,
  "tx_hash": "f26d2aee874f5c192475c035bc06595d600654692f6ef966b795be30acefe354",
  "withdrawals": [
    {
      "amount_ada": 1925307.423576,
      "amount_lovelace": "1925307423576",
      "stake_address": "stake1uy6yzwsxxc28lfms0qmpxvyz9a7y770rtcqx9y96m42cttqwvp4m5"
    }
  ]
}
```

### Get transaction confirmations

Find out whether a Cardano transaction is on chain and how many blocks have confirmed it. One not found comes back with found false rather than failing, so a workflow can wait and check again.

**Inputs**

- Transaction hash (`transaction_hash`, text, required): The transaction's hash: 64 characters, 0-9 and a-f.

**Outputs**

- `confirmations` (number): How many blocks have been added since, counting its own; empty when not found. Exchanges often wait for 15 or more.
- `found` (true/false): True when the transaction is on chain. False for one still waiting to be added, dropped, or never sent.
- `tx_hash` (text): The transaction's hash.

**Example output**

```json
{
  "confirmations": 1260439,
  "found": true,
  "tx_hash": "f26d2aee874f5c192475c035bc06595d600654692f6ef966b795be30acefe354"
}
```

### List address tokens

List the native tokens and NFTs a Cardano address holds, or a whole wallet by its stake address, with each token's name, fingerprint and amount (decimals applied).

**Inputs**

- Address or stake address (`address`, text, required): A Cardano address (addr1...) for that address alone, or a stake address (stake1...) for every address of the wallet it belongs to.
- Number of results (`limit`, number): How many to return, 1 to 1,000. Defaults to 100. From 1 to 1000.
- Skip (`offset`, number): How many to skip, to read the next page: give the Number of results of the page before. Leave empty for the first page. At least 0.

**Outputs**

- `address` (text): The address or stake address read.
- `address_type` (text): address, or stake_address for a wallet.
- `assets` (list): The tokens held.
- `count` (number): How many tokens held came back.

**Example output**

```json
{
  "address": "addr1qynpqguauxmgjryewdhzv7jdwl30p0v64uszz2vxtdpwtnp5gyaqvds507nhq7pkzvcgytmufau7xhsqv2gt4h24skkq946shd",
  "address_type": "address",
  "assets": [
    {
      "amount": 5000.0,
      "asset_name": "4c494f4e2043484144",
      "asset_name_text": "LION CHAD",
      "decimals": 0,
      "fingerprint": "asset1a2j64rgg5sxc56j6v76qw0k7qt5jk8zm84lcjq",
      "policy_id": "10eacc7b7aa4f433b2792bdeca0a5e84a45ff88ab576e1fbb8124c65",
      "quantity": "5000",
      "unit": "10eacc7b7aa4f433b2792bdeca0a5e84a45ff88ab576e1fbb8124c654c494f4e2043484144"
    },
    {
      "amount": 1.0,
      "asset_name": "77676d69",
      "asset_name_text": "wgmi",
      "decimals": 0,
      "fingerprint": "asset18r27k8znmf97wzcw8mfc7h0usmsyuzgvf4gjqt",
      "policy_id": "24a32f531db96d0b2daf673d31e6203c94eebdc83781d7f9d5dc6ae5",
      "quantity": "1",
      "unit": "24a32f531db96d0b2daf673d31e6203c94eebdc83781d7f9d5dc6ae577676d69"
    }
  ],
  "count": 2
}
```

### List address transactions

List the transactions of a Cardano address, or of a whole wallet by its stake address, newest first, with the block and time of each. Narrow them to those since a time or from a block.

**Inputs**

- Address or stake address (`address`, text, required): A Cardano address (addr1...) for that address alone, or a stake address (stake1...) for every address of the wallet it belongs to.
- Since (`since`, date and time): Only transactions made at or after this time.
- From block (`from_block_height`, number): Only transactions in this block number or later, e.g. the block_height of an earlier step's newest transaction. At least 0.
- Number of results (`limit`, number): How many to return, 1 to 1,000. Defaults to 20. From 1 to 1000.
- Skip (`offset`, number): How many to skip, to read the next page: give the Number of results of the page before. Leave empty for the first page. At least 0.

**Outputs**

- `address` (text): The address or stake address read.
- `address_type` (text): address, or stake_address for a wallet.
- `count` (number): How many transactions, newest first came back.
- `transactions` (list): The transactions, newest first.

**Example output**

```json
{
  "address": "addr1qynpqguauxmgjryewdhzv7jdwl30p0v64uszz2vxtdpwtnp5gyaqvds507nhq7pkzvcgytmufau7xhsqv2gt4h24skkq946shd",
  "address_type": "address",
  "count": 2,
  "transactions": [
    {
      "block_height": 12887221,
      "block_time": "2026-01-09T16:26:38Z",
      "block_time_unix": 1767975998,
      "epoch_no": 605,
      "tx_hash": "f26d2aee874f5c192475c035bc06595d600654692f6ef966b795be30acefe354"
    },
    {
      "block_height": 12879857,
      "block_time": "2026-01-07T22:51:23Z",
      "block_time_unix": 1767826283,
      "epoch_no": 605,
      "tx_hash": "d45cbe6dde003dc722f3c3edfe225b76d22fbc58427c124c44defa119860dbc6"
    }
  ]
}
```

### List blocks

List Cardano's blocks, newest first, optionally only those of one epoch or made by one stake pool, with each block's time, transactions and size.

**Inputs**

- Epoch (`epoch`, number): Only blocks of this epoch. Leave empty for any. From 0 to 100000.
- Stake pool (`pool`, text): Only blocks made by this pool. Leave empty for any pool.
- Number of results (`limit`, number): How many to return, 1 to 1,000. Defaults to 20. From 1 to 1000.
- Skip (`offset`, number): How many to skip, to read the next page: give the Number of results of the page before. Leave empty for the first page. At least 0.

**Outputs**

- `blocks` (list): The blocks, newest first.
- `count` (number): How many blocks, newest first came back.

**Example output**

```json
{
  "blocks": [
    {
      "absolute_slot": 202040901,
      "block_height": 14147660,
      "block_time": "2026-11-02T08:13:12Z",
      "block_time_unix": 1793607192,
      "epoch_no": 665,
      "epoch_slot": 124101,
      "hash": "2266c5059e1d369bb18296f91553a360b48ff9c71e34b9e091183ca59f66665c",
      "pool": "pool19tz0rwsnzmsw602rauwhzrsgk4qx55qzhkmxfqe04s6vuu37ptw",
      "protocol_version": "11.2",
      "size_bytes": 14971,
      "transaction_count": 18
    },
    {
      "absolute_slot": 202040840,
      "block_height": 14147659,
      "block_time": "2026-11-02T08:12:11Z",
      "block_time_unix": 1793607131,
      "epoch_no": 665,
      "epoch_slot": 124040,
      "hash": "aa4615be6bd7871168b64300e7db108e297b570d505af860de41bdc355d73c58",
      "pool": "pool1yr0cv3dtmhcfgqa6yetvmf769ngk89e6tepecmjrmjl2jzcw2lm",
      "protocol_version": "11.1",
      "size_bytes": 3119,
      "transaction_count": 3
    }
  ],
  "count": 2
}
```

### List governance proposals

List Cardano's on-chain governance proposals, newest first, with each one's title and summary, kind, status, voting deadline, deposit and, for a treasury withdrawal, the ADA it asks for.

**Inputs**

- Status (`status`, text): Only proposals in this state. Leave empty for all. One of: `active` (Open for votes), `ratified` (Ratified, taking effect next epoch), `enacted`, `expired` (Expired without passing), `dropped`.
- Type (`proposal_type`, text): Only proposals of this kind. Leave empty for all. One of: `TreasuryWithdrawals` (Treasury withdrawal), `ParameterChange` (Protocol parameter change), `HardForkInitiation` (Hard fork), `InfoAction` (Info action (a poll)), `NewConstitution` (New constitution), `NewCommittee` (Constitutional committee change), `NoConfidence` (Motion of no confidence).
- Number of results (`limit`, number): How many to return, 1 to 1,000. Defaults to 20. From 1 to 1000.
- Skip (`offset`, number): How many to skip, to read the next page: give the Number of results of the page before. Leave empty for the first page. At least 0.

**Outputs**

- `count` (number): How many proposals, newest first came back.
- `proposals` (list): The proposals, newest first.

**Example output**

```json
{
  "count": 2,
  "proposals": [
    {
      "abstract": "This Treasury Withdrawal funds Cardano PRIME, a 12-month community-overseen program to improve DeFi protocol readiness, responsibly activate incentives, and grow durable liquidity across Cardano markets. The withdrawal requests \u20b3120,000,000, with USD figures included only as planning references at the $0.16/ADA assumption.",
      "deposit_ada": 100000.0,
      "dropped_epoch": null,
      "enacted_epoch": 650,
      "expiration_epoch": 649,
      "expired_epoch": null,
      "metadata_url": "ipfs://bafkreieaerpnfvjblld4pywite3rbfxkebf2fvlacerklrdmsfvp4kvui4",
      "proposal_id": "gov_action122wue2k65qq8gmpz795z2axt8apka6ay6xt3pwg8jxj5yfkujmtsqvlfpu7",
      "proposal_type": "TreasuryWithdrawals",
      "proposed_epoch": 642,
      "ratified_epoch": 649,
      "return_address": "stake1u8c9lgcnx2n47m9t2ccufra270d9vfp4updxmgndv4f7hyg8mykgg",
      "status": "enacted",
      "submitted_at": "2026-07-09T16:30:25Z",
      "submitted_at_unix": 1783614625,
      "title": "Withdraw 120,000,000 ada for AlphaGrowth\u2019s Cardano PRIME",
      "tx_hash": "529dccaadaa000746c22f1682574cb3f436eeba4d19710b90791a54226dc96d7",
      "type_label": "Treasury withdrawal",
      "withdrawal_ada": 120000000.0
    },
    {
      "abstract": "This Treasury Withdrawal funds Daedalus Wallet Maintenance and Improvements",
      "deposit_ada": 100000.0,
      "dropped_epoch": null,
      "enacted_epoch": 647,
      "expiration_epoch": 646,
      "expired_epoch": null,
      "metadata_url": "ipfs://QmdWtCCvK6CJUzP4SFiuL5W8hg3eNr5LyngJHnwjoNxJey",
      "proposal_id": "gov_action1mr0qdz2jmagvsch6r08fhqvq6vu8jakt4c8m9s7ea7z0p740vntqq4yjd6j",
      "proposal_type": "TreasuryWithdrawals",
      "proposed_epoch": 639,
      "ratified_epoch": 646,
      "return_address": "stake1u85was6qks0exltkfl74clay4p6l272ry6kpkgweyfs7vtcvaj7xm",
      "status": "enacted",
      "submitted_at": "2026-06-24T21:25:59Z",
      "submitted_at_unix": 1782336359,
      "title": "Se7en Labs: Daedalus Wallet Maintenance and Improvements 2026-2027",
      "tx_hash": "d8de068952df50c862fa1bce9b8180d3387976cbae0fb2c3d9ef84f0faaf64d6",
      "type_label": "Treasury withdrawal",
      "withdrawal_ada": 1785333.0
    }
  ]
}
```

### List policy tokens

List every token minted under a Cardano policy ID, such as the NFTs of a collection, with each one's name, fingerprint and supply.

**Inputs**

- Policy ID (`policy_id`, text, required): The policy ID tokens were minted under: 56 characters, 0-9 and a-f.
- Number of results (`limit`, number): How many to return, 1 to 1,000. Defaults to 100. From 1 to 1000.
- Skip (`offset`, number): How many to skip, to read the next page: give the Number of results of the page before. Leave empty for the first page. At least 0.

**Outputs**

- `assets` (list): The tokens under the policy.
- `count` (number): How many tokens under the policy came back.
- `policy_id` (text): The policy ID read.

**Example output**

```json
{
  "assets": [
    {
      "asset_name": "534e454b",
      "asset_name_text": "SNEK",
      "decimals": 0,
      "fingerprint": "asset108xu02ckwrfc8qs9d97mgyh4kn8gdu9w8f5sxk",
      "total_supply": "76715880000",
      "total_supply_amount": 76715880000.0,
      "unit": "279c909f348e533da5808898f87f9a14bb2c3dfbbacccd631d927a3f534e454b"
    }
  ],
  "count": 1,
  "policy_id": "279c909f348e533da5808898f87f9a14bb2c3dfbbacccd631d927a3f"
}
```

### List stake pool history

List a Cardano stake pool's record epoch by epoch, newest first: its stake and saturation, blocks made, delegators, fees taken, rewards paid and its delegators' return.

**Inputs**

- Stake pool (`pool`, text, required): The pool, picked by ticker, or its pool ID (pool1...) pasted in. Retired pools aren't in the list but can be pasted.
- Epoch (`epoch`, number): Only this epoch. Leave empty for every epoch. From 0 to 100000.
- Number of results (`limit`, number): How many to return, 1 to 1,000. Defaults to 10. From 1 to 1000.
- Skip (`offset`, number): How many to skip, to read the next page: give the Number of results of the page before. Leave empty for the first page. At least 0.

**Outputs**

- `count` (number): How many epochs, newest first came back.
- `epochs` (list): The epochs, newest first.
- `pool_id` (text): The pool read.

**Example output**

```json
{
  "count": 2,
  "epochs": [
    {
      "active_stake_ada": 9816733.234535,
      "active_stake_percent": 0.04566683975484179,
      "block_count": 5,
      "delegator_count": 1019,
      "delegator_rewards_ada": 1024.801499,
      "epoch_no": 663,
      "fixed_cost_ada": 340.0,
      "margin_percent": 7.0,
      "member_rewards_ada": 502.523408,
      "pool_fees_ada": 417.135597,
      "return_on_stake_percent": 0.764942404,
      "saturation_percent": 12.6
    },
    {
      "active_stake_ada": 9816267.251129,
      "active_stake_percent": 0.04588772941486547,
      "block_count": 7,
      "delegator_count": 1021,
      "delegator_rewards_ada": null,
      "epoch_no": 662,
      "fixed_cost_ada": 340.0,
      "margin_percent": 7.0,
      "member_rewards_ada": null,
      "pool_fees_ada": null,
      "return_on_stake_percent": 0.0,
      "saturation_percent": 12.6
    }
  ],
  "pool_id": "pool1mxqjlrfskhd5kql9kak06fpdh8xjwc76gec76p3taqy2qmfzs5z"
}
```

### List stake pools

Find Cardano stake pools by ticker, with each pool's ID, status, stake, pledge, margin and fixed cost.

**Inputs**

- Ticker (`search`, text): All or part of the pool's ticker, e.g. IOG. Leave empty to list pools in Koios's order.
- Status (`status`, text): Which pools to list. Defaults to registered pools. One of: `registered` (Registered (making blocks)), `retiring`, `retired`, `any` (Any status). Default: `registered`.
- Number of results (`limit`, number): How many to return, 1 to 1,000. Defaults to 20. From 1 to 1000.
- Skip (`offset`, number): How many to skip, to read the next page: give the Number of results of the page before. Leave empty for the first page. At least 0.

**Outputs**

- `count` (number): How many stake pools came back.
- `pools` (list): The stake pools.

**Example output**

```json
{
  "count": 2,
  "pools": [
    {
      "active_stake_ada": 9759448.579343,
      "fixed_cost_ada": 340.0,
      "margin_percent": 7.0,
      "metadata_url": "https://iog1.cardano.iog.io/metadata.json",
      "pledge_ada": 5000000.0,
      "pool_group": "IOG",
      "pool_id": "pool1mxqjlrfskhd5kql9kak06fpdh8xjwc76gec76p3taqy2qmfzs5z",
      "pool_id_hex": "d9812f8d30b5db4b03e5b76cfd242db9cd2763da4671ed062be808a0",
      "status": "registered",
      "ticker": "IOG1"
    },
    {
      "active_stake_ada": 1.48148,
      "fixed_cost_ada": 500.0,
      "margin_percent": 100.0,
      "metadata_url": "https://pools.iohk.io/IOGP.json",
      "pledge_ada": 64000000.0,
      "pool_group": "IOG",
      "pool_id": "pool12ql6www8aa8usn98azlkz76d2htxtm9swalvyac27rlq6mdkxc7",
      "pool_id_hex": "503fa739c7ef4fc84ca7e8bf617b4d55d665ecb0777ec2770af0fe0d",
      "status": "registered",
      "ticker": "IOGP"
    }
  ]
}
```

### List staking rewards

List the staking rewards a Cardano wallet has earned, newest epoch first: how much, of what kind, from which pool, and when it could be spent.

**Inputs**

- Stake address (`stake_address`, text, required): The wallet's stake address (stake1...). Any of the wallet's addresses (addr1...) works too: its stake address is read from it.
- Epoch (`epoch`, number): Only rewards earned in this epoch. Leave empty for every epoch. From 0 to 100000.
- Number of results (`limit`, number): How many to return, 1 to 1,000. Defaults to 20. From 1 to 1000.
- Skip (`offset`, number): How many to skip, to read the next page: give the Number of results of the page before. Leave empty for the first page. At least 0.

**Outputs**

- `count` (number): How many rewards, newest epoch first came back.
- `rewards` (list): The rewards, newest epoch first.
- `stake_address` (text): The stake address read.
- `total_ada` (number): The rewards listed, added up, in ADA.

**Example output**

```json
{
  "count": 2,
  "rewards": [
    {
      "amount_ada": 34.220913,
      "amount_lovelace": "34220913",
      "earned_epoch": 663,
      "pool_id": "pool1mxqjlrfskhd5kql9kak06fpdh8xjwc76gec76p3taqy2qmfzs5z",
      "spendable_epoch": 665,
      "type": "member"
    },
    {
      "amount_ada": 939.413688,
      "amount_lovelace": "939413688",
      "earned_epoch": 663,
      "pool_id": "pool1mxqjlrfskhd5kql9kak06fpdh8xjwc76gec76p3taqy2qmfzs5z",
      "spendable_epoch": 665,
      "type": "leader"
    }
  ],
  "stake_address": "stake1uy6yzwsxxc28lfms0qmpxvyz9a7y770rtcqx9y96m42cttqwvp4m5",
  "total_ada": 2371.537618
}
```

### List token holders

List the addresses holding a Cardano token or NFT, with how much each holds and its stake address, in Koios's order (not by size). For a token held by a great many wallets the list can be too big for Koios's free service to make in time.

**Inputs**

- Token (`asset`, text, required): The token's fingerprint (asset1..., as wallets and explorers show it), or its policy ID followed by its name in hex.
- Number of results (`limit`, number): How many to return, 1 to 1,000. Defaults to 100. From 1 to 1000.
- Skip (`offset`, number): How many to skip, to read the next page: give the Number of results of the page before. Leave empty for the first page. At least 0.

**Outputs**

- `asset_name` (text): The token's name as hex.
- `asset_name_text` (text): The token's name as text.
- `count` (number): How many addresses holding the token came back.
- `decimals` (number): How many decimal places the token uses.
- `fingerprint` (text): The token's fingerprint (asset1...).
- `holders` (list): The addresses holding the token.
- `policy_id` (text): The token's policy ID.

**Example output**

```json
{
  "asset_name": "4c494f4e2043484144",
  "asset_name_text": "LION CHAD",
  "count": 2,
  "decimals": 0,
  "fingerprint": "asset1a2j64rgg5sxc56j6v76qw0k7qt5jk8zm84lcjq",
  "holders": [
    {
      "address": "addr1q80ukhmvgtm498e3h6pwpe52whpdh98yy4qfwup5zqg7lqz75jq4yvpskgayj55xegdp30g5rfynax66r8vgn9fldndskl33sd",
      "amount": 1000.0,
      "quantity": "1000",
      "stake_address": "stake1u902fq2jxqctywjf22rv5xsch52p5jf7nddpnkyfj5lkekcnnhvtv"
    },
    {
      "address": "addr1q824g7wr0jgrk4yamq7yp9f9c6zt53n6fc0qfjttqj6uuqs2wnq6j3l6c6zr8x4hzskhrskqw9klp0yl85jgx5lhjhesr33vrv",
      "amount": 1579201.0,
      "quantity": "1579201",
      "stake_address": "stake1uy98fsdfglavdppnn2m3gtt3ctq8zm0shj0n6fyr20metuc8xydzu"
    }
  ],
  "policy_id": "10eacc7b7aa4f433b2792bdeca0a5e84a45ff88ab576e1fbb8124c65"
}
```

### List wallet addresses

List the addresses of a Cardano wallet: every address that shares its stake address and holds something, or every one it has used.

**Inputs**

- Stake address (`stake_address`, text, required): The wallet's stake address (stake1...). Any of the wallet's addresses (addr1...) works too: its stake address is read from it.
- Include empty addresses (`include_empty`, true/false): Also list the wallet's addresses that hold nothing now. Default: `false`.

**Outputs**

- `addresses` (list): The addresses.
- `count` (number): How many addresses came back.
- `stake_address` (text): The stake address read.

**Example output**

```json
{
  "addresses": [
    "addr1qynpqguauxmgjryewdhzv7jdwl30p0v64uszz2vxtdpwtnp5gyaqvds507nhq7pkzvcgytmufau7xhsqv2gt4h24skkq946shd"
  ],
  "count": 1,
  "stake_address": "stake1uy6yzwsxxc28lfms0qmpxvyz9a7y770rtcqx9y96m42cttqwvp4m5"
}
```
