---
title: "Koios"
description: "Cardano over the Koios PostgREST API. Balances with totals. History and details. Native token holdings. Keyless and a little slow on busy addresses."
canonical_url: "https://explorers.agntn.dev/providers/koios"
---
# Koios

> Cardano over the Koios PostgREST API. Balances with totals. History and details. Native token holdings. Keyless and a little slow on busy addresses.

<provider-facts provider="koios">



</provider-facts>

## Address it

```ts
const koios = await create("koios");
await koios.getTokenBalances("addr1…", "cardano");
```

## What it reads

Koios answers on POST with the address or hash in the request body: `address_info` for the balance, `address_txs` then `tx_info` for history, `tx_info` for one transaction, `address_assets` for native token holdings.

## Gotchas

- The public instance rejects a body over 5120 bytes and one hash costs about 67 of them, so `getTxHistory` asks `tx_info` for seventy hashes at a time and reorders the answer, which comes back in the endpoint's own order.
- `address_info` ships the whole UTxO set of an address, 222 kB for a busy one. `getBalance` narrows the payload with the PostgREST `select` parameter, but the endpoint still builds the set before it answers, so a busy address takes seconds against the client timeout of fifteen. Slow, not broken.
- The phase-2 validity flag sits behind the heavier `_scripts` payload, so a transaction reads as `success` even when a failing script consumed its collateral. `isContractInteraction` comes from the presence of collateral inputs.
- Lovelace, six decimals. `funded` and `spent` are the address totals.

## Where it lives

`src/providers/koios.ts`.


## Sitemap

See the full [sitemap](https://explorers.agntn.dev/sitemap.md) for all pages.
