# Sai Keeper

Sai Keeper is a GraphQL API that provides real-time and historical data for the Sai protocol on Nibiru Chain. It enables developers to query perpetual trades, liquidity pool data, oracle prices, and fee analytics.

## What is Sai Keeper?

Sai Keeper is the data indexing and query layer for Sai Protocol. It processes on-chain events and makes them accessible through a fast, flexible GraphQL API.

**Key capabilities:**

* Query perpetual trading positions and history
* Access liquidity pool data and APY metrics
* Retrieve oracle price feeds
* Analyze fee structures and protocol revenue
* Subscribe to real-time updates via WebSockets

## Environments

### Testnet

* **GraphQL Endpoint**: `https://sai-keeper.testnet-2.nibiru.fi/graphql`
* **Interactive Playground**: `https://sai-keeper.testnet-2.nibiru.fi/`
* **Purpose**: Development and testing with test data
* Use for development and testing

### Mainnet

* **GraphQL Endpoint**: `https://sai-keeper.nibiru.fi/graphql`
* **Interactive Playground**: `https://sai-keeper.nibiru.fi/`
* **Purpose**: Production applications with real data
* Use for production applications

### Interactive User Interface

Both Testnet and Mainnet endpoints provide an **interactive GraphQL Playground** where you can:

* **Test all queries** with live data
* **Test subscriptions** with real-time updates
* **Explore the schema** with built-in documentation
* **View query history** and save queries
* **Debug responses** with formatted JSON

Simply visit the endpoint URLs in your browser to access the playground!

## Quick Start

### 1. Explore the API

Visit the GraphQL Playground to explore the schema interactively:

* **Testnet**: <https://sai-keeper.testnet-2.nibiru.fi/>
* **Mainnet**: <https://sai-keeper.nibiru.fi/>

### 2. Make Your First Query

Try this simple query in the playground:

```graphql
query GetTokenPrices {
  oracle {
    tokenPricesUsd(limit: 5) {
      token {
        symbol
        name
      }
      priceUsd
      lastUpdatedBlock {
        block
        block_ts
      }
    }
  }
}
```

### 3. Set Up Your Client

Install a GraphQL client library:

**JavaScript/TypeScript:**

```bash
npm install @apollo/client graphql
# or
npm install urql graphql
```

**Python:**

```bash
pip install gql[all]
```

**Rust:**

```toml
[dependencies]
graphql_client = "0.13"
```

## Core Data Domains

Sai Keeper organizes data into four main domains:

### 1. Perp (Perpetuals)

Query and subscribe to perpetual trading data:

* Open and closed positions
* Trade history and events
* Market borrowing rates

### 2. LP (Liquidity Pools)

Access liquidity provider information:

* Vault metrics (TVL, APY, share price)
* User deposits and shares
* Withdrawal requests
* Revenue tracking

### 3. Oracle

Get token price data:

* Real-time token prices in USD
* Token metadata
* Price update timestamps

### 4. Fee

Analyze fee data:

* Transaction-level fees
* Daily fee statistics
* Protocol and trader fee summaries
* Fee type breakdowns (opening/closing)

## GraphQL Basics

If you're new to GraphQL, here are the essentials:

### Queries

Request specific data:

```graphql
query {
  perp {
    trades(where: { trader: "nibi1abc..." }, limit: 10) {
      id
      isOpen
      leverage
    }
  }
}
```

### Subscriptions

Get real-time updates:

```graphql
subscription {
  perpTrades(where: { trader: "nibi1abc..." }) {
    id
    isOpen
    leverage
  }
}
```

### Variables

Parameterize your queries:

```graphql
query GetTrades($trader: String!, $limit: Int) {
  perp {
    trades(where: { trader: $trader }, limit: $limit) {
      id
    }
  }
}
```

Variables:

```json
{
  "trader": "nibi1abc...",
  "limit": 10
}
```

## Architecture Overview

```
┌─────────────────┐
│   Your App      │
│  (Frontend/     │
│   Backend)      │
└────────┬────────┘
         │
         │ GraphQL
         │ Query/Subscribe
         │
┌────────▼────────┐
│  Sai Keeper     │
│  GraphQL API    │
└────────┬────────┘
         │
         │ Indexes
         │
┌────────▼────────┐
│  Nibiru Chain   │
│  (Blockchain)   │
└─────────────────┘
```

Sai Keeper indexes blockchain data and provides it through a fast, queryable GraphQL interface. This means you don't need to query the blockchain directly or maintain your own indexer.

## What You Can Build

* **Trading Platforms**: Full-featured perpetual trading interfaces
* **Portfolio Trackers**: Monitor positions, PnL, and performance
* **Analytics Dashboards**: Visualize protocol metrics and user activity
* **Automated Bots**: Build trading algorithms with real-time data
* **LP Management Tools**: Optimize positions strategies

## Next Steps

* **New to GraphQL?** → Read [Core Concepts](/for-devs/sai-keeper/core-concepts.md)
* **Ready to code?** → Check out [Client Setup](/for-devs/sai-keeper/client-setup.md)
* **Want examples?** → See [Query Examples](/for-devs/sai-keeper/examples-queries.md)
* **Need API details?** → Browse the API references:
  * [Perp API](/for-devs/sai-keeper/api-perp.md)
  * [LP API](/for-devs/sai-keeper/api-lp.md)
  * [Oracle API](/for-devs/sai-keeper/api-oracle.md)
  * [Fee API](/for-devs/sai-keeper/api-fees.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sai.fun/for-devs/sai-keeper.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.