cardano-koios-client

TypeScript Client for XRAY/Graph Koios Tiny and Koios.REST API

Automatically generated Openapi-fetch (Axios) client for Koios Cardano RESTful API based on schema.yaml OpenAPI schema. Works great with XRAY/Graph Koios Tiny and the original Koios

Installation

To install the client with Yarn, run:

yarn install cardano-koios-client

To install the client with NPM, run:

npm i cardano-koios-client

Usage

import KoiosClient from "cardano-koios-client"

const client = KoiosClient("https://api.koios.rest/api/v1")

const app = async () => {
  const tip = await client.GET("/tip")

  if (tip.data) {
    console.log(tip.data?.[0]?.block_no)
  }
  if (tip.error) {
    console.error(tip.error)
  }
}

app()

Advanced Usage

Headers / Query Params

Read https://api.koios.rest/#overview--api-usage for more information

import KoiosClient from "cardano-koios-client"

const baseUrl = "https://api.koios.rest/api/v1"
const headers = {} // rest headers
const client = KoiosClient(baseUrl, headers)

const app = async () => {
  const blocks = await client.GET("/blocks", {
    headers: { "Content-Type": "application/json" }, // one shot headers
    params: { 
      query: { 
        limit: 1,
        offset: 100,
        epoch_no: "eq.250",
      },
    },
  })

  console.log(blocks.data)
}

app()

Request Cancellation (AbortSignal)

import KoiosClient from "cardano-koios-client"

const client = KoiosClient("https://api.koios.rest/api/v1")

const app = async () => {
  const abortController = new AbortController()

  setTimeout(() => {
    abortController.abort() // cancel request
    console.log('Aborted!')
  }, 200)

  const tip = await client.GET("/tip", {
    signal: abortController.signl,
  })

  if (tip.data) {
    console.log(tip.data?.[0]?.block_no)
  }
  if (tip.error) {
    console.error(tip.error)
  }
}

app()

Endpoints

• Check OpenAPI fetch documentations for available endpoint parameters: https://openapi-ts.pages.dev/openapi-fetch/
• The client uses OpenAPI definitions from the Koios configuration: koiosapi-mainnet.yaml
• A complete list of endpoints can be found here (RapiDoc): https://api.koios.rest

API URLs

Managed by Cardano Community (Koios Elastic Query Layer, HAproxy Balancer)

https://api.koios.rest/api/v1

https://preprod.koios.rest/api/v1

https://preview.koios.rest/api/v1

https://guild.koios.rest/api/v1

Managed by XRAY/Network (XRAY/Graph, Cloudflare WAF & Load Balancer)

https://graph.xray.app/output/koios/mainnet/api/v1

https://graph.xray.app/output/koios/preprod/api/v1

https://graph.xray.app/output/koios/preview/api/v1